Environments and variables

Yaak requests use variables, such as ${[ base_url ]}/products/${[ product_id ]}. yaakdoc resolves them so readers see real URLs and runnable examples, and it makes sure secrets never end up in the output.

The default environmentCopy Anchor Link

environment picks the environment (by name or id) used to resolve variables:

{
  "environment": "Production"
}

• By default, the first shared (non-private) sub environment is used.
• false uses only the base environment, with no sub environment.
• Folder environments apply to the requests in their folder, as they do in Yaak.

Environment switcherCopy Anchor Link

environments lets readers switch between environments without a reload:

{
  "environment": "Production",
  "environments": "public"
}

• "public" offers every shared environment. A list of names or ids offers just those.
• environment is the default selection.
• The URLs, code examples, the variables table and the variables in custom pages are prerendered for each environment, so switching is instant and works with the static site.
• The reader's choice is remembered.

Variables tableCopy Anchor Link

By default, the overview shows a table of the environment's variables. Turn it off with:

{
  "variables": {
    "show": false
  }
}

To show {{placeholders}} instead of values in examples, set "resolve": false.

SecretsCopy Anchor Link

yaakdoc never inlines a variable that:

• is defined with a template function, such as secure(...), or
• has a name that matches variables.hide.

These show up as {{name}} placeholders in URLs and examples, and as <redacted> in the variables table.

The default hide patterns are token, secret, password, passwd, apikey, api_key, private, credential and auth. Matching is a substring match that ignores case and separators, so api_key also hides apiKey and X-API-KEY. Setting hide replaces the defaults, so include them if you still want them:

{
  "variables": {
    "hide": ["token", "secret", "password", "apikey", "api_key", "auth", "signing"]
  }
}

Choosing from the command lineCopy Anchor Link

--environment (-e) overrides the config, which is handy for building the docs once per environment:

npx yaakdoc build -e Staging --base /staging/ --out-dir dist/staging