Skip to content

Add a "Disabling features" reference page - #6549

Open
ctondreau wants to merge 1 commit into
mainfrom
docs/disabling-features-reference
Open

Add a "Disabling features" reference page#6549
ctondreau wants to merge 1 commit into
mainfrom
docs/disabling-features-reference

Conversation

@ctondreau

Copy link
Copy Markdown

Why

Pulling Ask AI analytics for the last 30 days (1,115 conversations, 74.5% resolved), "how do I turn off X" is one of the most consistent question clusters on the site. A sample of ~150 queries turned up readers trying to disable the Ask AI button, the MCP server, the API Explorer, Wiremock test generation, the Fern badge, and CSP.

The notable part: several had nearly the right YAML and still couldn't get there. One reader wrote:

Why isn't this disabling the MCP servers and Ask AI search in the docs.yaml file?

page-actions:
  options:
    ask-ai: false
    mcp: false
ai-search: {}

Every setting they used is real and documented. The gap is that they're scattered across Site settings, the API Reference layout page, and the Dashboard, and that ask-ai: false doesn't do what the name suggests.

What

Adds /learn/docs/configuration/disabling-features under Configuration, next to Site settings and Page settings. It's a router page: each entry says what to set and links to the canonical page rather than restating it.

It leads with the confusion the analytics surfaced most:

  • Ask Fern is a Dashboard toggle. No docs.yml key disables it.
  • page-actions.options.ask-ai: false hides the page action button only. It does not disable Ask Fern.
  • ai-search configures Ask Fern; it has no enable/disable property. ai-search: {} leaves it running with defaults.

Two other traps worth naming:

  • The MCP server toggle lives under page-actions.options despite controlling an endpoint rather than a button.
  • settings.disable-explorer-proxy is not an off switch for the API Explorer — it keeps the Explorer running and bypasses Fern's proxy. Turning the Explorer off is an empty playground.environments list.

Cross-links added from Configuration overview (new card), Site settings (Ask Fern configuration), Ask Fern overview (enable step), and Hiding content (features vs. content).

Scope notes

  • Everything on the page is verified against this repo. I dropped one claim I couldn't substantiate: a reader reported playground.environments: [] failing when set on an - api entry inside a tab in a product YAML. That may be a real bug, but I couldn't confirm the mechanism from the docs, so the page doesn't speculate. Worth a separate look.
  • Not covered, and not documented anywhere I could find: disabling CSP / setting a custom permissions-policy on the docs site, and disabling Wiremock test generation for the TypeScript SDK generator. Both came up in Ask AI. Removing the Fern badge from generated SDKs is whitelabel in generators.yml, which is SDK product territory rather than this page.
  • No zh translation — the zh overlay doesn't mirror every English page, so this follows existing practice.
  • fern check not run — the CLI isn't installed in this environment. Links were verified by hand against the YAML config per AGENTS.md, and every anchor target was confirmed to be a real ##/### heading.

Generated with Claude Code

Ask AI analytics show "how do I turn off X" is one of the most common
question clusters on the docs site, and several readers had the right
YAML and still couldn't get there. The settings exist but are scattered
across Site settings, the API Reference layout page, and the Dashboard.

Adds /learn/docs/configuration/disabling-features, a router page that
collects the documented off switches and links to each canonical page.
It leads with the confusion the analytics surfaced most: Ask Fern is a
Dashboard toggle, `page-actions.options.ask-ai` only hides the page
action button, and `ai-search` configures Ask Fern without enabling or
disabling it. Also flags that the MCP server toggle lives under
`page-actions` despite controlling an endpoint, and that
`disable-explorer-proxy` is not an off switch for the API Explorer.

Cross-links from the Configuration overview, Site settings, Ask Fern
overview, and Hiding content.

Co-Authored-By: Claude <noreply@anthropic.com>
@ctondreau
ctondreau requested a review from devalog as a code owner August 5, 2026 17:43
<Steps>
<Step title="Enable in the Dashboard">
Open the [Fern Dashboard](https://dashboard.buildwithfern.com/). Navigate to the **Settings** tab and click **Enable** on the Ask AI card.
Open the [Fern Dashboard](https://dashboard.buildwithfern.com/). Navigate to the **Settings** tab and click **Enable** on the Ask AI card. The same card [turns Ask Fern off](/learn/docs/configuration/disabling-features#ask-fern-and-the-ask-ai-button), which is separate from hiding the **Ask AI** page action button in `docs.yml`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[Microsoft.UIVerbs] Use 'select' instead of the input-specific verb 'click'.

| Ask Fern itself: AI search and the side panel | **Settings** > **Ask AI** card in the Dashboard |
| The **Ask AI** page action button | `page-actions.options.ask-ai: false` in `docs.yml` |

The [`ai-search` key](/learn/docs/configuration/site-level-settings#ask-fern-configuration) configures Ask Fern once it's enabled, setting PII masking, additional datasources, and the system prompt. It has no enable or disable property, so `ai-search: {}` leaves Ask Fern running with its default behavior.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'PII' has no definition.

| [AI-generated examples](/learn/docs/ai-features/ai-examples) in the API Reference | `ai-examples.enabled: false` |
| The [directive prepended to pages served to agents](/learn/docs/ai-features/llms-txt) | `agents.page-directive: ""` |

`settings.disable-explorer-proxy: true` is not an off switch for the Explorer. It keeps the Explorer running and sends requests directly to your API instead of through Fern's proxy, which requires CORS on your API. To turn the Explorer off, use an empty `playground.environments` list.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant