Last updated 1 month ago

Reusing content with Markdown snippets

Important

Content reuse with Markdown snippets is supported starting with version beta.103 of the Developer portal.

As you expand your developer portal, sometimes you'll need to repeat the same content in multiple places. Redocly helps you manage such content more efficiently by supporting content reuse in Markdown files. Create "chunks" of text, save them as Markdown files, and embed them across the portal. We call these "chunks" snippets, and the pages in which they're embedded are target pages. You can embed a snippet in as many target pages as you want.

This single-source authoring approach lets you control the content from a central place. Instead of repeating or manually copying the content, you include a reference to it wherever you need it to appear. Redocly embeds the referenced content automatically when building the developer portal. This approach is similar to using $refs in OpenAPI definitions.

If you want to change the content in a snippet, you only need to do it once. The changes propagate automatically to all target pages. With this approach, your content is more consistent and easier to update.

Prerequisites

  • One or more text snippets saved as Markdown files in your developer portal project. Only Markdown (.md) files are supported; MDX, YAML or any other file types can't be used with this content reuse method.
  • The names of your snippet files must start with an underscore (for example, _snippet.md).
  • Each snippet must only contain text with basic Markdown formatting (emphasis, quotes, code, lists, tables) and HTML formatting. Images, links, and front matter are not supported.

Limitations

  • Snippets can only be embedded into Markdown pages (.md files). Using snippets in MDX files is currently not supported.
  • "Nested" snippets and cyclical file references are not supported. A Markdown snippet cannot contain a reference to another snippet or a link to any other file in your developer portal project.
  • If a snippet contains headings, they are included as-is, regardless of any existing heading order in the target page. This means that an H1 heading in a snippet won't be transformed into an H2 if the target page already has an H1 preceding it.

Configuration steps

Step 1: Create a directory for Markdown snippets

You can store your snippets in any directory as long as it's in the developer portal project. We recommend keeping snippets separate from the rest of the content for cleaner organization. A separate directory also indicates to other portal contributors that the files in it serve a specific purpose.

For example, you can create a directory for snippets in the root of the portal project:

├── ./README.md
├── ./favicon.png
├── ./images
├── ./index.mdx
├── ./openapi
│   └── ./openapi/petstore.yaml
├── ./package.json
├── ./reference.page.yaml
├── ./sidebars.yaml
├── ./siteConfig.yaml
├── ./theme.ts
├── ./developer-portal
│   ├── ./developer-portal/homepage.md
├── ./snippets
│   ├── ./snippets/_copyright-note.md
│   ├── ./snippets/_supported-product-versions.md
│   ├── ./snippets/_product-description.md
└── ./yarn.lock

In complex portal projects, we recommend organizing snippets into subdirectories by topic, product, or any other criteria:

├── ./README.md
├── ./favicon.png
├── ./images
├── ./index.mdx
├── ./openapi
│   └── ./openapi/petstore.yaml
├── ./package.json
├── ./reference.page.yaml
├── ./sidebars.yaml
├── ./siteConfig.yaml
├── ./theme.ts
├── ./developer-portal
│   ├── ./developer-portal/homepage.md
├── ./reusables
│   ├── ./reusables/playbooks
│       ├── ./reusables/playbooks/_version-snippet.md
│   ├── ./reusables/apis
│       ├── ./reusables/apis/_intro-snippet.md
        ├── ./reusables/apis/_auth-snippet.md
│   ├── ./reusables/tutorials
        ├── ./reusables/tutorials/_product-description.md
        ├── ./reusables/tutorials/_skill-level.md
└── ./yarn.lock

Step 2: Create a Markdown snippet file

Save the content you want to reuse as a Markdown file to the previously designated directory. The file name must start with an underscore.

Example: _version-snippet.md file

This text lists supported versions of **Product Name** that these instructions apply to.

- Version X
- Version Y
- Version Z

Step 3: Reference your snippet file in target pages

To ensure the content from your snippet is included when building the portal, reference the snippet in the page(s) where you want the content to appear.

Use the HTML <embed> tag followed by the path to the snippet file. You must provide the full path of the snippet file, either as

  • relative to the project root (<embed src="../snippets/_example.md" />), or
  • absolute to the project root (<embed src="/snippets/_example.md" />).

You can use both types of links interchangeably.

Make sure you use blank lines before and after the line referencing the snippet.

Example: including _version-snippet.md into target.md

# Target page

This is the page where we want to include the snippet.
The snippet should be included right after this sentence.

<embed src="/reusables/playbooks/_version-snippet.md" />

Now we continue with the rest of the page.

To include multiple snippets one after the other, reference each snippet in its own line.

Example: including multiple snippets consecutively

# Target page

This is the page where we want to include a bunch of snippets in a row.

<embed src="../reusables/apis/_intro-snippet.md" />

<embed src="../reusables/tutorials/_product-description.md" />

<embed src="../reusables/playbooks/_version-snippet.md" />

Now we're done including snippets.

Step 4: Confirm that the snippet content is visible

After building the portal, access the page(s) where you have referenced the snippet. The content from the snippet file should be displayed with appropriate Markdown formatting.

Troubleshooting

The portal build will fail if:

  • the snippet file doesn't exist in your developer portal project, or
  • the snippet file cannot be found because the provided path is incorrect, or
  • if you have not used valid Markdown.

Check the portal build log for error messages with information about the file(s) that prevented the build from completing successfully.