Update docs.yml page to site-level settings (#1879)

devin-ai-integration[bot] · kgowru · devalog · web-flow · commit 0aa4c7701382 · 2025-11-10T11:55:35.000-05:00
Co-authored-by: Devin AI &lt;158243242+devin-ai-integration[bot]@users.noreply.github.com&gt;
Co-authored-by: Kapil Gowru &lt;k.gowru@gmail.com&gt;
Co-authored-by: Devin Logan &lt;devinannlogan@gmail.com&gt;
diff --git a/fern/docs.yml b/fern/docs.yml
@@ -292,7 +292,7 @@ redirects:
   - source: /learn/docs/getting-started/customer-showcase
     destination: https://buildwithfern.com/customers
   - source: /learn/docs/getting-started/global-configuration
-    destination: /learn/docs/configuration/what-is-docs-yml
+    destination: /learn/docs/configuration/site-level-settings
   - source: /learn/docs/getting-started/development
     destination: /learn/docs/preview-publish/previewing-changes-locally
   - source: /learn/docs/getting-started/publish-your-docs
@@ -375,7 +375,7 @@ redirects:
   - source: /learn/user-feedback
     destination: /learn/docs/user-feedback
   - source: /learn/docs/customization/what-is-docs-yml
-    destination: /learn/docs/configuration/what-is-docs-yml
+    destination: /learn/docs/configuration/site-level-settings
 
   # ============================================================================
   # CLI & API REFERENCE REDIRECTS
@@ -568,7 +568,7 @@ redirects:
   - source: /learn/docs/content
     destination: /learn/docs/writing-content/markdown
   - source: /learn/docs/config/overview
-    destination: /learn/docs/configuration/what-is-docs-yml
+    destination: /learn/docs/configuration/site-level-settings
   - source: /learn/docs/llms.txt8
     destination: /learn/docs/seo/llms-txt
   - source: /learn/docs/path/to/asset.pdf
diff --git a/fern/products/api-def/ferndef-pages/availability.mdx b/fern/products/api-def/ferndef-pages/availability.mdx
@@ -3,7 +3,7 @@ title: Availability in Fern Definition
 description: Add availability to Fern Definition API services, endpoints, types, or properties to indicate their release status.
 ---
 
-You can add `availability` to an endpoint, type, or property within your Fern Definition. You can configure the `availability` of sections in your API reference documentation in your [`docs.yml` file](/learn/docs/configuration/what-is-docs-yml). 
+You can add `availability` to an endpoint, type, or property within your Fern Definition. You can configure the `availability` of sections in your API Reference documentation in your [`docs.yml` file](/learn/docs/configuration/site-level-settings). 
 
 ## Endpoints, types, and properties
 
diff --git a/fern/products/api-def/openapi-pages/extensions/availability.mdx b/fern/products/api-def/openapi-pages/extensions/availability.mdx
@@ -5,7 +5,7 @@ description: Mark endpoint availability status using `x-fern-availability` exten
 
 The `x-fern-availability` extension is used to mark the availability of an endpoint within your OpenAPI definition. The availability information propagates into the generated Fern Docs website as visual tags. 
 
-You can configure the `availability` of sections in your API reference documentation in your [`docs.yml` file](/learn/docs/configuration/what-is-docs-yml). 
+You can configure the `availability` of sections in your API Reference documentation in your [`docs.yml` file](/learn/docs/configuration/site-level-settings). 
 
 ## Endpoint
 
@@ -32,4 +32,4 @@ This renders as:
 
 ## Section
 
-<Markdown src="/snippets/availability.mdx" />
+<Markdown src="/snippets/availability.mdx" />
diff --git a/fern/products/ask-fern/pages/getting-started/how-it-works.mdx b/fern/products/ask-fern/pages/getting-started/how-it-works.mdx
@@ -10,7 +10,7 @@ Ask Fern is a **Retrieval Augmented Generation (RAG)** system that appears as a
 Ask Fern appears as a resizable side panel on your documentation site. Users can drag to resize it or use the expand/minimize button to control their viewing experience.
 
 Key behaviors:
-- **Adaptive layout** – Seamlessly integrates with all [Fern Docs layouts](/docs/configuration/what-is-docs-yml#layout-configuration)
+- **Adaptive layout** – Seamlessly integrates with all [Fern Docs layouts](/docs/configuration/site-level-settings#layout-configuration)
 - **Persistent navigation** – Side panel stays open as users browse different pages or click links provided by the AI responses
 - **Document-specific queries** – Users can ask questions about the current page through a dropdown option
 - **Mobile optimization** – Expands to full screen when users start typing on mobile devices
diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml
@@ -15,8 +15,8 @@ navigation:
     icon: fa-regular fa-clock-rotate-left
   - section: Configuration
     contents:
-      - page: What is docs.yml?
-        path: ./pages/customization/what-is-docs-yml.mdx
+      - page: Site-level settings
+        path: ./pages/customization/site-level-settings.mdx
       - page: Navigation
         path: ./pages/navigation/overview.mdx
       - page: Tabs and tab variants
diff --git a/fern/products/docs/pages/accessibility/overview.mdx b/fern/products/docs/pages/accessibility/overview.mdx
@@ -25,7 +25,7 @@ Fern automatically enforces [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref
 - **UI elements**: 3:1 minimum
 - **Enhanced**: 7:1 when feasible ([WCAG AAA](https://www.w3.org/WAI/WCAG21/quickref/#contrast-enhanced))
 
-When you [configure colors in your `docs.yml` file](/learn/docs/configuration/what-is-docs-yml#colors-configuration), Fern validates accent colors. If your accent color doesn't meet the minimum contrast ratio against your background color, Fern will:
+When you [configure colors in your `docs.yml` file](/learn/docs/configuration/site-level-settings#colors-configuration), Fern validates accent colors. If your accent color doesn't meet the minimum contrast ratio against your background color, Fern will:
 
 1. Display a warning during `fern check` validation
 2. Automatically adjust the accent color at runtime to meet WCAG AA standards
diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx
@@ -8,7 +8,7 @@ description: Enable SDK code examples in TypeScript, Python, Go, and more from t
  <Note title="Dynamic snippets">
   By default, SDK snippets are static code examples. Alternatively, you can use dynamic SDK snippets that allow users to modify parameters and see code examples update in real time. 
   
-  To use dynamic snippets, [enable them in your `docs.yml`](/docs/configuration/what-is-docs-yml#dynamic-snippets-configuration) and then complete the setup instructions on this page.
+  To use dynamic snippets, [enable them in your `docs.yml`](/docs/configuration/site-level-settings#dynamic-snippets-configuration) and then complete the setup instructions on this page.
 </Note>
 
 <Frame>
diff --git a/fern/products/docs/pages/changelog/2025-11-02.mdx b/fern/products/docs/pages/changelog/2025-11-02.mdx
@@ -15,7 +15,7 @@ navbar-links:
         href: https://example.com/guides
 ```
 
-Learn more in the [navbar links configuration documentation](/learn/docs/configuration/what-is-docs-yml#navbar-links-configuration).
+Learn more in the [navbar links configuration documentation](/learn/docs/configuration/site-level-settings#navbar-links-configuration).
 
 ## API Explorer direct requests
 
@@ -30,4 +30,4 @@ settings:
 Your API must have CORS enabled to allow requests from the documentation domain.
 </Warning>
 
-Learn more in the [docs.yml reference documentation](/learn/docs/configuration/what-is-docs-yml#settingsdisable-explorer-proxy).
+Learn more in the [docs.yml reference documentation](/learn/docs/configuration/site-level-settings#settingsdisable-explorer-proxy).
diff --git a/fern/products/docs/pages/changelog/2025-11-03.mdx b/fern/products/docs/pages/changelog/2025-11-03.mdx
@@ -27,9 +27,9 @@ navigation:
 
 ## Custom icons across your navigation
 
-You can now use your own image files as icons throughout your `docs.yml` navigation config, including for [navbar link](/learn/docs/configuration/what-is-docs-yml#navbar-links-configuration), [section, page](/learn/docs/configuration/navigation#sidebar-icons), and [product](/learn/docs/configuration/products#add-your-product-configuration) icons.
+You can use your own image files as icons throughout your `docs.yml` navigation config, including for [navbar link](/learn/docs/configuration/site-level-settings#navbar-links-configuration), [section, page](/learn/docs/configuration/navigation#sidebar-icons), and [product](/learn/docs/configuration/products#add-your-product-configuration) icons.
 
-Icons now support three formats:
+Icons support three formats:
 - **Font Awesome icons**: Use icon names like `fa-solid fa-seedling` or `fa-regular fa-leaf`. Pro and Brand icons from Font Awesome are supported.
 - **Custom image files**: Use relative paths to custom image files (e.g., `./assets/icons/plant-icon.svg`). Paths are relative to the `docs.yml` file.
 - **Inline SVG**: Provide an SVG string wrapped in quotes.
diff --git a/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx b/fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx
@@ -4,7 +4,7 @@ subtitle: Add custom CSS, global JavaScript, and UI components.
 description: Add brand-specific styling, user interactions. and components to make your docs your own.
 ---
 
-This page covers how to customize your docs with CSS, JavaScript, and custom components. However, you can [customize many things directly in your `docs.yml` file](/docs/configuration/what-is-docs-yml), including colors, typography, navbar links, layout, analytics, and metadata. Try these built-in options first before adding custom code. 
+This page covers how to customize your docs with CSS, JavaScript, and custom components. However, you can [customize many things directly in your `docs.yml` file](/docs/configuration/site-level-settings), including colors, typography, navbar links, layout, analytics, and metadata. Try these built-in options first before adding custom code. 
 
 ## Custom CSS
 
@@ -53,7 +53,7 @@ css:
 
 <Note>
 For customizing the background, logo, font, and layout of your Docs via Fern's built-in styling, 
-check out the [Global Configuration](/learn/docs/configuration/what-is-docs-yml). 
+check out the [Global Configuration](/learn/docs/configuration/site-level-settings). 
 </Note>
 
 ### Common use cases
diff --git a/fern/products/docs/pages/customization/frontmatter.mdx b/fern/products/docs/pages/customization/frontmatter.mdx
@@ -177,7 +177,7 @@ max-toc-depth: 3
 <ParamField path="hide-nav-links" type="boolean" required={false} default={false}>
   Controls the conditional rendering of the navigation links (previous, next) at the bottom of the page. Set to true to disable this feature.
   
-  This can be set globally in the [global configuration](/learn/docs/configuration/what-is-docs-yml#layout-configuration).
+  This can be set globally in the [global configuration](/learn/docs/configuration/site-level-settings#layout-configuration).
 </ParamField>
 
 <CodeBlock title="Example hide-nav-links">
@@ -197,7 +197,7 @@ hide-nav-links: true
 <ParamField path="hide-feedback" type="boolean" required={false} default={false}>
   Controls the conditional rendering of the on-page feedback form at the bottom of the page. Set to true to disable this feature.
   
-  This can be set globally in the [global configuration](/learn/docs/configuration/what-is-docs-yml#layout-configuration).
+  This can be set globally in the [global configuration](/learn/docs/configuration/site-level-settings#layout-configuration).
 </ParamField>
 
 <CodeBlock title="Example hide-feedback">
@@ -250,7 +250,7 @@ Currently, relative paths are _not_ supported for this field.
 ## SEO metadata
 
 <Note title="Looking to set metadata across the entire site?">
- [Use the metadata field in the `docs.yml` file](/learn/docs/configuration/what-is-docs-yml#seo-metadata-configuration).
+ [Use the metadata field in the `docs.yml` file](/learn/docs/configuration/site-level-settings#seo-metadata-configuration).
 </Note>
 
 <Markdown src="/snippets/seo-metadata-page.mdx" />
diff --git a/fern/products/docs/pages/customization/site-level-settings.mdx b/fern/products/docs/pages/customization/site-level-settings.mdx
@@ -1,11 +1,11 @@
 ---
-title: "Docs.yml"
-subtitle: "Customize your documentation using the docs.yml file"
+title: "Customize site-level settings using docs.yml"
+subtitle: "Set theming, redirects, and more"
 description: "Learn how to configure your Fern documentation site with the docs.yml file. Customize colors, typography, layout, analytics and more."
 max-toc-depth: 2
 ---
 
-The `docs.yml` file is your primary tool for customizing your documentation site, including colors, typography, layout, analytics, and more. Start here for most customization needs before considering [custom CSS and JavaScript](/docs/customization/custom-css-js) for advanced use cases.
+The `docs.yml` file is your primary tool for customizing colors, typography, layout, analytics, and more across your documentation site. Start here for most customization needs before considering [custom CSS and JavaScript](/docs/customization/custom-css-js) for advanced use cases.
 
 ### YAML Schema Validation
 
diff --git a/fern/products/docs/pages/getting-started/overview.mdx b/fern/products/docs/pages/getting-started/overview.mdx
@@ -31,7 +31,7 @@ subtitle: A website builder for beautiful agent and developer-friendly docs.
       </div>
     </a>
     
-    <a class="fern-card interactive not-prose rounded-3 relative block border p-6 text-base" href="/docs/configuration/what-is-docs-yml">
+    <a class="fern-card interactive not-prose rounded-3 relative block border p-6 text-base" href="/docs/configuration/site-level-settings">
       <div class="flex items-start flex-col space-y-3">
         <img class="mx-auto dark:hidden" alt="Configure with ease" src="./images/configure.png" />
         <img class="mx-auto hidden dark:block" alt="Configure with ease" src="./images/configure-dark.png" />
diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx
@@ -68,7 +68,7 @@ The `assets` folder contains any images or videos used in your documentation. Yo
 
 The `docs.yml` file is the heart of your Fern documentation site. This configuration file controls your documentation's navigation structure, visual design, site functionality, and hosting settings.
 
-For complete configuration options, see the [docs.yml reference](/docs/configuration/what-is-docs-yml).
+For complete configuration options, see the [docs.yml reference](/docs/configuration/site-level-settings).
 
 <CodeBlock title="fern/docs.yml of this website">
 ```yml
@@ -180,6 +180,6 @@ title: Fern's Documentation
 
 ## `fern.config.json`
 
-<Markdown src="/snippets/fern-config-json-reference.mdx" />      
+<Markdown src="/snippets/fern-config-json-reference.mdx" />            
 
 
diff --git a/fern/products/docs/pages/navigation/products.mdx b/fern/products/docs/pages/navigation/products.mdx
@@ -236,7 +236,7 @@ If your product-specific `.yml` files for **versioned products** includes a `nav
 
 ### Add instance audiences
 
-Control which versions and/or products appear in each [documentation instance](/docs/configuration/what-is-docs-yml#instances-configuration) by tagging them with audiences. This enables separate sites for different user groups (e.g., internal developers, beta testers, public customers).
+Control which versions and/or products appear in each [documentation instance](/docs/configuration/site-level-settings#instances-configuration) by tagging them with audiences. This enables separate sites for different user groups (e.g., internal developers, beta testers, public customers).
 
 Content is filtered based on audience tags:
 
@@ -345,4 +345,4 @@ The dropdown menus for product and version selectors can be customized using the
       <img src="webflow-version-selector.avif" alt="Example of a styled version selector" />
     </Frame>
   </Tab>
-</Tabs>    
+</Tabs>        
diff --git a/fern/products/docs/pages/navigation/tabs.mdx b/fern/products/docs/pages/navigation/tabs.mdx
@@ -56,7 +56,7 @@ Here's an example of how a tabs implementation renders:
 
 ### Tabs placement
 
-Tabs display in the left sidebar by default. To display them horizontally, set `tabs-placement` to `header` in your [layout configuration](/docs/configuration/what-is-docs-yml#layout-configuration).
+Tabs display in the left sidebar by default. To display them horizontally, set `tabs-placement` to `header` in your [layout configuration](/docs/configuration/site-level-settings#layout-configuration).
 
 <CodeBlock title="docs.yml">
 ```yaml
diff --git a/fern/products/docs/pages/navigation/versions.mdx b/fern/products/docs/pages/navigation/versions.mdx
@@ -82,7 +82,7 @@ If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure
 </Step>
 <Step title="Add instance audiences">
 
-Control which versions appear in each [documentation instance](/docs/configuration/what-is-docs-yml#instances-configuration) by tagging them with audiences. This enables separate sites for different user groups (e.g., internal developers, beta testers, public customers).
+Control which versions appear in each [documentation instance](/docs/configuration/site-level-settings#instances-configuration) by tagging them with audiences. This enables separate sites for different user groups (e.g., internal developers, beta testers, public customers).
 
 Content is filtered based on audience tags:
 
@@ -139,4 +139,4 @@ The dropdown menu for the version selector can be customized using the `fern-ver
 
   <Frame>
     <img src="webflow-version-selector.avif" alt="Example of a styled version selector" />
-  </Frame>
+  </Frame>
diff --git a/fern/products/docs/pages/resources/stainless-comparison.mdx b/fern/products/docs/pages/resources/stainless-comparison.mdx
@@ -14,7 +14,7 @@ Choose Fern for enterprise requirements, regulated industries, or production-cri
 |------------|------|-----------|
 | **Maturity** | Production-ready, stable APIs | Early access, breaking changes expected |
 | **Authoring** | [Visual editor](/learn/docs/writing-content/fern-editor) + Git | Git only |
-| **Enterprise features** | [RBAC](/learn/docs/authentication/rbac), [SSO](/learn/docs/authentication/sso), [versioning](/learn/docs/configuration/what-is-docs-yml) | None |
+| **Enterprise features** | [RBAC](/learn/docs/authentication/rbac), [SSO](/learn/docs/authentication/sso), [versioning](/learn/docs/configuration/site-level-settings) | None |
 | **API testing** | [Interactive explorer](/learn/docs/api-references/api-explorer/overview) | None |
 | **Deployment** | Cloud + [full-stack self-hosted](/learn/docs/self-hosted/overview) | Static files only |
 
@@ -58,13 +58,13 @@ Stainless doesn't provide an interactive testing environment. Fern's [API Explor
 
 <Accordion title="RBAC, versioning, and multi-product support">
 
-Stainless doesn't currently offer audience-specific content filtering, multi-version APIs, or unified multi-product sites. Fern provides [RBAC](/learn/docs/authentication/rbac) and [versioning](/learn/docs/configuration/what-is-docs-yml) capabilities for complex API portfolios.
+Stainless doesn't offer audience-specific content filtering, multi-version APIs, or unified multi-product sites. Fern provides [RBAC](/learn/docs/authentication/rbac) and [versioning](/learn/docs/configuration/site-level-settings) capabilities for complex API portfolios.
 
 | Feature | Fern Docs | Stainless Docs |
 |---------|-----------|----------------|
 | **RBAC** | ✅ [Audience-based content filtering](/learn/docs/authentication/rbac) for internal vs. public sites | ❌ None |
-| **API versioning** | ✅ [Multi-version support](/learn/docs/configuration/what-is-docs-yml) with availability states and per-version content | ❌ None |
-| **Multi-product sites** | ✅ [Multiple products](/learn/docs/configuration/what-is-docs-yml) in unified documentation | ⚠️ Basic tabs (Guides/Reference) |
+| **API versioning** | ✅ [Multi-version support](/learn/docs/configuration/site-level-settings) with availability states and per-version content | ❌ None |
+| **Multi-product sites** | ✅ [Multiple products](/learn/docs/configuration/site-level-settings) in unified documentation | ⚠️ Basic tabs (Guides/Reference) |
 <br/>
 </Accordion>
 
diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx
@@ -8,7 +8,7 @@ Fern automatically generates all SEO metadata for every page in your documentati
 When you do want to customize SEO settings, you can set defaults [at the site level](#website-metadata) or override them on [individual pages](#page-level-configuration). Keep titles between 50-60 characters and descriptions between 150-160 characters for optimal display.
 
 <Note>
-    The metadata configurations on this page are for SEO and social tags that aren't visible to users. For visible footer links, see [footer links configuration](/learn/docs/configuration/what-is-docs-yml#footer-links-configuration).
+    The metadata configurations on this page are for SEO and social tags that aren't visible to users. For visible footer links, see [footer links configuration](/learn/docs/configuration/site-level-settings#footer-links-configuration).
 </Note>
 
 ## How it works
@@ -53,7 +53,7 @@ For every page, Fern creates these SEO tags in your HTML:
 
 ## Website metadata
 
-Set default SEO metadata for your entire documentation site in [`docs.yml`](/docs/configuration/what-is-docs-yml). These settings apply to all pages unless overridden by page-specific metadata.
+Set default SEO metadata for your entire documentation site in [`docs.yml`](/docs/configuration/site-level-settings). These settings apply to all pages unless overridden by page-specific metadata.
 
 <Markdown src="/snippets/seo-metadata-site.mdx" />
 
diff --git a/fern/snippets/redirects.mdx b/fern/snippets/redirects.mdx
@@ -56,7 +56,7 @@ redirects:
     destination: / # Don't do this
 ```
 
-Instead, [enable automatic homepage redirects in your `docs.yml`](/docs/configuration/what-is-docs-yml#settings-configuration) to send broken links to your homepage rather than showing a 404 page:
+Instead, [enable automatic homepage redirects in your `docs.yml`](/docs/configuration/site-level-settings#settings-configuration) to send broken links to your homepage rather than showing a 404 page:
 
 ```yaml title="docs.yml"
 settings:
