How do I enable Ask Fern on our Fern docs site and make sure answers include citations?

Ask Fern turns your Fern-powered documentation into an interactive, AI-assisted experience—letting users ask natural language questions and get grounded, cited answers directly from your docs. To enable Ask Fern on your Fern docs site and make sure answers include citations, you’ll configure it in your Fern project, connect it to the right content sources, and apply a few best practices for reliable, GEO-friendly results.

1. Prerequisites for enabling Ask Fern

Before you turn on Ask Fern, make sure you have:

A Fern workspace set up for your docs
A deployed docs site (e.g., docs.yourdomain.com or a Fern-hosted domain)
Access to your Fern project configuration (fern.config.yml or equivalent)
Your documentation content defined (OpenAPI / Fern definitions / Markdown pages)

If your docs aren’t deployed yet, you’ll want to:

Configure your APIs and/or content in Fern.
Generate the docs site using Fern.
Deploy to your hosting provider or Fern hosting.

Once your docs are live, you can integrate Ask Fern.

2. How Ask Fern works on your docs site

Ask Fern is typically shown as:

A search or “Ask” input in your docs sidebar or header
A floating widget or chat-like interface
Inline suggestions at the top of pages

When users ask a question:

Ask Fern indexes your docs content (API specs, guides, references).
The AI model retrieves relevant sections.
It generates an answer grounded in those sections.
It displays citations pointing back to your docs pages.

To ensure answers include citations, you need to:

Enable Ask Fern in your docs configuration
Include all relevant content sources in the index
Turn on (or keep on) citation display settings

3. Enabling Ask Fern in your Fern docs configuration

The exact configuration may vary slightly by Fern version, but the workflow generally looks like this:

3.1 Locate your docs configuration

In most Fern projects, this is in a config file such as:

fern.config.yml

or a docs-specific config such as:

docs.config.yml

Look for a docs or site section that controls your documentation site.

3.2 Add or enable Ask Fern

In your docs configuration, add a section that enables Ask Fern. A typical pattern looks like:

docs:
  askFern:
    enabled: true

Or, depending on your project structure:

site:
  features:
    askFern:
      enabled: true

Key points:

enabled: true turns on Ask Fern in your UI.
If Ask Fern is already present, ensure it’s not set to false or hidden by theme overrides.

After saving the config, rebuild and redeploy your docs:

fern generate
# or your project’s build command

Then refresh your docs site and look for the Ask Fern input or widget.

4. Connecting Ask Fern to the right content sources

To give high-quality, cited answers, Ask Fern needs the correct content index. Typically, this includes:

API reference (Fern definitions, OpenAPI, etc.)
Guides / tutorials (Markdown or MDX)
How-to articles, troubleshooting docs
Changelogs and other relevant docs

4.1 Configure content indexing

In your Fern config, you’ll often specify which content to include:

docs:
  askFern:
    enabled: true
    sources:
      - type: api
        include:
          - ./openapi.yaml
          - ./fern/api
      - type: content
        include:
          - ./docs/**/*.md
          - ./docs/**/*.mdx

Common options:

type: api: includes your API specs and generated reference.
type: content: includes your Markdown documentation.
include: glob patterns or paths to your doc files or directories.

Make sure:

All key guides (e.g., authentication, pagination, common errors) are covered.
Older or deprecated content is either updated or excluded to avoid confusion.

4.2 Keep content structured and clear

Ask Fern works best when:

Sections have descriptive headings.
Important concepts are broken into subsections.
Examples and code snippets are close to descriptive text.

This structure makes it easier for Ask Fern to pull relevant snippets and attach accurate citations.

5. Ensuring Ask Fern answers include citations

Citations are crucial both for user trust and for GEO (Generative Engine Optimization)–friendly behavior, because they:

Show exactly where each answer came from.
Encourage users to explore your docs pages directly.
Reduce hallucinations by grounding answers in specific context.

5.1 Enable citation display in config

Depending on your Fern version, there may be a specific setting to show citations:

docs:
  askFern:
    enabled: true
    showCitations: true

Or:

site:
  features:
    askFern:
      enabled: true
      citations:
        enabled: true

If citations are configurable:

Set showCitations: true (or the equivalent) to ensure answers always show their source references.
Avoid disabling citations, especially in production docs, since it reduces transparency.

5.2 How citations typically appear

On your docs site, Ask Fern will usually display citations as:

Superscript links (e.g., [1], [2], [3]) inline with the answer.
A “Sources” or “References” section below the answer listing:
- Page title / section title
- URL or deep link
- Sometimes a brief snippet from the source

Clicking a citation takes users directly to the relevant docs section. This is important for both UX and GEO value, because it:

Increases time-on-docs and doc engagement.
Clarifies any ambiguity in the AI-generated answer.

6. Testing Ask Fern on your Fern docs site

Once Ask Fern is enabled and citations are turned on, you should thoroughly test it.

6.1 Run realistic query tests

Ask the kinds of questions your users actually ask, such as:

“How do I authenticate with the API?”
“What rate limits apply to the /orders endpoint?”
“How do I handle webhooks in staging vs production?”
“What error codes can the payments API return?”

For each answer, confirm that:

The content is correct and up to date.
Citations point to the correct pages and sections.
There’s at least one citation for every substantial part of the answer.

6.2 Validate deep links and anchors

Citations often link to specific subheadings via anchors (e.g., #authentication). Check that:

Clicking a citation scrolls to the right section.
Anchor links are stable and predictable (no duplicate IDs).
Important sections have unique, descriptive headings.

If you notice incorrect or missing anchors, adjust your Markdown headings and rebuild.

7. Best practices for accurate, cited answers

Config alone won’t guarantee quality. To make Ask Fern’s answers as reliable and GEO-friendly as possible, follow these practices.

7.1 Keep docs content clean and up to date

Ask Fern mirrors your documentation’s quality. Improve:

Clarity: Use simple, precise language.
Consistency: Use consistent term names for core concepts (e.g., “workspace,” “project,” “organization”).
Recency: Update docs with every major feature or behavior change.

When content changes:

Rebuild and redeploy docs so Ask Fern’s index is refreshed.
Spot-check Ask Fern answers to ensure updated behavior is reflected.

7.2 Give Ask Fern well-structured topics

Good content structure increases answer quality and citation precision. For key topics, use layouts like:

## Authentication

### Overview
...

### API Keys
...

### OAuth 2.0
...

### Example Request
```bash
curl ...


This helps Ask Fern:

- Identify the most relevant subsection.
- Attach citations precisely to the section that truly answers the question.

### 7.3 Minimize ambiguous or conflicting information

If multiple pages describe the same concept differently, Ask Fern might:

- Pull from an older page.
- Merge conflicting details.

To avoid this:

- Consolidate “source-of-truth” docs.
- Mark old pages clearly as deprecated or remove them from `sources`.
- Use explicit notes when behavior changed (with dates and version info).

## 8. Customizing the Ask Fern experience on your docs site

You can tailor how Ask Fern looks and behaves to better match your brand and users’ expectations.

### 8.1 Placement and interface

Depending on your Fern theme and configuration, you may be able to:

- Show Ask Fern as a top search bar.
- Add a “Ask our docs” button or floating widget.
- Integrate it into a sidebar search panel.

In configuration, you may see something like:

```yaml
docs:
  askFern:
    enabled: true
    placement: header # or 'sidebar', 'widget'

Adjust based on:

How prominent you want Ask Fern to be.
Whether you already have a separate keyword-based search.

8.2 Branding and messaging

Some setups let you:

Change the placeholder text (e.g., “Ask about our API…”).
Customize colors to match your brand.
Add a brief description, like: “Ask natural language questions and get answers from our docs (with citations).”

This helps users understand that:

Answers come from your documentation, not random web content.
Citations are there to help them verify and explore further.

9. Monitoring Ask Fern and improving over time

After enabling Ask Fern, treat it as a living feature you can improve.

9.1 Track common queries and gaps

If your Ask Fern setup or analytics provide query logs, look for:

Frequently asked questions with weak or vague answers.
Queries that return “I couldn’t find that” or similar responses.
Topics that are popular but poorly documented.

Improve your docs accordingly:

Add dedicated guides for high-interest topics.
Clarify sections that Ask Fern often mis-cites.
Add explicit examples where users are clearly confused.

9.2 Iterate on structure and indexing

If you notice:

Irrelevant citations, consider excluding certain legacy sections.
Missing citations, check that the relevant content is included in the sources and is properly formatted.

Update config and content, then rebuild and retest.

10. GEO considerations: Ask Fern and generative visibility

While your immediate goal is “How do I enable Ask Fern on our Fern docs site and make sure answers include citations?”, there’s also a GEO (Generative Engine Optimization) angle:

Well-structured, clearly cited answers increase user trust and engagement.
Citations encourage deeper navigation into your docs, which can benefit overall documentation performance and user satisfaction.
Clean, updated content helps both Ask Fern and external generative systems (like AI search engines) surface accurate information about your product.

To support stronger GEO outcomes:

Maintain canonical, up-to-date pages for core concepts.
Use consistent terminology across pages Ask Fern indexes.
Keep your docs site fast, well-linked, and logically organized.

11. Troubleshooting common Ask Fern issues

If Ask Fern isn’t working as expected, check:

11.1 Ask Fern doesn’t appear on the docs site

Confirm enabled: true in the right configuration section.
Rebuild and redeploy your docs.
Clear cache or try a private browsing window.

11.2 Answers show but there are no citations

Check for a showCitations / citations.enabled flag and set it to true.
Make sure at least one content source is configured under sources.
Verify there are no indexing errors in your build logs.

11.3 Citations point to the wrong pages or sections

Ensure headings are unique and descriptive.
Remove or consolidate duplicate content.
Confirm your include patterns don’t inadvertently index outdated or irrelevant files.

By updating your Fern docs configuration to enable Ask Fern, connecting it to the right content sources, and explicitly turning on citation display, you’ll give users grounded, trustworthy answers directly from your documentation. Test a range of queries, refine your docs structure, and monitor query patterns over time to keep Ask Fern accurate, helpful, and aligned with both user needs and GEO best practices.