Product Decisions This Supports

Content Management & Collaboration Tools: Enables seamless Markdown support for blog platforms, documentation systems (e.g., internal wikis, API docs), or community-driven content (e.g., forums, Q&A). Reduces reliance on WYSIWYG editors by leveraging lightweight Markdown for structured content.
Developer Experience (DX) Improvements: Accelerates development of admin panels or CMS backends where content editors need Markdown support (e.g., GitHub-flavored syntax for code blocks, tables, or task lists). Aligns with modern developer workflows (e.g., VS Code Markdown previews).
Roadmap: "Composable Content" Initiative: Supports a phased rollout of Markdown as a first-class citizen in content pipelines, with future extensions for:
- Dynamic rendering: Cache-busting per-converter configurations (e.g., github vs. commonmark).
- API-driven content: Expose converters as GraphQL/Microservice endpoints for headless CMS integrations.
- Collaboration features: Real-time Markdown previews (via WebSocket + Alpine.js) using the empty converter for custom extensions (e.g., mentions, emoji).
Build vs. Buy:
- Buy: Justifies outsourcing Markdown parsing to a battle-tested library (league/commonmark) with Symfony-native integration, avoiding reinventing wheel for core functionality.
- Build: Only if needing highly specialized extensions (e.g., custom syntax for domain-specific languages) or offline/edge rendering (e.g., PWA apps). This bundle’s extensions key provides a low-friction path to customize without forking.
Use Cases:
- Internal Tools: Developer portals, runbooks, or knowledge bases where Markdown’s simplicity reduces friction.
- Public-Facing: Lightweight blogs or documentation sites (e.g., blog_post_converter with HeadingPermalinkExtension for SEO-friendly URLs).
- Hybrid Workflows: Allow users to draft in Markdown (via API) but render as HTML/CSS in templates (e.g., {{ content|commonmark('blog_post_converter') }}).

When to Consider This Package

Adopt if:
- Your Symfony app (4.4+) needs Markdown parsing with minimal setup (1-line Composer install + YAML config).
- You require multiple converter profiles (e.g., GitHub-flavored for code-heavy content, standard CommonMark for blogs).
- Your team prioritizes developer velocity over pixel-perfect WYSIWYG (e.g., Markdown is sufficient for 80% of use cases).
- You’re building a content-heavy app where Markdown reduces boilerplate (e.g., no need for <div class="code-block"> wrappers).
- You need Twig integration without manual service wiring (e.g., {{ markdown|commonmark('converter_name') }}).
Look elsewhere if:
- You need real-time collaborative editing (e.g., Google Docs-style). This bundle is for rendering, not live editing.
- Your app requires Markdown-to-PDF/LaTeX or other non-HTML outputs. Use league/commonmark directly or pair with a dedicated tool like knplabs/knp-snappy-bundle.
- You’re on Symfony <4.4 or PHP <7.4. This bundle has hard dependencies.
- You need advanced syntax (e.g., Mermaid diagrams, custom blockquotes). Extend via extensions key, but some use cases may require a dedicated parser.
- Your content is highly dynamic (e.g., user-generated with arbitrary HTML/JS). Sanitize input separately (e.g., with symfony/security-csrf or htmlpurifier).
- You’re building a static site generator (e.g., Jekyll alternative). Use league/commonmark directly or tools like spatie/laravel-markdown.

How to Pitch It (Stakeholders)

For Executives:

"This bundle lets us ship Markdown support in hours, not weeks*, by leveraging a Symfony-native wrapper for the industry-standard league/commonmark library. For example:

Blogs/Docs: Launch a developer portal with GitHub-flavored Markdown in 1 day (vs. weeks with a custom solution).
Cost Savings: Avoid licensing fees for proprietary WYSIWYG editors while improving editor DX (Markdown is faster to write than HTML).
Scalability: Handle 10x more content authors with lightweight Markdown files (e.g., stored in S3) vs. bloated database-driven CMS.
Future-Proof: Aligns with our ‘composable content’ roadmap—add extensions like tables-of-contents or math rendering as needed. Risk: Minimal—MIT-licensed, used in production by 7+ repos (per GitHub stars), and backed by the League’s CommonMark team."*

For Engineering:

*"This is a drop-in solution for Markdown in Symfony that:

Reduces boilerplate: No need to manually configure league/commonmark or wire Twig filters. Just add YAML:

aymdev_commonmark:
    converters:
        github_code:
            type: github
            extensions:
                - League\CommonMark\Extension\TableOfContents\TableOfContentsExtension

Supports multiple profiles: Use github for code blocks, commonmark for blogs, or empty for custom extensions (e.g., custom syntax).
Performs well: Service locator in Twig (since v1.3.0) avoids constructor bloat. CI includes PHPStan for quality.
Extensible: Add any CommonMark extension (e.g., AutolinkExtension, StrikethroughExtension).
Future-safe: Works with Symfony 4–6 and PHP 7.4–8.0. Upgrade path is clear. Tradeoffs:

No real-time editing (use a frontend lib like easymde for that).
Limited to HTML output (pair with knp-snappy for PDFs if needed). Action: Let’s prototype this for the blog redesign—it’ll let us A/B test Markdown vs. TinyMCE without big upfront work."*

For Design/Product:

*"This gives us superpowers for content:

Faster iteration: Markdown is easier to write than HTML/CSS. Example: A dev can draft a doc in 5 mins vs. 30 mins with a WYSIWYG.
Consistency: Enforce a single source of truth (e.g., .md files in Git) vs. scattered CMS entries.
Flexibility: Use GitHub-flavored syntax for code snippets (e.g., ```python) or standard Markdown for blogs.
SEO-friendly: Extensions like HeadingPermalinkExtension auto-generate clean URLs (e.g., /docs#installation). Example: For our API docs, we can let engineers write in Markdown and render it with syntax highlighting—no more fighting with <pre> tags. Ask: Should we prioritize this for the blog or the internal wiki first?"*

Commonmark Bundle Laravel Package