From 758ebda5b157e9afec1d4235d1f211502a286f68 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sat, 18 Oct 2025 19:51:49 +0000
Subject: [PATCH 1/4] docs: add ai-search configuration to docs.yml reference
 and update Ask Fern getting started

Co-Authored-By: ryanstep@buildwithfern.com <ryanstep@umich.edu>
---
 .../getting-started/what-is-ask-fern.mdx      |  2 +-
 .../pages/customization/what-is-docs-yml.mdx  | 27 +++++++++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx b/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx
index d236e392e..fa2cd0c00 100644
--- a/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx
+++ b/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx
@@ -5,7 +5,7 @@ description: Let your customers find answers in your documentation instantly.
 
 Ask Fern is Fern's AI Search feature that indexes your documentation and provides an interface for your end users to ask questions and get answers. It appears as a side panel on your documentation site so users can ask questions without leaving the page. 
 
-You can turn Ask Fern on or off via the [Fern Dashboard](https://dashboard.buildwithfern.com/).
+You can configure Ask Fern via the [Fern Dashboard](https://dashboard.buildwithfern.com/) or directly in your [`docs.yml` file](/learn/docs/configuration/what-is-docs-yml#ai-search-configuration).
 
 <Frame>
   <video 
diff --git a/fern/products/docs/pages/customization/what-is-docs-yml.mdx b/fern/products/docs/pages/customization/what-is-docs-yml.mdx
index ee98ff5ea..c6ad5875a 100644
--- a/fern/products/docs/pages/customization/what-is-docs-yml.mdx
+++ b/fern/products/docs/pages/customization/what-is-docs-yml.mdx
@@ -619,6 +619,33 @@ analytics:
   Your PostHog project API key. Defaults to the api-host of "https://us.i.posthog.com".
 </ParamField> 
 
+## AI search configuration
+
+Configure [Ask Fern](/learn/ask-fern/getting-started/what-is-ask-fern), Fern's AI-powered search feature, to control where it appears and what content it can access.
+
+```yaml docs.yml
+ai-search:
+  location:
+    - docs
+    - slack
+    - discord
+  datasources:
+    - url: https://example.com/additional-docs
+      title: Additional Documentation
+```
+
+<ParamField path="ai-search.location" type="list of strings" required={false} toc={true}>
+  Specifies where Ask Fern will be available. Options include `docs` (documentation site), `slack` (Slack integration), and `discord` (Discord integration). Learn more about [locations and datasources configuration](/learn/ask-fern/configuration/locations-and-datasources).
+</ParamField>
+
+<ParamField path="ai-search.datasources" type="list of objects" required={false} toc={true}>
+  Additional content sources that Ask Fern should index and search. Each datasource requires a `url` and optional `title`. Learn more about [locations and datasources configuration](/learn/ask-fern/configuration/locations-and-datasources).
+</ParamField>
+
+<Note>
+  Ask Fern can also be configured via the [Fern Dashboard](https://dashboard.buildwithfern.com/). Configuration in `docs.yml` provides version control and allows for preview environment testing.
+</Note>
+
 ## Dynamic snippets configuration
 
 By default, SDK snippets are static code examples that are displayed in your API Reference. Alternatively, you can use dynamic SDK snippets that allow users to modify parameters and see code examples update in real time. 

From 0977a10cba0509289e64fe747cd2f6ab34962c68 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sat, 18 Oct 2025 20:06:50 +0000
Subject: [PATCH 2/4] docs: simplify ParamField descriptions and move auxiliary
 info to Note

Co-Authored-By: ryanstep@buildwithfern.com <ryanstep@umich.edu>
---
 fern/products/docs/pages/customization/what-is-docs-yml.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/fern/products/docs/pages/customization/what-is-docs-yml.mdx b/fern/products/docs/pages/customization/what-is-docs-yml.mdx
index c6ad5875a..e341e44f1 100644
--- a/fern/products/docs/pages/customization/what-is-docs-yml.mdx
+++ b/fern/products/docs/pages/customization/what-is-docs-yml.mdx
@@ -635,15 +635,15 @@ ai-search:
 ```
 
 <ParamField path="ai-search.location" type="list of strings" required={false} toc={true}>
-  Specifies where Ask Fern will be available. Options include `docs` (documentation site), `slack` (Slack integration), and `discord` (Discord integration). Learn more about [locations and datasources configuration](/learn/ask-fern/configuration/locations-and-datasources).
+  Specifies where Ask Fern will be available. Options: `docs`, `slack`, `discord`.
 </ParamField>
 
 <ParamField path="ai-search.datasources" type="list of objects" required={false} toc={true}>
-  Additional content sources that Ask Fern should index and search. Each datasource requires a `url` and optional `title`. Learn more about [locations and datasources configuration](/learn/ask-fern/configuration/locations-and-datasources).
+  Additional content sources that Ask Fern should index and search. Each datasource requires a `url` and optional `title`.
 </ParamField>
 
 <Note>
-  Ask Fern can also be configured via the [Fern Dashboard](https://dashboard.buildwithfern.com/). Configuration in `docs.yml` provides version control and allows for preview environment testing.
+  Ask Fern can also be configured via the [Fern Dashboard](https://dashboard.buildwithfern.com/). Configuration in `docs.yml` provides version control and allows for preview environment testing. Learn more about [locations and datasources configuration](/learn/ask-fern/configuration/locations-and-datasources).
 </Note>
 
 ## Dynamic snippets configuration

From 5bf3849d91febfc6103e01efd33f2f2e3107547d Mon Sep 17 00:00:00 2001
From: Devin Logan <devinannlogan@gmail.com>
Date: Thu, 30 Oct 2025 10:49:38 -0400
Subject: [PATCH 3/4] consolidate setup info

---
 fern/docs.yml                                 |  2 +
 fern/products/ask-fern/ask-fern.yml           |  5 +-
 .../locations-and-datasources.mdx             | 67 ++-----------------
 .../getting-started/what-is-ask-fern.mdx      | 34 +++++++---
 .../pages/customization/what-is-docs-yml.mdx  | 27 +-------
 fern/snippets/ask-fern-config.mdx             | 33 +++++++++
 6 files changed, 71 insertions(+), 97 deletions(-)
 create mode 100644 fern/snippets/ask-fern-config.mdx

diff --git a/fern/docs.yml b/fern/docs.yml
index 853f20502..e623657d8 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -461,6 +461,8 @@ redirects:
     destination: /learn/ask-fern/features/citations
   - source: /learn/ask-fern/custom-prompting
     destination: /learn/ask-fern/configuration/custom-prompts
+  - source: /learn/ask-fern/configuration/locations-and-datasources
+    destination: /learn/ask-fern/configuration/setup
 
   # General Ask Fern patterns
   - source: /learn/ai-search/getting-started/:slug*
diff --git a/fern/products/ask-fern/ask-fern.yml b/fern/products/ask-fern/ask-fern.yml
index 5415b8d6b..bcfc656a7 100644
--- a/fern/products/ask-fern/ask-fern.yml
+++ b/fern/products/ask-fern/ask-fern.yml
@@ -9,10 +9,11 @@ navigation:
         href: https://buildwithfern.com/showcase#ask-fern-customers
   - section: Configuration
     contents:
+      - page: Setup
+        path: ./pages/configuration/locations-and-datasources.mdx
+        slug: setup
       - page: Custom prompts
         path: ./pages/configuration/custom-prompting.mdx
-      - page: Locations and datasources
-        path: ./pages/configuration/locations-and-datasources.mdx
       - page: Guidance
         path: ./pages/features/guidance.mdx
       - page: Documents
diff --git a/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx b/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx
index 693ef1191..f34f1b89e 100644
--- a/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx
+++ b/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx
@@ -1,83 +1,26 @@
 ---
-title: Locations and Datasources
+title: Setup
 subtitle: Configure where Ask Fern is available and what content it can access.
 ---
 
-Ask Fern can be configured to appear in multiple locations and pull content from various datasources. This allows you to provide AI-powered assistance wherever your users need it and ensure access to relevant information.
+## Basic setup
 
-## Locations
-
-The `location` field in your `ai-search` configuration determines where Ask Fern will be available to your users. You can specify one or more locations:
+Enable Ask Fern by adding the `ai-search` configuration to your `docs.yml` file:
 
 ```yaml docs.yml
 ai-search:
   location:
     - docs
     - slack
-    - discord
 ```
 
-### Available Locations
-
-<ParamField path="docs" type="string">
-  Enables Ask Fern on your documentation site. Users will see the AI search interface directly in your docs.
-</ParamField>
-
-<ParamField path="slack" type="string">
-  Enables Ask Fern in Slack. Learn more about the [Slack app integration](/ask-fern/features/slack-app).
-</ParamField>
-
-<ParamField path="discord" type="string">
-  Enables Ask Fern in Discord. This allows your community to get AI-powered answers in your Discord server.
-</ParamField>
-
-## Datasources (coming soon)
-
-The `datasources` field allows you to specify additional content sources that Ask Fern should index and search. This is useful when you want to include content from external websites or documentation that isn't part of your main docs.
-
-```yaml docs.yml
-ai-search:
-  datasources:
-    - url: https://example.com/additional-docs
-      title: Additional Documentation
-    - url: https://blog.example.com
-      title: Company Blog
-```
-
-### Website Datasources
-
-<ParamField path="url" type="string" required>
-  The URL of the website to index. Ask Fern will crawl and index the content from this URL.
-</ParamField>
-
-<ParamField path="title" type="string">
-  An optional display name for this datasource. This helps users understand where the information is coming from when Ask Fern cites content from this source.
-</ParamField>
+## Configuration
 
-## Preview Environments
+<Markdown src="/snippets/ask-fern-config.mdx" />
 
-Setting `location: [docs]` enables Ask Fern on preview deployments generated with `fern generate --docs --preview`, allowing you to test the AI search functionality before publishing to production.
 
-<Note>
-  Preview environments don't interfere with your production Ask Fern deployment.
-</Note>
 
-## Best Practices
 
-<AccordionGroup>
-  <Accordion title="Start with docs location">
-    Begin by enabling Ask Fern on your documentation site (`location: [docs]`) to test and refine the experience before expanding to other channels like Slack or Discord.
-  </Accordion>
 
-  <Accordion title="Use descriptive titles for datasources">
-    Always provide a `title` for your datasources. This helps users understand the source of information when Ask Fern provides citations.
-  </Accordion>
 
-  <Accordion title="Keep datasources relevant">
-    Only include datasources that contain information relevant to your users' questions. Too many datasources can dilute the quality of search results.
-  </Accordion>
 
-  <Accordion title="Test with previews">
-    Use preview deployments to test your Ask Fern configuration, including locations and datasources, before deploying to production.
-  </Accordion>
-</AccordionGroup>
diff --git a/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx b/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx
index fa2cd0c00..143b04687 100644
--- a/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx
+++ b/fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx
@@ -5,8 +5,6 @@ description: Let your customers find answers in your documentation instantly.
 
 Ask Fern is Fern's AI Search feature that indexes your documentation and provides an interface for your end users to ask questions and get answers. It appears as a side panel on your documentation site so users can ask questions without leaving the page. 
 
-You can configure Ask Fern via the [Fern Dashboard](https://dashboard.buildwithfern.com/) or directly in your [`docs.yml` file](/learn/docs/configuration/what-is-docs-yml#ai-search-configuration).
-
 <Frame>
   <video 
     style={{ aspectRatio: '16 / 9', width: '100%' }}
@@ -24,9 +22,27 @@ Ask Fern helps you:
 - **Accelerate user onboarding** – Help users integrate your product faster by surfacing relevant code samples and guides.
 - **Identify documentation gaps** – Understand where your docs need improvement through user search patterns and feedback.
 
-## Get started
+
+## Quickstart
+
+Enable Ask Fern in your [`docs.yml` file](/learn/ask-fern/configuration/setup):
+
+```yaml docs.yml
+ai-search:
+  location:
+    - docs
+    - slack # or discord
+```
 
 <CardGroup cols={2}>
+  <Card 
+    title="Setup"
+    icon="regular lightbulb"
+    href="/learn/ask-fern/configuration/setup"
+  >
+    Configure locations and additional data sources.
+  </Card>
+  
   <Card 
     title="How it works"
     icon="regular lightbulb"
@@ -35,6 +51,12 @@ Ask Fern helps you:
     Learn about Ask Fern's interface, behavior, and technical architecture.
   </Card>
 
+</CardGroup>
+
+## Features 
+
+<CardGroup cols={2}>
+
   <Card 
     title="Custom prompting"
     icon="regular book-open"
@@ -43,12 +65,6 @@ Ask Fern helps you:
     Write custom prompts to improve accuracy and tailor responses for your users. 
   </Card>
 
-</CardGroup>
-
-## Features 
-
-<CardGroup cols={2}>
-
   <Card 
     title="Analytics" 
     icon="regular fa-chart-simple"
diff --git a/fern/products/docs/pages/customization/what-is-docs-yml.mdx b/fern/products/docs/pages/customization/what-is-docs-yml.mdx
index e341e44f1..6cb7a85b9 100644
--- a/fern/products/docs/pages/customization/what-is-docs-yml.mdx
+++ b/fern/products/docs/pages/customization/what-is-docs-yml.mdx
@@ -619,32 +619,11 @@ analytics:
   Your PostHog project API key. Defaults to the api-host of "https://us.i.posthog.com".
 </ParamField> 
 
-## AI search configuration
+## Ask Fern configuration
 
-Configure [Ask Fern](/learn/ask-fern/getting-started/what-is-ask-fern), Fern's AI-powered search feature, to control where it appears and what content it can access.
+Specify [Ask Fern](/learn/ask-fern/getting-started/what-is-ask-fern) to control where it appears and what content it can access.
 
-```yaml docs.yml
-ai-search:
-  location:
-    - docs
-    - slack
-    - discord
-  datasources:
-    - url: https://example.com/additional-docs
-      title: Additional Documentation
-```
-
-<ParamField path="ai-search.location" type="list of strings" required={false} toc={true}>
-  Specifies where Ask Fern will be available. Options: `docs`, `slack`, `discord`.
-</ParamField>
-
-<ParamField path="ai-search.datasources" type="list of objects" required={false} toc={true}>
-  Additional content sources that Ask Fern should index and search. Each datasource requires a `url` and optional `title`.
-</ParamField>
-
-<Note>
-  Ask Fern can also be configured via the [Fern Dashboard](https://dashboard.buildwithfern.com/). Configuration in `docs.yml` provides version control and allows for preview environment testing. Learn more about [locations and datasources configuration](/learn/ask-fern/configuration/locations-and-datasources).
-</Note>
+<Markdown src="/snippets/ask-fern-config.mdx" />
 
 ## Dynamic snippets configuration
 
diff --git a/fern/snippets/ask-fern-config.mdx b/fern/snippets/ask-fern-config.mdx
new file mode 100644
index 000000000..f3ac34250
--- /dev/null
+++ b/fern/snippets/ask-fern-config.mdx
@@ -0,0 +1,33 @@
+```yaml docs.yml
+ai-search:
+  location:
+    - docs
+    - slack
+    - discord
+  datasources:
+    - url: https://example.com/additional-docs
+      title: Additional documentation
+    - url: https://blog.example.com
+      title: Company blog
+```
+
+<ParamField path="ai-search.location" type="list of strings" required={false} toc={true}>
+  Specifies where Ask Fern will be available. Options: 
+  - `docs` enables Ask Fern on your documentation site
+  - `slack` enables Ask Fern in Slack
+  - `discord` enables Ask Fern in Discord
+
+  Most users should enable Ask Fern for both `docs` and either `slack` or `discord`. 
+</ParamField>
+
+<ParamField path="ai-search.datasources" type="list of objects" required={false} toc={true}>
+  Additional content sources that Ask Fern should index and search.
+</ParamField>
+
+<ParamField path="datasources.url" type="string" required={true}>
+  The URL of the website to index. Ask Fern will crawl and index the content from this URL.
+</ParamField>
+
+<ParamField path="datasources.title" type="string">
+  An optional display name for this datasource. This helps users understand where the information is coming from when Ask Fern cites content from this source.
+</ParamField>
\ No newline at end of file

From fbc2ca563d74abd6fcb378954ad2b0db2157f671 Mon Sep 17 00:00:00 2001
From: Devin Logan <devinannlogan@gmail.com>
Date: Thu, 30 Oct 2025 10:56:12 -0400
Subject: [PATCH 4/4] set max-toc-depth

---
 .../ask-fern/pages/configuration/locations-and-datasources.mdx   | 1 +
 1 file changed, 1 insertion(+)

diff --git a/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx b/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx
index f34f1b89e..434075665 100644
--- a/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx
+++ b/fern/products/ask-fern/pages/configuration/locations-and-datasources.mdx
@@ -1,6 +1,7 @@
 ---
 title: Setup
 subtitle: Configure where Ask Fern is available and what content it can access.
+max-toc-depth: 2
 ---
 
 ## Basic setup