doccupine 0.0.124 → 0.0.126

package/dist/templates/mdx/mermaid.mdx.d.ts

@@ -0,0 +1 @@
+export declare const mermaidMdxTemplate = "---\ntitle: \"Mermaid\"\ndescription: \"Create flowcharts, sequence diagrams, and other visualizations using Mermaid syntax.\"\ndate: \"2026-07-16\"\ncategory: \"Components\"\ncategoryOrder: 1\norder: 16\n---\n\n# Mermaid\n\nCreate flowcharts, sequence diagrams, and other visualizations using Mermaid syntax with automatic rendering.\n\nWrite a diagram inside a `mermaid` code fence and it renders as an SVG:\n\n````mdx\n```mermaid\nflowchart LR\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Action]\n  B -->|No| D[End]\n```\n````\n\n```mermaid\nflowchart LR\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Action]\n  B -->|No| D[End]\n```\n\nDiagrams are rendered when your site is built, so no diagramming library is shipped to your readers' browsers. They are drawn with your theme's colors and follow the light and dark toggle automatically.\n\n## Supported diagram types\n\nDoccupine renders diagrams with [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid), which supports six diagram types:\n\n| Type | Opening keyword |\n| --- | --- |\n| Flowchart | `flowchart` or `graph` |\n| Sequence | `sequenceDiagram` |\n| State | `stateDiagram-v2` |\n| Class | `classDiagram` |\n| Entity relationship | `erDiagram` |\n| XY chart | `xychart-beta` |\n\nOther Mermaid diagram types - including `pie`, `gantt`, `mindmap`, `journey`, and `gitGraph` - are not supported. A diagram that cannot be rendered falls back to a plain code block showing its source, and the reason is logged when your site builds. A broken diagram never breaks the page.\n\n## Examples\n\n### Sequence diagram\n\n```mermaid\nsequenceDiagram\n  participant Reader\n  participant Docs\n  participant Search\n  Reader->>Docs: Open a page\n  Docs->>Search: Index the content\n  Search-->>Reader: Return results\n```\n\n### Subgraphs\n\n```mermaid placement=\"top-right\"\nflowchart LR\n  subgraph one\n    direction TB\n    top1[top] --> bottom1[bottom]\n  end\n  subgraph two\n    direction TB\n    top2[top] --> bottom2[bottom]\n  end\n  outside --> one\n  outside --> top2\n```\n\n## Interactive controls\n\nDiagrams include zoom in and out, pan in four directions, reset the view, and full screen. You can also drag a diagram with your mouse to move it around.\n\nBy default the controls appear once a diagram is taller than 120px, since a diagram that already fits does not need them. Use the `actions` property to decide explicitly. Setting `actions={false}` turns off the whole interactive layer, including dragging.\n\n## Properties\n\n<Field value=\"placement\" type=\"string\">\n  Where the controls sit. One of `top-left`, `top-right`, `bottom-left`, or `bottom-right`. Defaults to `bottom-right`.\n</Field>\n\n<Field value=\"actions\" type=\"boolean\">\n  Show or hide the controls. When set, this overrides the default behavior of showing them only on diagrams taller than 120px.\n</Field>\n\nSet properties on the opening fence, after the language:\n\n````mdx\n```mermaid placement=\"top-left\" actions={true}\nflowchart LR\n  A --> B\n```\n````\n\nTo hide the controls entirely:\n\n````mdx\n```mermaid actions={false}\nflowchart LR\n  A --> B\n```\n````\n\n```mermaid actions={false}\nflowchart LR\n  A --> B\n```\n\n## Layout\n\nDiagrams are laid out with the [ELK](https://eclipse.dev/elk/) engine, which arranges nodes to reduce overlapping edges and keep large diagrams readable. It is always on, so no directive is needed to enable it.\n\nIf you are porting diagrams from another tool, a `%%{init: ...}%%` directive is read as a comment and ignored rather than causing an error.\n\n## Theming\n\nDiagram colors come from CSS variables, so they follow your theme and the light/dark toggle without re-rendering. Override any of them in your own CSS to restyle diagrams:\n\n```css\n:root {\n  --mermaid-bg: var(--color-light);\n  --mermaid-fg: var(--color-dark);\n  --mermaid-line: var(--color-grayDark);\n  --mermaid-accent: var(--color-accent);\n  --mermaid-muted: var(--color-grayDark);\n  --mermaid-surface: var(--color-grayLight);\n  --mermaid-border: var(--color-gray);\n}\n```\n\n## Syntax reference\n\nFor the syntax of each supported diagram type, see the [Mermaid documentation](https://mermaid.js.org/intro/). Keep to the six types listed above.";

package/dist/templates/mdx/mermaid.mdx.js

@@ -0,0 +1,142 @@
+export const mermaidMdxTemplate = `---
+title: "Mermaid"
+description: "Create flowcharts, sequence diagrams, and other visualizations using Mermaid syntax."
+date: "2026-07-16"
+category: "Components"
+categoryOrder: 1
+order: 16
+---
+
+# Mermaid
+
+Create flowcharts, sequence diagrams, and other visualizations using Mermaid syntax with automatic rendering.
+
+Write a diagram inside a \`mermaid\` code fence and it renders as an SVG:
+
+\`\`\`\`mdx
+\`\`\`mermaid
+flowchart LR
+  A[Start] --> B{Decision}
+  B -->|Yes| C[Action]
+  B -->|No| D[End]
+\`\`\`
+\`\`\`\`
+
+\`\`\`mermaid
+flowchart LR
+  A[Start] --> B{Decision}
+  B -->|Yes| C[Action]
+  B -->|No| D[End]
+\`\`\`
+
+Diagrams are rendered when your site is built, so no diagramming library is shipped to your readers' browsers. They are drawn with your theme's colors and follow the light and dark toggle automatically.
+
+## Supported diagram types
+
+Doccupine renders diagrams with [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid), which supports six diagram types:
+
+| Type | Opening keyword |
+| --- | --- |
+| Flowchart | \`flowchart\` or \`graph\` |
+| Sequence | \`sequenceDiagram\` |
+| State | \`stateDiagram-v2\` |
+| Class | \`classDiagram\` |
+| Entity relationship | \`erDiagram\` |
+| XY chart | \`xychart-beta\` |
+
+Other Mermaid diagram types - including \`pie\`, \`gantt\`, \`mindmap\`, \`journey\`, and \`gitGraph\` - are not supported. A diagram that cannot be rendered falls back to a plain code block showing its source, and the reason is logged when your site builds. A broken diagram never breaks the page.
+
+## Examples
+
+### Sequence diagram
+
+\`\`\`mermaid
+sequenceDiagram
+  participant Reader
+  participant Docs
+  participant Search
+  Reader->>Docs: Open a page
+  Docs->>Search: Index the content
+  Search-->>Reader: Return results
+\`\`\`
+
+### Subgraphs
+
+\`\`\`mermaid placement="top-right"
+flowchart LR
+  subgraph one
+    direction TB
+    top1[top] --> bottom1[bottom]
+  end
+  subgraph two
+    direction TB
+    top2[top] --> bottom2[bottom]
+  end
+  outside --> one
+  outside --> top2
+\`\`\`
+
+## Interactive controls
+
+Diagrams include zoom in and out, pan in four directions, reset the view, and full screen. You can also drag a diagram with your mouse to move it around.
+
+By default the controls appear once a diagram is taller than 120px, since a diagram that already fits does not need them. Use the \`actions\` property to decide explicitly. Setting \`actions={false}\` turns off the whole interactive layer, including dragging.
+
+## Properties
+
+<Field value="placement" type="string">
+  Where the controls sit. One of \`top-left\`, \`top-right\`, \`bottom-left\`, or \`bottom-right\`. Defaults to \`bottom-right\`.
+</Field>
+
+<Field value="actions" type="boolean">
+  Show or hide the controls. When set, this overrides the default behavior of showing them only on diagrams taller than 120px.
+</Field>
+
+Set properties on the opening fence, after the language:
+
+\`\`\`\`mdx
+\`\`\`mermaid placement="top-left" actions={true}
+flowchart LR
+  A --> B
+\`\`\`
+\`\`\`\`
+
+To hide the controls entirely:
+
+\`\`\`\`mdx
+\`\`\`mermaid actions={false}
+flowchart LR
+  A --> B
+\`\`\`
+\`\`\`\`
+
+\`\`\`mermaid actions={false}
+flowchart LR
+  A --> B
+\`\`\`
+
+## Layout
+
+Diagrams are laid out with the [ELK](https://eclipse.dev/elk/) engine, which arranges nodes to reduce overlapping edges and keep large diagrams readable. It is always on, so no directive is needed to enable it.
+
+If you are porting diagrams from another tool, a \`%%{init: ...}%%\` directive is read as a comment and ignored rather than causing an error.
+
+## Theming
+
+Diagram colors come from CSS variables, so they follow your theme and the light/dark toggle without re-rendering. Override any of them in your own CSS to restyle diagrams:
+
+\`\`\`css
+:root {
+  --mermaid-bg: var(--color-light);
+  --mermaid-fg: var(--color-dark);
+  --mermaid-line: var(--color-grayDark);
+  --mermaid-accent: var(--color-accent);
+  --mermaid-muted: var(--color-grayDark);
+  --mermaid-surface: var(--color-grayLight);
+  --mermaid-border: var(--color-gray);
+}
+\`\`\`
+
+## Syntax reference
+
+For the syntax of each supported diagram type, see the [Mermaid documentation](https://mermaid.js.org/intro/). Keep to the six types listed above.`;

package/dist/templates/mdx/navigation.mdx.d.ts

@@ -1 +1 @@
-export declare const navigationMdxTemplate = "---\ntitle: \"Navigation\"\ndescription: \"Organize and structure your navigation.\"\ndate: \"2026-02-19\"\ncategory: \"Configuration\"\ncategoryOrder: 3\norder: 2\n---\n\n# Navigation\n\nDoccupine builds your sidebar automatically from your MDX pages. By default, it reads the page frontmatter and groups pages into categories in the order you define. For larger docs, you can take full control with a `navigation.json` file.\n\n## Automatic navigation (default)\n\nWhen no custom navigation is provided, Doccupine generates a structure based on each page's frontmatter.\n\n### Frontmatter fields\n\n- **category**: The category name that groups the page in the sidebar.\n- **categoryOrder**: The position of the category within the sidebar. Lower numbers appear first.\n- **order**: The position of the page within its category. Lower numbers appear first.\n- **navIcon**: Optional [Lucide](https://lucide.dev/icons) icon name shown next to the page's sidebar link.\n- **categoryIcon**: Optional Lucide icon name for the page's category header. The first page in a category that sets it wins.\n\n### Example frontmatter\n\n```text\n---\ntitle: \"Navigation\"\ndescription: \"Organize and structure your navigation.\"\ndate: \"2025-01-15\"\ncategory: \"Configuration\"\ncategoryOrder: 3\norder: 2\n---\n```\n\nThis approach is great for small sets of documents. For larger projects, setting these fields on every page can become repetitive.\n\n## Custom navigation with navigation.json\n\nTo centrally define the entire sidebar, create a `navigation.json` at your project root (the same directory where you execute `npx doccupine`). When present, it takes priority over page frontmatter and fully controls the navigation structure.\n\n### Array format\n\nThe simplest format is an array of categories. When using [sections](/sections), this applies to the root section only.\n\n```json\n[\n  {\n    \"label\": \"Getting Started\",\n    \"links\": [\n      { \"slug\": \"\", \"title\": \"Introduction\" },\n      { \"slug\": \"commands\", \"title\": \"Commands\" }\n    ]\n  },\n  {\n    \"label\": \"Components\",\n    \"links\": [\n      { \"slug\": \"components\", \"title\": \"Components\" },\n      { \"slug\": \"headers-and-text\", \"title\": \"Headers and Text\" },\n      { \"slug\": \"lists-and-tables\", \"title\": \"Lists and tables\" },\n      { \"slug\": \"code\", \"title\": \"Code\" },\n      { \"slug\": \"accordion\", \"title\": \"Accordion\" },\n      { \"slug\": \"tabs\", \"title\": \"Tabs\" },\n      { \"slug\": \"cards\", \"title\": \"Cards\" },\n      { \"slug\": \"buttons\", \"title\": \"Buttons\" },\n      { \"slug\": \"callouts\", \"title\": \"Callouts\" },\n      { \"slug\": \"image-and-embeds\", \"title\": \"Images and embeds\" },\n      { \"slug\": \"icons\", \"title\": \"Icons\" },\n      { \"slug\": \"fields\", \"title\": \"Fields\" },\n      { \"slug\": \"update\", \"title\": \"Update\" },\n      { \"slug\": \"columns\", \"title\": \"Columns\" },\n      { \"slug\": \"steps\", \"title\": \"Steps\" },\n      { \"slug\": \"color-swatches\", \"title\": \"Color Swatches\" }\n    ]\n  },\n  {\n    \"label\": \"Configuration\",\n    \"links\": [\n      { \"slug\": \"globals\", \"title\": \"Globals\" },\n      { \"slug\": \"navigation\", \"title\": \"Navigation\" },\n      { \"slug\": \"sections\", \"title\": \"Sections\" },\n      { \"slug\": \"footer-links\", \"title\": \"Footer Links\" },\n      { \"slug\": \"theme\", \"title\": \"Theme\" },\n      { \"slug\": \"media-and-assets\", \"title\": \"Media and assets\" },\n      { \"slug\": \"fonts\", \"title\": \"Fonts\" },\n      { \"slug\": \"ai-assistant\", \"title\": \"AI Assistant\" },\n      { \"slug\": \"model-context-protocol\", \"title\": \"Model Context Protocol\" },\n      { \"slug\": \"analytics\", \"title\": \"Analytics\" },\n      { \"slug\": \"deployment-and-hosting\", \"title\": \"Deployment & Hosting\" },\n      { \"slug\": \"authentication\", \"title\": \"Authentication\" }\n    ]\n  }\n]\n```\n\n### Object format (per-section)\n\nWhen using [sections](/sections), you can define navigation for each section by using an object keyed by section slug. Sections without a key fall back to auto-generated navigation from frontmatter.\n\n```json\n{\n  \"\": [\n    {\n      \"label\": \"General\",\n      \"links\": [\n        { \"slug\": \"\", \"title\": \"Getting Started\" },\n        { \"slug\": \"commands\", \"title\": \"Commands\" }\n      ]\n    }\n  ],\n  \"platform\": [\n    {\n      \"label\": \"Overview\",\n      \"links\": [\n        { \"slug\": \"platform/auth\", \"title\": \"Authentication\" },\n        { \"slug\": \"platform/users\", \"title\": \"Users\" }\n      ]\n    }\n  ]\n}\n```\n\nThe key `\"\"` controls the root section. Other keys match section slugs defined in `sections.json` or derived from frontmatter. See [Sections](/sections) for details on configuring sections.\n\n### Fields\n\n- **label**: The section header shown in the sidebar.\n- **icon**: Optional [Lucide](https://lucide.dev/icons) icon name shown next to the category header.\n- **links**: An array of page entries for that section.\n  - **slug**: The MDX file slug (filename without extension). Use an empty string `\"\"` for `index.mdx`.\n  - **title**: The display title in the navigation. This can differ from the page's `title` frontmatter.\n  - **icon**: Optional Lucide icon name shown next to the link.\n  - **links**: Optional array of nested child links. See [Nested navigation](#nested-navigation).\n\n## Icons\n\nAdd icons to categories and links to make the sidebar easier to scan. Icons use [Lucide](https://lucide.dev/icons) names in kebab-case (e.g. `rocket`, `book-open`, `settings`). Unknown names render nothing, so a typo never breaks the build.\n\nWith frontmatter, set `navIcon` on a page for its sidebar link and `categoryIcon` for its category:\n\n```text\n---\ntitle: \"Introduction\"\ncategory: \"Getting Started\"\ncategoryOrder: 1\norder: 1\nnavIcon: \"rocket\"\ncategoryIcon: \"book-open\"\n---\n```\n\nWith `navigation.json`, add an `icon` to any category or link:\n\n```json\n[\n  {\n    \"label\": \"Getting Started\",\n    \"icon\": \"book-open\",\n    \"links\": [\n      { \"slug\": \"\", \"title\": \"Introduction\", \"icon\": \"rocket\" },\n      { \"slug\": \"commands\", \"title\": \"Commands\", \"icon\": \"terminal\" }\n    ]\n  }\n]\n```\n\n## Nested navigation\n\nA link in `navigation.json` can hold its own `links` array to create a collapsible group. Groups expand and collapse on click and open automatically when one of their pages is active. Nesting can go as deep as you need.\n\n```json\n[\n  {\n    \"label\": \"Guides\",\n    \"icon\": \"book-open\",\n    \"links\": [\n      { \"slug\": \"guides\", \"title\": \"Overview\", \"icon\": \"compass\" },\n      {\n        \"title\": \"Advanced\",\n        \"icon\": \"settings\",\n        \"links\": [\n          { \"slug\": \"guides/caching\", \"title\": \"Caching\" },\n          { \"slug\": \"guides/streaming\", \"title\": \"Streaming\" }\n        ]\n      }\n    ]\n  }\n]\n```\n\nA group can be a plain label - omit `slug` and it acts only as a collapsible header - or a real page, by adding a `slug` so the group title is also a link.\n\n<Callout type=\"note\">\n  Nested groups are only available through `navigation.json`. Frontmatter navigation is always two levels: category and pages.\n</Callout>\n\n## Precedence and behavior\n\n<Callout type=\"note\">\n  `navigation.json` takes priority over frontmatter. If present, it fully controls the sidebar structure for the sections it covers.\n</Callout>\n\n- Without `navigation.json`, the sidebar is built from page frontmatter: `category` -> grouped; `categoryOrder` -> category position; `order` -> page position.\n- When using the object format, sections not listed in `navigation.json` fall back to frontmatter-based navigation.\n- Pages without a `category` appear at the top level.\n\n## Tips\n\n- **Start simple**: Use frontmatter for small docs. Switch to `navigation.json` as the structure grows.\n- **Keep slugs consistent**: `slug` must match the MDX filename (e.g., `text.mdx` -> `text`).\n- **Control titles**: Use `title` in `navigation.json` to customize sidebar labels without changing page frontmatter.\n- **Per-section navigation**: Use the object format to define different sidebars for each section. Mix and match - define some sections explicitly and let others auto-generate.";
+export declare const navigationMdxTemplate = "---\ntitle: \"Navigation\"\ndescription: \"Organize and structure your navigation.\"\ndate: \"2026-02-19\"\ncategory: \"Configuration\"\ncategoryOrder: 3\norder: 2\n---\n\n# Navigation\n\nDoccupine builds your sidebar automatically from your MDX pages. By default, it reads the page frontmatter and groups pages into categories in the order you define. For larger docs, you can take full control with a `navigation.json` file.\n\n## Automatic navigation (default)\n\nWhen no custom navigation is provided, Doccupine generates a structure based on each page's frontmatter.\n\n### Frontmatter fields\n\n- **category**: The category name that groups the page in the sidebar.\n- **categoryOrder**: The position of the category within the sidebar. Lower numbers appear first.\n- **order**: The position of the page within its category. Lower numbers appear first.\n- **navIcon**: Optional [Lucide](https://lucide.dev/icons) icon name shown next to the page's sidebar link.\n- **categoryIcon**: Optional Lucide icon name for the page's category header. The first page in a category that sets it wins.\n\n### Example frontmatter\n\n```text\n---\ntitle: \"Navigation\"\ndescription: \"Organize and structure your navigation.\"\ndate: \"2025-01-15\"\ncategory: \"Configuration\"\ncategoryOrder: 3\norder: 2\n---\n```\n\nThis approach is great for small sets of documents. For larger projects, setting these fields on every page can become repetitive.\n\n## Custom navigation with navigation.json\n\nTo centrally define the entire sidebar, create a `navigation.json` at your project root (the same directory where you execute `npx doccupine`). When present, it takes priority over page frontmatter and fully controls the navigation structure.\n\n### Array format\n\nThe simplest format is an array of categories. When using [sections](/sections), this applies to the root section only.\n\n```json\n[\n  {\n    \"label\": \"Getting Started\",\n    \"links\": [\n      { \"slug\": \"\", \"title\": \"Introduction\" },\n      { \"slug\": \"commands\", \"title\": \"Commands\" },\n      { \"slug\": \"what-is-doccupine\", \"title\": \"What is Doccupine\" }\n    ]\n  },\n  {\n    \"label\": \"Components\",\n    \"links\": [\n      { \"slug\": \"components\", \"title\": \"Components\" },\n      { \"slug\": \"headers-and-text\", \"title\": \"Headers and Text\" },\n      { \"slug\": \"lists-and-tables\", \"title\": \"Lists and tables\" },\n      { \"slug\": \"code\", \"title\": \"Code\" },\n      { \"slug\": \"accordion\", \"title\": \"Accordion\" },\n      { \"slug\": \"tabs\", \"title\": \"Tabs\" },\n      { \"slug\": \"cards\", \"title\": \"Cards\" },\n      { \"slug\": \"buttons\", \"title\": \"Buttons\" },\n      { \"slug\": \"callouts\", \"title\": \"Callouts\" },\n      { \"slug\": \"image-and-embeds\", \"title\": \"Images and embeds\" },\n      { \"slug\": \"icons\", \"title\": \"Icons\" },\n      { \"slug\": \"fields\", \"title\": \"Fields\" },\n      { \"slug\": \"update\", \"title\": \"Update\" },\n      { \"slug\": \"columns\", \"title\": \"Columns\" },\n      { \"slug\": \"steps\", \"title\": \"Steps\" },\n      { \"slug\": \"color-swatches\", \"title\": \"Color Swatches\" },\n      { \"slug\": \"mermaid\", \"title\": \"Mermaid\" }\n    ]\n  },\n  {\n    \"label\": \"Configuration\",\n    \"links\": [\n      { \"slug\": \"globals\", \"title\": \"Globals\" },\n      { \"slug\": \"navigation\", \"title\": \"Navigation\" },\n      { \"slug\": \"sections\", \"title\": \"Sections\" },\n      { \"slug\": \"footer-links\", \"title\": \"Footer Links\" },\n      { \"slug\": \"theme\", \"title\": \"Theme\" },\n      { \"slug\": \"media-and-assets\", \"title\": \"Media and assets\" },\n      { \"slug\": \"fonts\", \"title\": \"Fonts\" },\n      { \"slug\": \"ai-assistant\", \"title\": \"AI Assistant\" },\n      { \"slug\": \"model-context-protocol\", \"title\": \"Model Context Protocol\" },\n      { \"slug\": \"analytics\", \"title\": \"Analytics\" },\n      { \"slug\": \"deployment-and-hosting\", \"title\": \"Deployment & Hosting\" },\n      { \"slug\": \"authentication\", \"title\": \"Authentication\" }\n    ]\n  }\n]\n```\n\n### Object format (per-section)\n\nWhen using [sections](/sections), you can define navigation for each section by using an object keyed by section slug. Sections without a key fall back to auto-generated navigation from frontmatter.\n\n```json\n{\n  \"\": [\n    {\n      \"label\": \"General\",\n      \"links\": [\n        { \"slug\": \"\", \"title\": \"Getting Started\" },\n        { \"slug\": \"commands\", \"title\": \"Commands\" }\n      ]\n    }\n  ],\n  \"platform\": [\n    {\n      \"label\": \"Overview\",\n      \"links\": [\n        { \"slug\": \"platform/auth\", \"title\": \"Authentication\" },\n        { \"slug\": \"platform/users\", \"title\": \"Users\" }\n      ]\n    }\n  ]\n}\n```\n\nThe key `\"\"` controls the root section. Other keys match section slugs defined in `sections.json` or derived from frontmatter. See [Sections](/sections) for details on configuring sections.\n\n### Fields\n\n- **label**: The section header shown in the sidebar.\n- **icon**: Optional [Lucide](https://lucide.dev/icons) icon name shown next to the category header.\n- **links**: An array of page entries for that section.\n  - **slug**: The MDX file slug (filename without extension). Use an empty string `\"\"` for `index.mdx`.\n  - **title**: The display title in the navigation. This can differ from the page's `title` frontmatter.\n  - **icon**: Optional Lucide icon name shown next to the link.\n  - **links**: Optional array of nested child links. See [Nested navigation](#nested-navigation).\n\n## Icons\n\nAdd icons to categories and links to make the sidebar easier to scan. Icons use [Lucide](https://lucide.dev/icons) names in kebab-case (e.g. `rocket`, `book-open`, `settings`). Unknown names render nothing, so a typo never breaks the build.\n\nWith frontmatter, set `navIcon` on a page for its sidebar link and `categoryIcon` for its category:\n\n```text\n---\ntitle: \"Introduction\"\ncategory: \"Getting Started\"\ncategoryOrder: 1\norder: 1\nnavIcon: \"rocket\"\ncategoryIcon: \"book-open\"\n---\n```\n\nWith `navigation.json`, add an `icon` to any category or link:\n\n```json\n[\n  {\n    \"label\": \"Getting Started\",\n    \"icon\": \"book-open\",\n    \"links\": [\n      { \"slug\": \"\", \"title\": \"Introduction\", \"icon\": \"rocket\" },\n      { \"slug\": \"commands\", \"title\": \"Commands\", \"icon\": \"terminal\" }\n    ]\n  }\n]\n```\n\n## Nested navigation\n\nA link in `navigation.json` can hold its own `links` array to create a collapsible group. Groups expand and collapse on click and open automatically when one of their pages is active. Nesting can go as deep as you need.\n\n```json\n[\n  {\n    \"label\": \"Guides\",\n    \"icon\": \"book-open\",\n    \"links\": [\n      { \"slug\": \"guides\", \"title\": \"Overview\", \"icon\": \"compass\" },\n      {\n        \"title\": \"Advanced\",\n        \"icon\": \"settings\",\n        \"links\": [\n          { \"slug\": \"guides/caching\", \"title\": \"Caching\" },\n          { \"slug\": \"guides/streaming\", \"title\": \"Streaming\" }\n        ]\n      }\n    ]\n  }\n]\n```\n\nA group can be a plain label - omit `slug` and it acts only as a collapsible header - or a real page, by adding a `slug` so the group title is also a link.\n\n<Callout type=\"note\">\n  Nested groups are only available through `navigation.json`. Frontmatter navigation is always two levels: category and pages.\n</Callout>\n\n## Precedence and behavior\n\n<Callout type=\"note\">\n  `navigation.json` takes priority over frontmatter. If present, it fully controls the sidebar structure for the sections it covers.\n</Callout>\n\n- Without `navigation.json`, the sidebar is built from page frontmatter: `category` -> grouped; `categoryOrder` -> category position; `order` -> page position.\n- When using the object format, sections not listed in `navigation.json` fall back to frontmatter-based navigation.\n- Pages without a `category` appear at the top level.\n\n## Tips\n\n- **Start simple**: Use frontmatter for small docs. Switch to `navigation.json` as the structure grows.\n- **Keep slugs consistent**: `slug` must match the MDX filename (e.g., `text.mdx` -> `text`).\n- **Control titles**: Use `title` in `navigation.json` to customize sidebar labels without changing page frontmatter.\n- **Per-section navigation**: Use the object format to define different sidebars for each section. Mix and match - define some sections explicitly and let others auto-generate.";

package/dist/templates/mdx/navigation.mdx.js

@@ -52,7 +52,8 @@ The simplest format is an array of categories. When using [sections](/sections),
     "label": "Getting Started",
     "links": [
       { "slug": "", "title": "Introduction" },
-      { "slug": "commands", "title": "Commands" }
+      { "slug": "commands", "title": "Commands" },
+      { "slug": "what-is-doccupine", "title": "What is Doccupine" }
     ]
   },
   {
@@ -73,7 +74,8 @@ The simplest format is an array of categories. When using [sections](/sections),
       { "slug": "update", "title": "Update" },
       { "slug": "columns", "title": "Columns" },
       { "slug": "steps", "title": "Steps" },
-      { "slug": "color-swatches", "title": "Color Swatches" }
+      { "slug": "color-swatches", "title": "Color Swatches" },
+      { "slug": "mermaid", "title": "Mermaid" }
     ]
   },
   {

package/dist/templates/mdx/what-is-doccupine.mdx.d.ts

@@ -0,0 +1 @@
+export declare const whatIsDoccupineMdxTemplate = "---\ntitle: \"What is Doccupine\"\ndescription: \"Doccupine is a CLI that turns a folder of MDX files into a complete, production-ready documentation website - no frontend work required.\"\ndate: \"2026-02-19\"\ncategory: \"Getting Started\"\ncategoryOrder: 0\norder: 2\n---\n\n# What is Doccupine\n\n**Doccupine** is a CLI tool that turns a directory of MDX files into a complete Next.js documentation website. It is less of a framework you assemble and more of a tool that does the assembling for you - you bring the content, Doccupine builds the site.\n\n```bash\nnpx doccupine\n```\n\n## Philosophy\n\nDoccupine was built on a simple belief: writing documentation should feel like writing, not like building a web app. Most docs frameworks hand you a pile of libraries and configuration and expect you to wire up rendering, navigation, theming, and search yourself. Doccupine makes those decisions for you and gets out of the way, so the only thing left to do is write.\n\n## Content first\n\nYou write standard Markdown and MDX. No React, no build configuration, no component wiring. Your navigation, theming, and search are all derived from your files and a handful of JSON config files. If you can write a Markdown file, you can ship a documentation site.\n\n## Batteries included\n\nEverything you expect from a great docs site works the moment you run the command - MDX rendering, an auto-generated sidebar, dark and light themes, 14+ built-in components, full-text search, an AI chat assistant, and an MCP server. Nothing to install, nothing to opt into.\n\n<Callout type=\"info\">\n  Every element on this page - this callout, the cards below, the code block above - is a live example of what your docs get out of the box, with zero setup.\n</Callout>\n\n## You own the output\n\nDoccupine generates a real Next.js 16 app inside your project, not a hosted black box. Every page, layout, and API route is written to disk where you can read it, extend it, or deploy it anywhere Next.js runs. Doccupine scaffolds the site; you stay in control of it.\n\n## Instant feedback\n\nRun `npx doccupine` and it watches your files. Every time you save an MDX file, change a config value, or drop in a new font, the site regenerates and the dev server reloads. Your docs are always one save away from being live.\n\n## AI-native\n\nDocumentation is not only read by people anymore. Doccupine ships a RAG-powered chat assistant so readers can ask questions in natural language, and an MCP server so AI tools and agents can search your documentation directly. Your content is ready for both audiences from day one.\n\n## Opinionated, on purpose\n\nDoccupine makes the boring decisions - layout, typography, color, navigation structure - so you can spend your time on the words that matter. When you are ready to customize, simple JSON files let you adjust site metadata, navigation, theme, and fonts without touching a line of code.\n\n## When to use Doccupine\n\nDoccupine is built for anyone who needs a polished documentation site without becoming a frontend engineer.\n\n- Product and API documentation\n- Developer guides and tutorials\n- Internal knowledge bases and runbooks\n- Design systems and component references\n\nThere are two ways to run it:\n\n<Columns cols={2}>\n  <Card title=\"Local CLI\" icon=\"terminal\" href=\"/\">\n    `npx doccupine` scaffolds and serves the site on your machine, and you self-host the generated Next.js app anywhere.\n  </Card>\n  <Card title=\"Doccupine Platform\" icon=\"cloud\" href=\"/platform\">\n    A managed, browser-based experience with a visual editor, one-click publishing, custom domains, and team collaboration - no local setup.\n  </Card>\n</Columns>";

package/dist/templates/mdx/what-is-doccupine.mdx.js

@@ -0,0 +1,68 @@
+export const whatIsDoccupineMdxTemplate = `---
+title: "What is Doccupine"
+description: "Doccupine is a CLI that turns a folder of MDX files into a complete, production-ready documentation website - no frontend work required."
+date: "2026-02-19"
+category: "Getting Started"
+categoryOrder: 0
+order: 2
+---
+
+# What is Doccupine
+
+**Doccupine** is a CLI tool that turns a directory of MDX files into a complete Next.js documentation website. It is less of a framework you assemble and more of a tool that does the assembling for you - you bring the content, Doccupine builds the site.
+
+\`\`\`bash
+npx doccupine
+\`\`\`
+
+## Philosophy
+
+Doccupine was built on a simple belief: writing documentation should feel like writing, not like building a web app. Most docs frameworks hand you a pile of libraries and configuration and expect you to wire up rendering, navigation, theming, and search yourself. Doccupine makes those decisions for you and gets out of the way, so the only thing left to do is write.
+
+## Content first
+
+You write standard Markdown and MDX. No React, no build configuration, no component wiring. Your navigation, theming, and search are all derived from your files and a handful of JSON config files. If you can write a Markdown file, you can ship a documentation site.
+
+## Batteries included
+
+Everything you expect from a great docs site works the moment you run the command - MDX rendering, an auto-generated sidebar, dark and light themes, 14+ built-in components, full-text search, an AI chat assistant, and an MCP server. Nothing to install, nothing to opt into.
+
+<Callout type="info">
+  Every element on this page - this callout, the cards below, the code block above - is a live example of what your docs get out of the box, with zero setup.
+</Callout>
+
+## You own the output
+
+Doccupine generates a real Next.js 16 app inside your project, not a hosted black box. Every page, layout, and API route is written to disk where you can read it, extend it, or deploy it anywhere Next.js runs. Doccupine scaffolds the site; you stay in control of it.
+
+## Instant feedback
+
+Run \`npx doccupine\` and it watches your files. Every time you save an MDX file, change a config value, or drop in a new font, the site regenerates and the dev server reloads. Your docs are always one save away from being live.
+
+## AI-native
+
+Documentation is not only read by people anymore. Doccupine ships a RAG-powered chat assistant so readers can ask questions in natural language, and an MCP server so AI tools and agents can search your documentation directly. Your content is ready for both audiences from day one.
+
+## Opinionated, on purpose
+
+Doccupine makes the boring decisions - layout, typography, color, navigation structure - so you can spend your time on the words that matter. When you are ready to customize, simple JSON files let you adjust site metadata, navigation, theme, and fonts without touching a line of code.
+
+## When to use Doccupine
+
+Doccupine is built for anyone who needs a polished documentation site without becoming a frontend engineer.
+
+- Product and API documentation
+- Developer guides and tutorials
+- Internal knowledge bases and runbooks
+- Design systems and component references
+
+There are two ways to run it:
+
+<Columns cols={2}>
+  <Card title="Local CLI" icon="terminal" href="/">
+    \`npx doccupine\` scaffolds and serves the site on your machine, and you self-host the generated Next.js app anywhere.
+  </Card>
+  <Card title="Doccupine Platform" icon="cloud" href="/platform">
+    A managed, browser-based experience with a visual editor, one-click publishing, custom domains, and team collaboration - no local setup.
+  </Card>
+</Columns>`;

package/dist/templates/package.js

@@ -12,20 +12,21 @@ export const packageJsonTemplate = JSON.stringify({
     },
     dependencies: {
         "@langchain/anthropic": "^1.5.1",
-        "@langchain/core": "^1.2.2",
+        "@langchain/core": "^1.2.3",
         "@langchain/google-genai": "^2.2.0",
         "@langchain/openai": "^1.5.5",
         "@mdx-js/react": "^3.1.1",
         "@modelcontextprotocol/sdk": "^1.29.0",
         "@posthog/react": "^1.10.3",
+        "beautiful-mermaid": "^1.1.3",
         "cherry-styled-components": "^0.2.11",
         langchain: "^1.5.3",
         "lucide-react": "^1.24.0",
         minisearch: "^7.2.0",
         next: "16.2.10",
         "next-mdx-remote": "^6.0.0",
-        "posthog-js": "^1.399.2",
-        "posthog-node": "^5.41.0",
+        "posthog-js": "^1.403.0",
+        "posthog-node": "^5.45.1",
         react: "19.2.7",
         "react-dom": "19.2.7",
         "rehype-highlight": "^7.0.2",
@@ -42,8 +43,8 @@ export const packageJsonTemplate = JSON.stringify({
         "@types/node": "^26",
         "@types/react": "^19",
         "@types/react-dom": "^19",
-        "@typescript-eslint/eslint-plugin": "^8.63.0",
-        "@typescript-eslint/parser": "^8.63.0",
+        "@typescript-eslint/eslint-plugin": "^8.64.0",
+        "@typescript-eslint/parser": "^8.64.0",
         "@typescript/native-preview": "^7.0.0-dev.20260707.2",
         eslint: "^10",
         "eslint-plugin-import": "^2.32.0",
@@ -52,7 +53,7 @@ export const packageJsonTemplate = JSON.stringify({
         "eslint-plugin-react-hooks": "^7.1.1",
         globals: "^17.7.0",
         prettier: "^3.9.5",
-        tsx: "^4.23.0",
+        tsx: "^4.23.1",
         typescript: "npm:@typescript/typescript6@^6.0.2",
     },
 }, null, 2) + "\n";

package/dist/templates/utils/mermaid.d.ts

@@ -0,0 +1 @@
+export declare const mermaidTemplate = "import \"server-only\";\nimport { renderMermaidSVG } from \"beautiful-mermaid\";\n\nconst DIAGRAM_OPTIONS = {\n  bg: \"var(--mermaid-bg)\",\n  fg: \"var(--mermaid-fg)\",\n  line: \"var(--mermaid-line)\",\n  accent: \"var(--mermaid-accent)\",\n  muted: \"var(--mermaid-muted)\",\n  surface: \"var(--mermaid-surface)\",\n  border: \"var(--mermaid-border)\",\n  transparent: true,\n};\n\nexport type MermaidResult =\n  | { ok: true; svg: string; width: number | null }\n  | { ok: false; error: string };\n\nfunction normalizeSvg(svg: string): {\n  ok: true;\n  svg: string;\n  width: number | null;\n} {\n  const openTag = /^<svg\\b[^>]*>/.exec(svg);\n  if (!openTag) return { ok: true, svg, width: null };\n\n  const widthMatch = /\\swidth=\"([\\d.]+)\"/.exec(openTag[0]);\n  const width = widthMatch ? Number.parseFloat(widthMatch[1]) : null;\n\n  const stripped = openTag[0].replace(/\\s(?:width|height)=\"[^\"]*\"/g, \"\");\n  return {\n    ok: true,\n    svg: stripped + svg.slice(openTag[0].length),\n    width: width !== null && Number.isFinite(width) ? width : null,\n  };\n}\n\nexport function renderDiagram(code: string): MermaidResult {\n  try {\n    return normalizeSvg(renderMermaidSVG(code, DIAGRAM_OPTIONS));\n  } catch (error) {\n    return {\n      ok: false,\n      error: error instanceof Error ? error.message : String(error),\n    };\n  }\n}\n";

package/dist/templates/utils/mermaid.js

@@ -0,0 +1,48 @@
+export const mermaidTemplate = `import "server-only";
+import { renderMermaidSVG } from "beautiful-mermaid";
+
+const DIAGRAM_OPTIONS = {
+  bg: "var(--mermaid-bg)",
+  fg: "var(--mermaid-fg)",
+  line: "var(--mermaid-line)",
+  accent: "var(--mermaid-accent)",
+  muted: "var(--mermaid-muted)",
+  surface: "var(--mermaid-surface)",
+  border: "var(--mermaid-border)",
+  transparent: true,
+};
+
+export type MermaidResult =
+  | { ok: true; svg: string; width: number | null }
+  | { ok: false; error: string };
+
+function normalizeSvg(svg: string): {
+  ok: true;
+  svg: string;
+  width: number | null;
+} {
+  const openTag = /^<svg\\b[^>]*>/.exec(svg);
+  if (!openTag) return { ok: true, svg, width: null };
+
+  const widthMatch = /\\swidth="([\\d.]+)"/.exec(openTag[0]);
+  const width = widthMatch ? Number.parseFloat(widthMatch[1]) : null;
+
+  const stripped = openTag[0].replace(/\\s(?:width|height)="[^"]*"/g, "");
+  return {
+    ok: true,
+    svg: stripped + svg.slice(openTag[0].length),
+    width: width !== null && Number.isFinite(width) ? width : null,
+  };
+}
+
+export function renderDiagram(code: string): MermaidResult {
+  try {
+    return normalizeSvg(renderMermaidSVG(code, DIAGRAM_OPTIONS));
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+`;

package/dist/templates/utils/parseCodeMeta.d.ts

@@ -0,0 +1 @@
+export declare const parseCodeMetaTemplate = "export type CodeMetaValue = string | boolean;\n\nexport function parseCodeMeta(meta?: string): Record<string, CodeMetaValue> {\n  const out: Record<string, CodeMetaValue> = {};\n  if (!meta) return out;\n\n  const pattern = /([A-Za-z_][\\w-]*)(?:=(?:\"([^\"]*)\"|'([^']*)'|\\{([^}]*)\\}))?/g;\n\n  let match: RegExpExecArray | null;\n  while ((match = pattern.exec(meta)) !== null) {\n    const [, key, doubleQuoted, singleQuoted, braced] = match;\n\n    if (doubleQuoted !== undefined) {\n      out[key] = doubleQuoted;\n    } else if (singleQuoted !== undefined) {\n      out[key] = singleQuoted;\n    } else if (braced !== undefined) {\n      const value = braced.trim();\n      out[key] =\n        value === \"true\"\n          ? true\n          : value === \"false\"\n            ? false\n            : value.replace(/^[\"']|[\"']$/g, \"\");\n    } else {\n      out[key] = true;\n    }\n  }\n\n  return out;\n}\n";

package/dist/templates/utils/parseCodeMeta.js

@@ -0,0 +1,32 @@
+export const parseCodeMetaTemplate = `export type CodeMetaValue = string | boolean;
+
+export function parseCodeMeta(meta?: string): Record<string, CodeMetaValue> {
+  const out: Record<string, CodeMetaValue> = {};
+  if (!meta) return out;
+
+  const pattern = /([A-Za-z_][\\w-]*)(?:=(?:"([^"]*)"|'([^']*)'|\\{([^}]*)\\}))?/g;
+
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(meta)) !== null) {
+    const [, key, doubleQuoted, singleQuoted, braced] = match;
+
+    if (doubleQuoted !== undefined) {
+      out[key] = doubleQuoted;
+    } else if (singleQuoted !== undefined) {
+      out[key] = singleQuoted;
+    } else if (braced !== undefined) {
+      const value = braced.trim();
+      out[key] =
+        value === "true"
+          ? true
+          : value === "false"
+            ? false
+            : value.replace(/^["']|["']$/g, "");
+    } else {
+      out[key] = true;
+    }
+  }
+
+  return out;
+}
+`;

package/dist/templates/utils/rehypeCodeMeta.d.ts

@@ -0,0 +1 @@
+export declare const rehypeCodeMetaTemplate = "interface MetaNode {\n  type: string;\n  tagName?: string;\n  data?: { meta?: string };\n  properties?: Record<string, unknown>;\n  children?: MetaNode[];\n}\n\nexport function rehypeCodeMeta() {\n  return (tree: MetaNode) => {\n    const visit = (node: MetaNode) => {\n      if (node.type === \"element\" && node.tagName === \"code\") {\n        const meta = node.data?.meta;\n        if (typeof meta === \"string\" && meta.length > 0) {\n          node.properties = { ...node.properties, meta };\n        }\n      }\n      node.children?.forEach(visit);\n    };\n    visit(tree);\n  };\n}\n";

package/dist/templates/utils/rehypeCodeMeta.js

@@ -0,0 +1,23 @@
+export const rehypeCodeMetaTemplate = `interface MetaNode {
+  type: string;
+  tagName?: string;
+  data?: { meta?: string };
+  properties?: Record<string, unknown>;
+  children?: MetaNode[];
+}
+
+export function rehypeCodeMeta() {
+  return (tree: MetaNode) => {
+    const visit = (node: MetaNode) => {
+      if (node.type === "element" && node.tagName === "code") {
+        const meta = node.data?.meta;
+        if (typeof meta === "string" && meta.length > 0) {
+          node.properties = { ...node.properties, meta };
+        }
+      }
+      node.children?.forEach(visit);
+    };
+    visit(tree);
+  };
+}
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doccupine",
-  "version": "0.0.124",
+  "version": "0.0.126",
   "description": "Free and open-source documentation platform. Write MDX, get a production-ready site with AI chat, built-in components, and an MCP server - in one command.",
   "main": "dist/index.js",
   "bin": {