Skip to main content

Writing Tutorials

Directory structure​

Put all tutorial files in a single directory. JSDoc will load every supported file in that directory:

Include tutorials when generating docsnpx jsdoc src --tutorials ./tutorials -d docs
tutorials/
  installation.md
  quick-start.md
  advanced-config.md
  tutorials.json

Writing a tutorial​

A tutorial file is a plain Markdown or HTML file. No special front matter is required:

# Getting Started

Install the package, then run the CLI:

    npm install --save-dev jsdoc
    npx jsdoc src -d docs

Continue with the [Installation](#installation) tutorial.

Configuring metadata with tutorials.json​

Create a tutorials.json file in the tutorials directory to set titles and build a hierarchy:

{
  "installation": {
    "title": "Installation"
  },
  "quick-start": {
    "title": "Quick Start",
    "children": {
      "advanced-config": {
        "title": "Advanced Configuration"
      }
    }
  }
}
note

The keys in tutorials.json must match the filenames of your tutorial files (without the extension).

Linking from source code​

Use {@tutorial <id>} in any JSDoc comment to insert a hyperlink:

/**
 * Initialise the application.
 * See {@tutorial quick-start} for a complete walkthrough.
 */
function init() {}

You can also use the @tutorial block tag to add a related-tutorials section:

/**
 * @tutorial installation
 * @tutorial quick-start
 */
class App {}

Linking between tutorials​

Inside a Markdown tutorial, link to other tutorials using their file paths:

Continue with the [Quick Start](quick-start.md) tutorial.

See also​

Official reference: jsdoc.app/about-tutorials