diff --git a/fern/products/docs/pages/changelog/2026-02-03.mdx b/fern/products/docs/pages/changelog/2026-02-03.mdx
index fa9f08d9d..78e311637 100644
--- a/fern/products/docs/pages/changelog/2026-02-03.mdx
+++ b/fern/products/docs/pages/changelog/2026-02-03.mdx
@@ -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
 
diff --git a/fern/products/docs/pages/customization/frontmatter.mdx b/fern/products/docs/pages/customization/frontmatter.mdx
index b50ee0293..89ac31cfc 100644
--- a/fern/products/docs/pages/customization/frontmatter.mdx
+++ b/fern/products/docs/pages/customization/frontmatter.mdx
@@ -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
diff --git a/fern/products/docs/pages/customization/site-level-settings.mdx b/fern/products/docs/pages/customization/site-level-settings.mdx
index 197472c41..319517dd3 100644
--- a/fern/products/docs/pages/customization/site-level-settings.mdx
+++ b/fern/products/docs/pages/customization/site-level-settings.mdx
@@ -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}>
@@ -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
diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx
index d4278b75f..171d4e022 100644
--- a/fern/products/docs/pages/navigation/overview.mdx
+++ b/fern/products/docs/pages/navigation/overview.mdx
@@ -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