Skip to content

docs: small clarifying updates to new availability and env var params #3454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
devalog merged 1 commit into from
Feb 3, 2026
Merged

docs: small clarifying updates to new availability and env var params #3454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion fern/products/docs/pages/changelog/2026-02-03.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ availability: beta

Valid values are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`.

Learn more about [frontmatter availability](/learn/docs/customization/frontmatter#availability).
Learn more about [frontmatter availability](/learn/docs/configuration/page-level-settings#availability).

## Folder section overviews with index files

Expand Down
4 changes: 2 additions & 2 deletions fern/products/docs/pages/customization/frontmatter.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -315,10 +315,10 @@ Currently, relative paths are _not_ supported for this field.
## Availability

<ParamField path="availability" type="string" required={false}>
Displays an availability badge on the page. When set in frontmatter, it overrides any availability defined in the navigation (`docs.yml`). Valid values are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`.
Displays an availability badge on the page. When set in frontmatter, it overrides any [availability defined in the navigation](/learn/docs/configuration/navigation#availability) (`docs.yml`). Valid values are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`.
</ParamField>

<CodeBlock title="Example availability">
<CodeBlock title="fern/docs/pages/getting-started/feature.mdx">
```mdx
---
title: New feature
Expand Down
27 changes: 11 additions & 16 deletions fern/products/docs/pages/customization/site-level-settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -646,7 +646,7 @@ settings:
http-snippets: false
hide-404-page: true
use-javascript-as-typescript: false
substitute-env-vars: false
substitute-env-vars: true
```

<ParamField path="settings.search-text" type="string" required={false} default="Search" toc={true}>
Expand Down Expand Up @@ -705,26 +705,21 @@ settings:
</ParamField>

<ParamField path="settings.substitute-env-vars" type="boolean" required={false} default="false" toc={true}>
When set to true, substitutes `${ENV_VAR}` expressions with environment variable values across your documentation. This includes Markdown/MDX content and API specifications (OpenAPI, Fern definitions). Use this to inject dynamic values like API keys, URLs, or version numbers at build time.
If set to true, replaces `${ENV_VAR}` expressions with environment variable values at build time. Useful for injecting API keys, base URLs, or version numbers into your docs.

To output a literal `${VAR}` without substitution, escape it as `\$\{VAR\}`.
```mdx title="example.mdx"
Connect to our API at ${API_BASE_URL}/v1

<Note>
JavaScript files are excluded from substitution to avoid conflicts with template literals.
</Note>
Your API key: ${API_KEY}
```

During local preview (`fern docs dev`), undefined environment variables are replaced with empty strings to prevent errors. During publishing, undefined environment variables will cause the build to fail.
Substitution works in Markdown/MDX files and API specifications (OpenAPI, Fern definitions). JavaScript files are excluded to avoid conflicts with template literals.

```yaml title="docs.yml"
settings:
substitute-env-vars: true
```

```mdx title="example.mdx"
Connect to our API at ${API_BASE_URL}/v1
To output a literal `${VAR}`, escape it as `\$\{VAR\}`.

Your API key: ${API_KEY}
```
<Note>
During local preview (`fern docs dev`), undefined variables resolve to empty strings. During publishing, undefined variables cause the build to fail.
</Note>
</ParamField>

## Page actions configuration
Expand Down
9 changes: 6 additions & 3 deletions fern/products/docs/pages/navigation/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,11 +190,14 @@ navigation:

## Availability

Set availability for individual pages, sections, or folders. Pages inherit availability from their parent section or folder unless explicitly overridden.
Set availability badges on pages, sections, or folders. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`.

Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`.
Pages inherit availability from their parent section or folder unless overridden by:
- A per-page `availability` setting in `docs.yml` (shown below)
- [Page frontmatter availability](/learn/docs/configuration/page-level-settings#availability), which takes precedence over all `docs.yml` availability

```yaml Availability {3, 11, 14}

```yaml docs.yml {3, 11, 14}
navigation:
- section: Developer resources
availability: generally-available
Expand Down
Loading