Include | Hanzo Docs

Usage

Content

To display content from another Markdown/MDX file, specify its path relative to the file itself in the <include> tag.

MDX

Markdown

<include>./another.mdx</include>

::include[./another.mdx]

For Markdown

Markdown (.md) files do not support JSX syntax. To use <include />, you need to configure remark-directive.

source.config.ts

import { defineConfig } from '@hanzo/docs/mdx/config';
import remarkDirective from 'remark-directive';

export default defineConfig({
  mdxOptions: {
    remarkPlugins: [remarkDirective],
  },
});

You may also need rehype-raw for HTML comments & content.

CodeBlock

For other types of files, it will become a codeblock:

MDX

Markdown

<include>./script.ts</include>

<include lang="md" meta='title="lib.md"'>
  page.md
</include>

::include[./script.ts]

::include[page.md]{lang=md meta='title="lib.md"'}

You can include only a region of content:

code.ts

export function fn() {
  //#region a
  console.log('one');
  //#endregion
}

MDX

Markdown

<include>./code.ts#a</include>

::include[./code.ts#a]

`cwd`

Resolve relative paths from cwd instead of the current file:

MDX

Markdown

<include cwd lang="tsx" meta='title="lib.ts"'>
  ./script.ts
</include>

::include[./script.ts]{cwd lang=tsx meta='title="lib.ts"'}

Extraction

When referencing content files, you can only include a certain part of the document.

Section

Encapsulate by a <section /> tag:

a.mdx

b.mdx

## Hello World

<section id="test">This is included</section>

This is not included.

Include the content from `a.mdx`:

<include>a.mdx#test</include>

In Markdown:

a.md

b.md

## Hello World

:::section{#test}
This is included
:::

This is not included.

Include the content from `a.mdx`:

::include[a.md#test]

Heading

Include contents under a certain heading.

a.mdx

b.mdx

## Included Section

I'm here!

## Not Included

Some random text.

Content under the heading:

<include>a.mdx#included-section</include>

In Markdown:

a.md

b.md

## Included Section

I'm here!

## Not Included

Some random text.

Content under the heading:

::include[a.mdx#included-section]