Reusable snippets | NookDocs

Reusable snippets let you author a piece of content once and include it in many pages — API auth intros, common warnings, shared error tables, consistent callouts. Without this, you copy-paste and drift the moment you update one and forget the others.

Shipping status today. Inline-children authoring via <Snippet> works right now. Repo-wide /snippets/*.mdx file resolution + template variables (vars prop) are Phase 4 roadmap — see Phase 4 status below.

What works today

Write <Snippet> call sites in your MDX. Pass the content as children. The component renders whatever you pass, unchanged.

<Snippet>
  Add your API key to the `Authorization` header:

  ```bash
  curl -H "Authorization: Bearer YOUR_KEY" https://api.example.com/v1/users
  ```
</Snippet>

Renders exactly like the children would if they were inline — no reuse benefit, but the call sites are forward-compatible. When Phase 4 ships, you swap inline children for <Snippet file="..."> without rewriting anything.

The target API (Phase 4)

File-based snippets

Author once at _snippets/<name>.mdx, include anywhere:

<Snippet file="_snippets/authentication.mdx" />

<!-- docs/_snippets/authentication.mdx -->
Add your API key to the `Authorization` header:

```bash
curl -H "Authorization: Bearer YOUR_KEY" https://api.example.com/v1/users
```

At sync time the pipeline walks _snippets/ (under contentRoot), stores each file's body, and inlines it wherever file="..." resolves to an existing snippet.

Template variables

Parameterise snippets per call site:

<Snippet
  file="_snippets/install.mdx"
  vars={{ tool: "docker", version: "4.2" }}
/>

<!-- docs/_snippets/install.mdx -->
Install {{tool}} version {{version}}:

```bash
{{tool}} install --version {{version}}
```

{{variable}} placeholders resolve at render time with values from the vars prop. Missing values render as an empty string with a warning in the build log.

When to use snippets (once available)

Auth intros

Every API reference page opens with the same auth paragraph. Write it once; include in all.

Compliance warnings

GDPR / HIPAA / SOC 2 notices that must appear on specific page types. Snippet = one update site.

Install / setup blocks

Same package-manager tabs across quickstart, concepts, recipes. Parameterise with vars to swap package names.

Shared tables

Error code tables, rate-limit tables, feature-tier matrices. Centralise so the source of truth lives in one file.

Phase 4 roadmap

Full file-based resolution ships alongside the OpenAPI parser and assistant upgrades in Phase 4. The pipeline work is:

Sync extracts snippets

Walk <contentRoot>/_snippets/ during webhook sync. Store each file's body + hash in a new snippets Postgres table keyed by (project_id, path).

Renderer resolves at render time

When MDX renderer encounters <Snippet file="...">, it looks up the row and inlines the body. Missing file → render with a warning banner instead of crashing.

Template variable substitution

Parse {{name}} placeholders in snippet body, substitute from vars prop. Missing variable → empty string + build warning.

Dashboard snippet manager

Editor gets a side-panel view of every snippet + usage count (how many pages include it), so writers can audit before deleting.

Track the actual ship at github.com/Codivion/NookDocs/issues or follow the changelog.

Escape hatches until Phase 4

Inline children — shown above. No reuse, but forward-compatible call sites.
Hand-copy + grep — author your snippet content once in a local .md note, grep its usages across docs/ when it changes. Crude but keeps drift bounded.
Import at edit time — the dashboard editor lets you search across all pages; copy-paste during editing keeps a mental cross-reference.

Snippet component — the component reference (stub behaviour)
Format text — raw Markdown in pages
Format code — code-block-specific reuse patterns
Visibility — audience-split authoring (different reuse story — splits content by viewer type)