@fusion.dev/helix-docs 0.107.0 → 0.108.0

package/content/metrics.mdx

@@ -403,7 +403,7 @@ stripped column shows the bytes we removed.
 | `@fusion.dev/helix-icons` | 150,162 | 21 | 50,346 | `svgo` |
 | `@fusion.dev/helix-styles` | 102,108 | 6 | 0 | none |
 | `@fusion.dev/helix-theme` | 465,413 | 8 | 4,703 | none |
-| `@fusion.dev/helix` | 14,179,532 | 868 | 362,883 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix` | 14,185,818 | 870 | 368,333 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/content/recipes.mdx

@@ -112,14 +112,40 @@ In prose:
 
 See [Typography](./typography).
 
-If you control the Markdown renderer, map two elements to components, because
-HTML alone cannot hold what they need:
-
-- **Fenced code** to `helix-code-block`, with the fence's language as its `label`.
-  A `<pre>` has no label or copy button.
-- **Alerts** such as `> [!WARNING]` to `helix-callout`. A `<blockquote>` has no
-  tone. `NOTE` and `IMPORTANT` become `tone="info"`, `TIP` becomes `success`,
-  `WARNING` becomes `warning`, and `CAUTION` becomes `danger`.
+Two Markdown constructs need components, because HTML alone cannot hold what
+they need:
+
+- **Fenced code** becomes `helix-code-block`, with the fence's language as its
+  `label`. A `<pre>` has no label or copy button.
+- **Alerts** such as `> [!WARNING]` become `helix-callout`. A `<blockquote>` has no
+  tone. `NOTE` becomes `tone="info"`, `TIP` becomes `success`, `WARNING` becomes
+  `warning`, and `CAUTION` becomes `danger`. `IMPORTANT` has no tone. Each
+  callout is headed by its kind, as GitHub shows it.
+
+The `rehype` plugin from `@fusion.dev/helix/rehype` makes both changes in the
+tree your Markdown library has already built. It parses nothing, so your
+library, its dialect, and your sanitizing stay yours. Add it to any pipeline
+that reaches rehype, such as `remark` with `remark-rehype`, `react-markdown`, or
+MDX:
+
+```js
+import rehypeHelix from '@fusion.dev/helix/rehype'
+
+const html = await unified()
+  .use(remarkParse)
+  .use(remarkRehype)
+  .use(rehypeHelix)
+  .use(rehypeStringify)
+  .process(markdown)
+```
+
+Code that a highlighter colored before the plugin ran keeps its colors. Pass
+`fences: false` if your page draws its own code blocks, `alerts: false` to keep
+alerts as quotes, and `headings` to name each kind in your page's language.
+
+> [!NOTE]
+> The plugin changes only these two constructs. If the Markdown comes from your
+> users, sanitize it in your pipeline before the plugin runs.
 
 Prose spaces each component the same as the element it replaces.
 

package/dist/sources.generated.js

@@ -3146,7 +3146,7 @@ stripped column shows the bytes we removed.
 | \`@fusion.dev/helix-icons\` | 150,162 | 21 | 50,346 | \`svgo\` |
 | \`@fusion.dev/helix-styles\` | 102,108 | 6 | 0 | none |
 | \`@fusion.dev/helix-theme\` | 465,413 | 8 | 4,703 | none |
-| \`@fusion.dev/helix\` | 14,179,532 | 868 | 362,883 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix\` | 14,185,818 | 870 | 368,333 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 
@@ -3894,14 +3894,40 @@ In prose:
 
 See [Typography](./typography).
 
-If you control the Markdown renderer, map two elements to components, because
-HTML alone cannot hold what they need:
+Two Markdown constructs need components, because HTML alone cannot hold what
+they need:
 
-- **Fenced code** to \`helix-code-block\`, with the fence's language as its \`label\`.
-  A \`<pre>\` has no label or copy button.
-- **Alerts** such as \`> [!WARNING]\` to \`helix-callout\`. A \`<blockquote>\` has no
-  tone. \`NOTE\` and \`IMPORTANT\` become \`tone="info"\`, \`TIP\` becomes \`success\`,
-  \`WARNING\` becomes \`warning\`, and \`CAUTION\` becomes \`danger\`.
+- **Fenced code** becomes \`helix-code-block\`, with the fence's language as its
+  \`label\`. A \`<pre>\` has no label or copy button.
+- **Alerts** such as \`> [!WARNING]\` become \`helix-callout\`. A \`<blockquote>\` has no
+  tone. \`NOTE\` becomes \`tone="info"\`, \`TIP\` becomes \`success\`, \`WARNING\` becomes
+  \`warning\`, and \`CAUTION\` becomes \`danger\`. \`IMPORTANT\` has no tone. Each
+  callout is headed by its kind, as GitHub shows it.
+
+The \`rehype\` plugin from \`@fusion.dev/helix/rehype\` makes both changes in the
+tree your Markdown library has already built. It parses nothing, so your
+library, its dialect, and your sanitizing stay yours. Add it to any pipeline
+that reaches rehype, such as \`remark\` with \`remark-rehype\`, \`react-markdown\`, or
+MDX:
+
+\`\`\`js
+import rehypeHelix from '@fusion.dev/helix/rehype'
+
+const html = await unified()
+  .use(remarkParse)
+  .use(remarkRehype)
+  .use(rehypeHelix)
+  .use(rehypeStringify)
+  .process(markdown)
+\`\`\`
+
+Code that a highlighter colored before the plugin ran keeps its colors. Pass
+\`fences: false\` if your page draws its own code blocks, \`alerts: false\` to keep
+alerts as quotes, and \`headings\` to name each kind in your page's language.
+
+> [!NOTE]
+> The plugin changes only these two constructs. If the Markdown comes from your
+> users, sanitize it in your pipeline before the plugin runs.
 
 Prose spaces each component the same as the element it replaces.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-docs",
   "description": "Versioned documentation content and registry for Helix.",
-  "version": "0.107.0",
+  "version": "0.108.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -36,8 +36,8 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.107.0",
-    "@fusion.dev/helix-testing": "0.107.0",
+    "@fusion.dev/helix-cem": "0.108.0",
+    "@fusion.dev/helix-testing": "0.108.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.62.1"