[Site] Rework Toolkit recipe rendering system, improve our Markdown converter #3256

Kocal · 2025-12-30T22:54:25Z

Q	A
Bug fix?	no
New feature?	no
Deprecations?	no
Documentation?	no
Issues	Fix #...
License	MIT

This PR aims to improve the UX and DX, on the recipe page and how it's generated.

Before, the page was generated by a Twig Component that rendered Markdown with some HTML inside. It was very hacky, because inserting raw HTML in a Markdown can be difficult and came with costs, you need to be super careful about newlines and cie.

Now, the page is still generated by a Twig Component, but it only render raw Markdown. The Markdown is then properly parsed and interpreted by the PHPLeague CommonMark system. With some custom extensions, it is now possible to easily render tabs and Toolkit example preview without any issue.

In a markdown, it is possible to render tabs with:

::: tabs 

:: Title 1

Hello world

:: Title 2

(...)

:::

The Toolkit_Tab* components have been renamed to `Wysiwyg_Tab* in order to make them generic.

In a markdown, it is possible to render a Toolkit exemple preview with:

[toolkit-preview {"kitId": "shadcn"}]
<twig:FooBar />
[/toolkit-preview]

I also added a new component CodeBlockInline, because the actual CodeBlock was hard to use to render inline code.

A super-minimal Bash language support has been added to Tempest, in order to add some colors to Bash code.

Before/after: the commands are highlighted, and copy/pastable too!

Before/after: the commands about packages dependencies are moved above, the files are not rendered in <details> tags anymore because copy/pasting the filename was super-hard. Now, they are rendered in dedicated code-blocks, fully-expanded, with a filename and a copy button:

Kocal · 2025-12-30T23:14:30Z

src/Toolkit/src/Recipe/RecipeManifest.php

+                // format: "package@version", "@scope/package", "@scope/package@version"
+                $name = $package;
+                $version = null;
+                $versionPos = strrpos($package, '@');
+                if (false !== $versionPos && 0 !== $versionPos) {
+                    $name = substr($package, 0, $versionPos);
+                    $version = substr($package, $versionPos + 1);
+                }
+
+                if (null !== $version) {
                    $dependencies[] = new NpmPackageDependency($name, new ConstraintVersion($version));
                } else {
-                    $dependencies[] = new NpmPackageDependency($package);
+                    $dependencies[] = new NpmPackageDependency($name);


Small bug, must have been cherry-picked 🙈

Kocal · 2025-12-30T23:18:36Z

ux.symfony.com/src/Service/UxPackageRepository.php

+                '#64748b',
+                'linear-gradient(142deg, #334155 -15%, #64748b 95%)',


I wasn't fan anymore about this color and gradient, and we already have 5/6 blue-colored packages.

Changing it to grey make it more "generic", more "basic", like the base Toolkit provides to create a design system.

Before:

After:

(I'm open to suggestions btw)

ux.symfony.com/src/Util/SourceCleaner.php

Copilot

Pull request overview

This PR refactors the Toolkit recipe rendering system by replacing hacky HTML-in-Markdown with proper CommonMark extensions. The changes improve developer experience by making Markdown templates cleaner and more maintainable, while adding support for tabs and toolkit preview rendering through custom CommonMark parsers.

Key changes:

Introduced CommonMark extensions for tabs and toolkit preview rendering with custom parsers, nodes, and renderers
Refactored ToolkitService to extract reusable methods and simplified the markdown generation logic
Added Shell/Bash syntax highlighting support with command, comment, and option patterns
Renamed Toolkit_Tab* components to Wysiwyg_Tab* for better semantic clarity

Reviewed changes

Copilot reviewed 41 out of 41 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
`ux.symfony.com/templates/toolkit/recipe/_previewable_code_block.md.twig`	New template for rendering code blocks with preview tabs
`ux.symfony.com/templates/toolkit/recipe/_code_block.md.twig`	New template for rendering simple code blocks
`ux.symfony.com/templates/toolkit/_component.md.twig`	New unified markdown template for component documentation
`ux.symfony.com/templates/components/Toolkit/Tabs.html.twig`	Renamed tab component with updated CSS classes
`ux.symfony.com/templates/components/Toolkit/Tab/Panel.html.twig`	Tab panel component with Wysiwyg naming
`ux.symfony.com/templates/components/Toolkit/Tab/Control.html.twig`	Tab control component with updated structure
`ux.symfony.com/templates/components/Toolkit/ComponentDoc.html.twig`	Simplified to use `markdownContent` property
`ux.symfony.com/templates/components/Code/CodeBlockInline.html.twig`	New inline code block component with copy functionality
`ux.symfony.com/src/Util/SourceCleaner.php`	Removed obsolete `cleanupTwigFile` method
`ux.symfony.com/src/Twig/Components/Toolkit/ComponentDoc.php`	Refactored to use Twig templates for markdown generation
`ux.symfony.com/src/Twig/Components/Code/CodeBlockInline.php`	New component class for inline code blocks
`ux.symfony.com/src/Twig/Components/Code/CodeBlock.php`	Removed Twig file cleanup logic
`ux.symfony.com/src/Service/UxPackageRepository.php`	Updated Toolkit package colors
`ux.symfony.com/src/Service/Toolkit/ToolkitService.php`	Refactored to extract recipe data methods and made class readonly
`ux.symfony.com/src/Service/Tempest/Highlighter/HighlighterFactory.php`	Factory for creating Tempest highlighter with custom languages
`ux.symfony.com/src/Service/Tempest/Highlighter/Languages/Shell/ShellLanguage.php`	Shell language support for syntax highlighting
`ux.symfony.com/src/Service/Tempest/Highlighter/Languages/Shell/Patterns/*.php`	Shell patterns for commands, comments, and options
`ux.symfony.com/src/Service/CommonMark/Extension/ToolkitPreview/*.php`	CommonMark extension for toolkit preview blocks
`ux.symfony.com/src/Service/CommonMark/Extension/Tabs/*.php`	CommonMark extension for tabs rendering
`ux.symfony.com/src/Service/CommonMark/Extension/FencedCode/FencedCodeRenderer.php`	New renderer using CodeBlockInline component
`ux.symfony.com/src/Service/CommonMark/Extension/CodeBlockRenderer/CodeBlockRenderer.php`	Removed old code block renderer
`ux.symfony.com/src/Service/CommonMark/ConverterFactory.php`	Updated to register new CommonMark extensions
`ux.symfony.com/config/services.yaml`	Added factory for Tempest Highlighter
`ux.symfony.com/assets/styles/components/_Wysiwyg_Tabs.scss`	New styles for Wysiwyg tabs
`ux.symfony.com/assets/styles/components/_Toolkit.scss`	Extracted Toolkit-specific styles
`ux.symfony.com/assets/styles/components/_Toolkit_Tabs.scss`	Removed old Toolkit tabs styles
`ux.symfony.com/assets/styles/components/_Wysiwyg.scss`	Updated with Terminal margin and link selector
`ux.symfony.com/assets/styles/app.scss`	Fixed typo and updated imports
`src/Toolkit/src/Recipe/RecipeManifest.php`	Fixed npm dependency parsing for scoped packages without versions
`src/Toolkit/tests/Recipe/RecipeManifestTest.php`	Added test case for scoped package without version

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ux.symfony.com/src/Twig/Components/Toolkit/ComponentDoc.php

ux.symfony.com/src/Service/CommonMark/Extension/ToolkitPreview/Parser/ToolkitPreviewParser.php

ux.symfony.com/src/Twig/Components/Toolkit/ComponentDoc.php

ux.symfony.com/src/Twig/Components/Code/CodeBlockInline.php

ux.symfony.com/src/Service/CommonMark/Extension/ToolkitPreview/Parser/ToolkitPreviewParser.php

ux.symfony.com/src/Service/Tempest/Highlighter/Languages/Shell/Patterns/ShellCommandPattern.php

ux.symfony.com/src/Service/CommonMark/Extension/ToolkitPreview/Parser/ToolkitPreviewParser.php

ux.symfony.com/templates/components/Toolkit/Tab/Control.html.twig

ux.symfony.com/assets/styles/components/_Wysiwyg_Tabs.scss

…der (Kocal) This PR was merged into the 2.x branch. Discussion ---------- [*CS-Fixer] Ensure "apps/" exists before adding it in Finder | Q | A | -------------- | --- | Bug fix? | no | New feature? | no  | Deprecations? | no  | Documentation? | no  | Issues | Fix #...  | License | MIT  Follow #3251, I noticed in #3256 that Fabbot is failing because the Finder used by PHP-CS-Fixer throw an error because the directory `apps/` does not exist (https://github.com/symfony/ux/actions/runs/20607943823/job/59187283446?pr=3256#step:4:25). Indeed, I didn't modified any files from `apps/` folder in this PR, and it looks like `Finder::in()` throws an exception when the path does not exist. Commits ------- 0e355fe [*CS-Fixer] Ensure "apps/" exists before adding it in Finder

…onverter

Kocal self-assigned this Dec 30, 2025

carsonbot added Site ux.symfony.com Status: Needs Review Needs to be reviewed labels Dec 30, 2025

Kocal force-pushed the site-toolkit-ui-improvments branch from 8cecca4 to b9a35bf Compare December 30, 2025 23:14

Kocal requested a review from Copilot December 30, 2025 23:14

Kocal commented Dec 30, 2025

View reviewed changes

Copilot started reviewing on behalf of Kocal December 30, 2025 23:14 View session

Kocal commented Dec 30, 2025

View reviewed changes

ux.symfony.com/src/Util/SourceCleaner.php Show resolved Hide resolved

Kocal force-pushed the site-toolkit-ui-improvments branch from b9a35bf to a95eee5 Compare December 30, 2025 23:20

Copilot AI reviewed Dec 30, 2025

View reviewed changes

Kocal force-pushed the site-toolkit-ui-improvments branch from a95eee5 to 513877a Compare December 31, 2025 07:08

Kocal mentioned this pull request Dec 31, 2025

[*CS-Fixer] Ensure "apps/" exists before adding it in Finder #3257

Merged

[Site] Rework Toolkit recipe rendering system, improve our Markdown c…

b7587ef

…onverter

Kocal force-pushed the site-toolkit-ui-improvments branch from 513877a to b7587ef Compare December 31, 2025 07:35

Kocal merged commit a073116 into symfony:2.x Jan 1, 2026
27 of 29 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[Site] Rework Toolkit recipe rendering system, improve our Markdown converter #3256

[Site] Rework Toolkit recipe rendering system, improve our Markdown converter #3256

Uh oh!

Kocal commented Dec 30, 2025 •

edited

Loading

Uh oh!

Kocal Dec 30, 2025

Uh oh!

Kocal Dec 30, 2025

Uh oh!

Kocal Dec 31, 2025

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		'#64748b',
		'linear-gradient(142deg, #334155 -15%, #64748b 95%)',

Uh oh!

[Site] Rework Toolkit recipe rendering system, improve our Markdown converter #3256

[Site] Rework Toolkit recipe rendering system, improve our Markdown converter #3256

Uh oh!

Conversation

Kocal commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kocal Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Kocal Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Kocal Dec 31, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Kocal commented Dec 30, 2025 •

edited

Loading