Project setup

Install yaakdoc in a project, add a config file and keep the export in version control.

npx yaakdoc works without any setup. For docs that live in a repository and build in CI, install yaakdoc as a dependency and add a config file.

Install

npm i -D yaakdoc

Then add scripts to package.json:

package.json

{
  "scripts": {
    "docs:dev": "yaakdoc",
    "docs:build": "yaakdoc build",
    "docs:preview": "yaakdoc preview"
  }
}

Create a config file

npx yaakdoc init

init asks for a site title, a primary color, the page layout and whether to generate LLM output, then writes yaakdoc.config.json. Pass --yes to skip the questions, and --force to overwrite an existing file.

yaakdoc.config.json

{
  "$schema": "./node_modules/yaakdoc/config.schema.json",
  "export": "./yaak.json",
  "branding": {
    "title": "Acme API",
    "colors": {
      "primary": "#0f766e"
    }
  },
  "pages": "single"
}

The $schema line gives you autocomplete and validation in editors such as VS Code. When yaakdoc isn't installed locally, init points it at the schema on unpkg instead.

Everything in the config is optional. See the configuration reference for every option.

Config file formats

yaakdoc looks for yaakdoc.config.json in the current directory. .jsonc, .ts and .js work too. In TypeScript or JavaScript, use defineConfig for types:

yaakdoc.config.ts

import { defineConfig } from "yaakdoc";

export default defineConfig({
  branding: {
    title: "Acme API",
  },
  pages: "per-request",
});

Relative paths in the config (the export, pagesDir, the logo, ...) are resolved from the config file's directory.

The export

Unless you pass a path (as an argument or export in the config), yaakdoc uses yaakdoc.json from the current directory, then yaak.json. Nothing else is scanned.

Commit the export

The export is the source of your docs, so commit it along with the config. Re-export from Yaak whenever the API changes. The Yaak plugin's Save as yaakdoc project... action writes both files for you. Before you commit it to a public repository, check it for secrets: the export isn't redacted, only the site is.

If the export contains several workspaces, choose one with workspace (its name or id):

{
  "workspace": "Acme Store API"
}

Your export isn't redacted

yaakdoc keeps secrets out of the site it builds, but the export itself (yaak.json or yaakdoc.json) is untouched. It contains every environment, including private ones, and every value stored in plain text: tokens, passwords and API keys in variables, headers and auth settings. Before you commit it to a public repository, keep secrets out of the workspace (use secure(...), or leave the values empty), or keep the repository private.

Page layout

pages decides how the API reference is split into pages:

single (default): the whole reference on one page, with anchors for every folder and request. It works well for small and medium APIs.
per-request: a page for every folder and request. It's better for large APIs and keeps pages fast.

Static files

Files in a public/ folder next to the config are copied to the site root as they are. Use it for robots.txt, verification files or images that you link to from descriptions.

Overriding config from the command line

CLI flags (--theme, --pages, --base, --environment, ...) take precedence over the config file. For any other value, use --overrides with inline JSON or a JSON file:

npx yaakdoc build --overrides '{"branding":{"title":"Staging API"},"runInYaak":false}'

See the CLI reference.

InstallCopy Anchor Link

Create a config fileCopy Anchor Link

Config file formatsCopy Anchor Link

The exportCopy Anchor Link

Page layoutCopy Anchor Link

Static filesCopy Anchor Link

Overriding config from the command lineCopy Anchor Link