Templates

Every Markdown file is also a nunjucks template. Use it to reuse content across pages, render values from the page configuration, and call NgDoc actions such as demos and API tables.

👀 See it

This page reads its own configuration. Its title is Templates, and it renders this list from the page's data field:

• Discover
• Render
• Link
• Write

And this callout is included from another file:

Note

This callout comes from partials/support.md. Every page that includes it shows the same text.

🧰 Use it

Nunjucks tags go straight into the Markdown. The example above comes from this source:

Its title is **{{ NgDocPage.title }}**.

<ul>{% for step in NgDocPage.data.steps %}<li>{{ step }}</li>{% endfor %}</ul>

{% include "./partials/support.md" %}

The data field is set in the page configuration:

import { NgDocPage } from '@ng-doc/core';

import WriteContentCategory from '../ng-doc.category';

const TemplatesPage: NgDocPage = {
  title: 'Templates',
  mdFile: './index.md',
  category: WriteContentCategory,
  order: 7,
  data: {
    steps: ['Discover', 'Render', 'Link', 'Write'],
  },
};

export default TemplatesPage;

Template variables

Demos, Playgrounds and Embed API in guides show these actions in use. Markdown and template syntax lists their signatures.

Includes

include inserts another file into the page. Use it for text that several pages share. The path is relative to the current Markdown file.

{% include "../shared/support.md" %}

When the included file changes, NgDoc rebuilds every page that includes it.

Macros

A macro is a reusable piece of template with parameters. Define macros in a shared file:

{% macro kbd(key) %}<kbd>{{ key }}</kbd>{% endmacro %}

Import the file, then call the macro:

{% import "../shared/macros.md" as ui %}

Press {{ ui.kbd('/') }} to search.

Exclude content from search

Wrap content in index false to keep it out of the search index. The Related links at the end of each page on this site use it:

{% index false %}

## Related

- A link that search should skip.

{% endindex %}

Code blocks are never indexed, so you don't need to wrap them.

Show template syntax as text

NgDoc renders every {{ }} and {% %} in the file, including inside code blocks. To show them as text, output them as a string with the safe filter:

{{ '{{ NgDocPage.title }}' | safe }}

🚧 Gotchas

Warning

Paths in include and import are relative to the Markdown file, not to the documentation root. Use only the built-in Nunjucks filters: the new engine adds no filters of its own. The legacy builders expose some internal filters, but don't rely on them, because the new engine doesn't have them.

Next: Demos