Markdown Partials#

Copy as MarkdownView Markdown

Parameterized partials are opt-in and off by default. When enabled, an HTML comment directive inlines another Markdown file and substitutes named {{ values }} before the host document is parsed. Existing <!-- @include: --> includes are unchanged.

import { oxContent } from "@ox-content/vite-plugin";

export default {
  plugins: [
    oxContent({
      partials: true,
    }),
  ],
};

false or omitted leaves the directive literal. true or an object enables the transform. Expansion is build-time only.

Directive#

<!-- @partial: ./_partials/install.md package="ox-content" manager="pnpm" -->

This site enables partials, so the next sentence is a live partial:

Install ox-content with pnpm.

The path may be quoted. Bare names such as install.md resolve under _partials (configurable with root). {{ name }} substitutions are HTML-escaped, so <script> cannot be injected as raw markup.

Missing parameters#

A missing {{ name }} stays literal. It is never replaced with an empty string. Set missing: "error" to report a transform diagnostic while still leaving the placeholder in the source.

oxContent({
  partials: {
    root: "_partials",
    missing: "literal",
  },
});

Path safety#

• Relative ./ and ../ paths resolve from the current file.
• @/ and a leading / resolve from rootDir.
• After canonicalize, any path outside rootDir is rejected. The directive stays in the source and a transform error is reported.
• Cycles and nesting deeper than 16 levels are transform errors. Diagnostics include the host file and line.

What is not expanded#

The directive is not expanded inside fenced code, indented code, or inline code. HTML comments that are not @partial: stay as-is, including <!-- @include: PATH -->.

Related#

• File Includes
• Built-in Features overview