Environment Configuration Reference: _shared/env.md

Every MarkApiDown project keeps its environment-specific variables in a single shared file: api-docs/_shared/env.md. Each environment — dev, staging, production, and any custom names you define — gets its own ## heading containing a fenced YAML block of key-value pairs. When you run a command with --env staging, MarkApiDown reads only the ## staging block and makes those values available to all your endpoint specs as {{variableName}} references.

Never put secrets — API tokens, passwords, private keys, or any other sensitive value — in env.md. This file is committed to version control. Store secrets in .env.local (git-ignored) or as MAD_* operating-system environment variables instead.

Complete example

A typical _shared/env.md defines at least a dev environment and grows as you add deployment targets. The following example is drawn from the JSONPlaceholder sample project included with MarkApiDown.

# Environments

## dev

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

## staging

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

Commonly used variables

Variable	Purpose
`baseUrl`	Root URL prepended to all request paths — `{{baseUrl}}/posts/:postId`
`postId`	Path parameter for post-related endpoints — `/posts/:postId`
`userId`	Path parameter or request body field for user-scoped requests

You can define any additional key-value pairs your specs need. Variable names are camelCase by convention, but MarkApiDown accepts any non-empty string.

Adding a new environment

Add a new ## section to _shared/env.md using the same name you plan to pass to --env. Then run mad validate api-docs/ to confirm the file parses correctly.

## preview

\`\`\`yaml
baseUrl: https://preview.example.com
postId: 1
userId: 1
\`\`\`

Activate it in a command:

mad exec api-docs/posts/get-post-by-id.md --env preview

Variable resolution order

MarkApiDown resolves {{variableName}} references by layering four sources. Later sources override earlier ones, so CLI flags always win.

env.md — environment block

MarkApiDown reads the ## section in _shared/env.md that matches the active environment name (e.g. ## dev). This is the baseline for every request.

.env.local — local overrides

MarkApiDown looks for .env.local in your project root (the directory containing api-docs/). Values here override the env block. This file is never committed to version control.

MAD_* OS environment variables

Any OS-level environment variable whose name starts with MAD_ is mapped into the variable context. The MAD_ prefix is stripped and the remainder is converted to camelCase: MAD_API_TOKEN → apiToken.

--var flags on the command line

Inline variables passed as --var key=value take the highest priority and override all other sources. Useful for one-off overrides in CI pipelines.

mad exec api-docs/posts/get-post-by-id.md --env staging --var postId=42

Secrets management

Keep secrets out of env.md entirely. Use one of these two mechanisms instead.

.env.local
MAD_* env vars

Create a .env.local file in your project root (the directory that contains api-docs/). Write one KEY=value pair per line. Lines starting with # are comments.

# .env.local  — never commit this file
token=eyJhbGciOiJIUzI1NiJ9.my-secret-token
apiKey=sk-live-abc123
dbPassword=hunter2

mad init automatically adds .env.local to your .gitignore. If you add the file manually, add this line to .gitignore yourself:

.env.local

Reference these values in any spec exactly like env variables:

GET {{baseUrl}}/users
Authorization: Bearer {{token}}

Export variables from your shell or CI environment using the MAD_ prefix. MarkApiDown strips the prefix and converts the remainder to camelCase before making the value available in specs.

# Shell export
export MAD_API_TOKEN=sk-live-abc123
export MAD_DB_PASSWORD=hunter2

# Now available in specs as {{apiToken}} and {{dbPassword}}
mad exec api-docs/posts/get-post-by-id.md --env production

In a CI pipeline (e.g. GitHub Actions), inject them as environment variables in the job step:

- name: Run API contract tests
  env:
    MAD_API_TOKEN: ${{ secrets.API_TOKEN }}
  run: mad exec api-docs/posts/get-post-by-id.md --env staging

.gitignore entry

mad init adds .env.local to your .gitignore automatically. If you manage your own .gitignore, add the entry manually:

# MarkApiDown local secrets — never commit
.env.local

Run mad doctor at any time to confirm .env.local is excluded:

✓ .env.local in .gitignore

Browser UI: the Variables drawer

When you open the web preview with mad serve, the Variables drawer in the sidebar shows all resolved variables for the active environment. It splits them into two tabs:

Env

Variables sourced from the ## <env> block in env.md. These are read-only in the browser and reflect the file on disk.

Browser

Variables stored in localStorage for the current browser session. Use these to temporarily override an env variable without modifying any file — useful for pasting in a token during manual testing.

Browser-tab overrides are local to your browser and are never written back to env.md or .env.local.

Documentation Index

​Complete example

​Commonly used variables

​Adding a new environment

​Variable resolution order

​Secrets management

​.gitignore entry

​Browser UI: the Variables drawer

Env

Browser

Complete example

Commonly used variables

Adding a new environment

Variable resolution order

Secrets management

.gitignore entry

Browser UI: the Variables drawer