NDG Syntax Reference

• NDG Syntax Reference
  • Basic Markdown
  • Extended Syntax
    • Admonitions
      • Nesting admonitions
    • Text Roles
    • Command and REPL Prompts
    • GitHub Callouts
    • Headers with Anchors
    • Inline Anchors
    • List Items with Anchors
    • Figures
    • Definition Lists
    • File Includes
    • Autolinks
    • Option References
  • NixOS Module Options
  • Manpage Formatting

This document details all the syntax features supported by ndg and covers all the special markup features that ndg supports beyond standard Markdown.

By using these extensions, you can create rich, semantically meaningful documentation for your Nix projects that works well both as HTML and manpages.

Basic Markdown

ndg supports all standard CommonMark syntax including:

• Headings H1 to H6 (# to ######)
• Emphasis (italic and bold)
• Lists (ordered and unordered)
• Links and images
  • Masked links and <autolinks>
• Code blocks and inline code
• Blockquotes
• Horizontal rules
• Tables
• Footnotes

Additionally, ndg includes support for GitHub Flavored Markdown extensions like strikethrough and task lists.

Extended Syntax

Beyond standard Markdown, ndg provides several additional syntax features designed to enhance documentation, particularly for Nix-related projects.

Admonitions

Admonitions are colored callout boxes that highlight important information. They use a fenced block syntax with a class indicator.

::: {.note} This is a note admonition. :::

::: {.warning} This is a warning admonition. :::

::: {.tip} This is a tip admonition. :::

::: {.important} This is an important admonition. :::

::: {.caution} This is a caution admonition. :::

::: {.danger} This is a danger admonition. :::

::: {.info} This is an info admonition. :::

You can also add an ID to an admonition for direct linking:

::: {.note #custom-id}
This note has a custom ID and can be linked to with
[link](#custom-id).
:::

Nesting admonitions

Fenced admonitions process block elements in their contents recursively. You can nest a GitHub-style callout inside a fenced admonition without writing HTML:

::: {.example} This is an example.

> [!NOTE]
> With a nested note!

:::

For nested fenced admonitions, use a longer fence for the outer block than for the inner block. A fence at least as long as the opening fence closes that block, so using the same length for both would close the outer block early.

:::: {.example} Outer content.

::: {.note} Inner content. :::

More outer content.

::::

Text Roles

Text roles provide semantic markup for specific types of content. They use a special syntax with curly braces and backticks.

{command}`ls -la`                    # Terminal command
{file}`/etc/nixos/configuration.nix` # File path
{option}`services.nginx.enable`      # NixOS option
{env}`HOME`                          # Environmentvariable
{var}`myVariable`                    # Nix variable
{manpage}`man(1)`                    # Man page reference

Each role applies specific styling in the HTML output, making it easier to distinguish different types of technical content.

Command and REPL Prompts

Terminal commands with prompts can be typed with a shorthand syntax:

`$ echo "Hello World"`

This renders as a command prompt with styling.

Similarly, for Nix REPL prompts:

`nix-repl> 1 + 2`

GitHub Callouts

ndg supports GitHub-style callouts:

> [!NOTE]
> This is a note callout using GitHub's syntax.

> [!WARNING]
> This is a warning callout.

> [!TIP]
> This is a tip callout.

> [!IMPORTANT]
> This is an important callout.

> [!CAUTION]
> This is a caution callout.

> [!DANGER]
> This is a danger callout.

These are converted to the same styled admonition blocks as the fenced admonition syntax.

Callout type names currently require uppercase letters in NDG. Nesting one GitHub-style callout inside another is not supported; use a fenced outer admonition as shown in Nesting admonitions.

Headers with Anchors

You can add custom anchor IDs to headers for more reliable linking:

## Installation {#installation}

Refer to the [installation section](#installation).

This creates a header with a specific ID that won't change even if you rename the section.

Inline Anchors

You can create anchor points anywhere in your document:

[]{#my-anchor}

... some content ...

[Link to the anchor](#my-anchor)

This adds an invisible anchor that you can link to from elsewhere in the document.

List Items with Anchors

Add anchors to specific list items:

- []{#item1} First item
- []{#item2} Second item

See the [second item](#item2).

Figures

Create figures with captions:

::: {.figure #sample-figure}

# Sample Figure Caption

![Alt text for image](path/to/image.png) :::

This creates a figure with proper semantic HTML including a caption.

Definition Lists

Create definition lists with a simple syntax:

Term : Definition for the term.

Another term : Definition for another term.

File Includes

Include the contents of other files in your documentation:

```{=include=}
path/to/file1.md
path/to/file2.md
```

This is useful for creating modular documentation from multiple smaller files.

Autolinks

URLs are automatically converted to clickable links even without explicit Markdown link syntax:

Visit https://nixos.org for more information.

Option References

References to NixOS options are automatically linked to the options documentation page:

Configure `services.nginx.enable` to start the web server.

When you have included a module options JSON file in your build, option references like this will be automatically linked to the corresponding entry in the options page. ¹

NixOS Module Options

ndg can generate documentation for NixOS module options when provided with an options JSON file (typically created with nixosOptionsDoc). Options are automatically rendered with:

• Type information
• Default values
• Examples (if available)
• Descriptions
• Declaration locations (with links to source if available)

To include options documentation:

$ ndg html --module-options ./options.json ...
# => This will generate the document with an options.html page, also linked in
# the navbar by default

Options are presented in a hierarchical structure for easier navigation, with the depth of parent categories controlled by the sidebar.options.depth config key.

Manpage Formatting

When generating manpages with ndg, special formatting is applied to convert Markdown elements to troff syntax. The following elements receive special treatment:

• Section headings become proper manpage section headings
• Code blocks are properly formatted with fixed-width text
• Lists are formatted with appropriate indentation
• Command prompts and REPL prompts are specially formatted
• Admonitions become indented blocks with appropriate headings
• Text roles are converted to bold or italic text as appropriate
• Links show both the link text and URL

To generate manpages from options:

$ ndg manpage --module-options ./options.json --output ./man/myproject.5 \
  --title "My Project" --section 5

Please refer to manpages and the README for direct command usage.