Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.markapidown.net/llms.txt

Use this file to discover all available pages before exploring further.

MarkApiDown resolves every {{variable}} reference in your endpoint specs at execution time through a layered variable system. Define base URLs and shared values in api-docs/_shared/env.md, store secrets safely outside of version control in .env.local, and override anything on the fly with MAD_* OS environment variables or --var CLI flags. All four layers stack on top of each other — higher layers win without modifying the underlying file.

​
Defining environments in env.md

The file api-docs/_shared/env.md holds your named environment definitions. Each environment is a second-level heading (## <name>) followed by a fenced yaml code block containing key-value pairs. Here is the real _shared/env.md from the JSONPlaceholder example project: 
# Environments

## dev

\`\`\`yaml
baseUrl: https://jsonplaceholder.typicode.com
postId: 1
userId: 1
\`\`\`
You can add as many environment sections as you need. Each section is independent — dev values are never mixed into staging runs: 
# Environments

## dev

\`\`\`yaml
baseUrl: https://jsonplaceholder.typicode.com
postId: 1
userId: 1
\`\`\`

## staging

\`\`\`yaml
baseUrl: https://staging.myapi.example.com
postId: 10
userId: 5
apiVersion: v2
\`\`\`

## prod

\`\`\`yaml
baseUrl: https://api.myapi.example.com
apiVersion: v2
\`\`\`
Every key defined here becomes a {{variable}} you can use in any spec under api-docs/.

​
Variable resolution order

When mad resolves a {{variable}} reference, it searches four sources in order from lowest to highest priority. A value found in a higher-priority source overrides the same key from any lower-priority source.
1

_shared/env.md (chosen environment)

The baseline values for the environment you pass with --env. This is where non-sensitive, team-shared configuration lives — base URLs, IDs, version strings.
2

.env.local

A file at your project root, next to api-docs/. It is gitignored automatically by mad init. Put API keys, tokens, passwords, and any other secret here. Values defined in .env.local override those in env.md.
3

MAD_* OS environment variables

Any OS environment variable whose name starts with MAD_ is injected after stripping the prefix and converting to camelCase. For example, MAD_API_TOKEN becomes {{apiToken}}. Use this layer in CI pipelines and Docker containers.
4

--var key=value CLI flags

The highest-priority layer. Pass --var key=value (repeatable) on any mad exec, mad flow, or mad request command. These values override everything else — useful for one-off test runs without touching any file.

​
Referencing variables in specs

Use {{variableName}} anywhere in the ## Request section — URL, headers, or body: 
GET {{baseUrl}}/posts/{{postId}}
Accept: application/json
Authorization: Bearer {{apiToken}}

POST {{baseUrl}}/users
Content-Type: application/json

{
  "role": "{{defaultRole}}",
  "version": "{{apiVersion}}"
}
MarkApiDown reports an error before sending the request if any {{variable}} cannot be resolved in the active layer stack.

​
Switching environments

Pass --env=<name> to any mad command to select a different environment section from env.md: 
# Run against dev (the default)
mad exec api-docs/apis/posts/get-post-by-id.md --env=dev

# Run against staging
mad exec api-docs/apis/posts/get-post-by-id.md --env=staging

# Run a pipeline against prod (confirm before doing this!)
mad flow api-docs/flows/user-onboarding.md --env=prod
If you omit --env, MarkApiDown uses the default-env value from api-docs/mad.md (set to dev by mad init). In the browser UI (mad serve), use the environment switcher dropdown in the top navigation bar to change environments globally for all requests made from that session.

​
Adding a new environment

Open api-docs/_shared/env.md and add a new ## <name> section with its yaml block: 
## qa

\`\`\`yaml
baseUrl: https://qa.myapi.example.com
postId: 99
apiVersion: v1
featureFlag: true
\`\`\`
Save the file, then run mad exec ... --env=qa immediately — no restarts or rebuilds required.

​
Keeping secrets out of markdown

Never put secrets — API keys, tokens, passwords, or credentials of any kind — inside env.md or any spec file. These files are committed to version control and visible to anyone with repository access. Put secrets in .env.local or in MAD_* OS environment variables instead.

​
.env.local format

Create .env.local at your project root (the directory that contains api-docs/). Each line is a KEY=VALUE pair. Lines starting with # are comments. 
# .env.local — gitignored, never commit this file

apiToken=sk-live-abc123xyz
databasePassword=hunter2
stripeSecretKey=sk_live_...
mad init automatically adds .env.local to your .gitignore. Verify this with mad doctor.

​
MAD_* environment variables

Set MAD_-prefixed variables in your shell, CI secrets store, or container environment. MarkApiDown strips the prefix and converts SCREAMING_SNAKE_CASE to camelCase automatically:
Environment variableTemplate variable
MAD_API_TOKEN{{apiToken}}
MAD_BASE_URL{{baseUrl}}
MAD_STRIPE_SECRET_KEY{{stripeSecretKey}}
For example, in a GitHub Actions workflow you would inject a secret like this: 
MAD_API_TOKEN=$SECRET_API_TOKEN mad exec api-docs/apis/auth/login.md --env=staging

​
One-off variable overrides

Use --var for a single run without touching any file: 
mad exec api-docs/apis/posts/get-post-by-id.md \
  --env=dev \
  --var postId=42 \
  --var baseUrl=http://localhost:9000
Pass --var multiple times to inject several values in one command.