Skip to main content

Reusing content with includes

In Docusaurus, you can import an MDX file into another MDX file and render it as a component. That is how you reuse notices, warnings, and short shared snippets.

In this template, shared MDX lives under docs/_includes/. The include files should also be named with a leading underscore, for example _template-notice.mdx.

Creating an include​

  1. Add a file under docs/_includes/.
  2. Write normal MDX (Markdown, admonitions, HTML-in-MDX).
    No special front matter is required for a simple snippet.

Example:

docs/_includes/_template-notice.mdx
:::info[Template notice]
This block is a reusable include. Edit it once in `docs/_includes/`, and every page that imports it updates together.
:::

Using an include​

After the reusable snippet exists under docs/_includes/, you can insert it into a topic by importing the file and placing a tag where the content should appear. The import is the reference to the shared file, and the tag is the insertion point in the topic body.

  1. Open the topic that should show the shared content.
    Use an MDX file. Imports are unreliable in plain Markdown.

  2. Immediately after the front matter (before any headings, paragraphs, or admonitions), add an import that points at the include.
    Choose a capitalised name for the import — MDX uses that name as a component.

    Capitalise the import name

    Component names must start with a capital letter (TemplateNotice, not templateNotice). A lowercase tag is treated as a normal HTML element and the include will not render.

    Put imports at the top

    Place every import right after the front matter. An import later in the file — especially after a ::: admonition — can fail MDX compilation (acorn / import parse errors). Keep imports at the top; put only the <Component /> tags in the body where the content should appear.

    You can write the path in two ways:

    • Relative to the current topic, for example ../../../_includes/_template-notice.mdx. That works, but every ../ depends on where this topic sits in the folder tree. If you move the topic, you must fix the import.
    • From the project root with the @site alias. @site always means the repository root (the folder that contains docs/, src/, and docusaurus.config.js), so the same import works from any topic:
    ---
    title: Example topic
    ---

    import TemplateNotice from '@site/docs/_includes/_template-notice.mdx';

    # Example topic

    <TemplateNotice />

    Prefer @site unless you have a reason to keep a relative path. The path after @site/ is the reusable file. The name (TemplateNotice) is only the local label for this topic.

  3. In the topic body, put a self-closing tag with that name where the reused block should appear:

    <TemplateNotice />

    When the page builds, the include’s content is inlined at that point. Edit the file under _includes/ once; every topic that imports it updates together.

  4. To reuse more than one snippet on the same page, add another import at the top (still after front matter) and another tag in the body:

    ---
    title: Example topic
    ---

    import TemplateNotice from '@site/docs/_includes/_template-notice.mdx';
    import SharedTip from '@site/docs/_includes/_shared-tip.mdx';

    # Example topic

    <TemplateNotice />

    <SharedTip />

Live examples​

Template notice

This block is a reusable include. Edit it once in docs/_includes/, and every page that imports it updates together.

Shared tip

Prefer .mdx for docs that import includes. Importing MDX into a plain .md file is unreliable.

On this page: