Skip to main content

Tutorials

What are tutorials?​

Tutorials are standalone documentation pages that live outside your source code. They are useful for conceptual guides, architecture overviews, and any narrative content that doesn't belong in a symbol's JSDoc comment.

Tutorials appear in the output as a dedicated section separate from the API reference.

Enabling tutorials​

Pass the directory containing your tutorial files to JSDoc with the -u (or --tutorials) flag:

Include tutorialsnpx jsdoc src -u tutorials -d docs

Or set it in your configuration file:

{
  "opts": {
    "tutorials": "tutorials"
  }
}

File formats​

Tutorials can be written as:

FormatExtension
Markdown.md, .markdown
HTML.html, .htm, .xhtml

Naming and titles​

By default, the tutorial's filename (without extension) becomes its title and its identifier. To override the title and define a parent–child hierarchy, create a tutorials.json file in the tutorials directory:

{
  "getting-started": {
    "title": "Getting Started",
    "children": {
      "installation": {
        "title": "Installation"
      }
    }
  }
}

Linking to tutorials​

Use the {@tutorial} inline tag in any JSDoc comment to link to a tutorial by its identifier:

/**
 * See {@tutorial getting-started} for setup instructions.
 */

See also​