docs.yml

instances:
  - url: fern.docs.buildwithfern.com/learn
    custom-domain: buildwithfern.com/learn
    edit-this-page:
      github:
        owner: fern-api
        repo: docs
        branch: main
      launch: dashboard

title: Fern Documentation

translations:
  - lang: en
    default: true
  - lang: zh

ai-search:
  location:
    - docs
  datasources:
    - url: https://buildwithfern.com/pricing
      title: Fern pricing

metadata:
  og:dynamic: true
  og:dynamic:show-url: false
  og:dynamic:show-gradient: false
  og:dynamic:show-logo: false
  og:dynamic:background-image: https://fern-docs.s3.us-east-2.amazonaws.com/fern-docs-og_image.png
  canonical-host: buildwithfern.com


products:
  - display-name: Home
    path: ./products/home/home.yml
    image: ./images/product-switcher/product-switcher-home-light.png
    subtitle: Products that elevate your developer experience 
  
  - display-name: SDKs
    path: ./products/sdks/sdks.yml
    icon: fa-brands fa-codepen
    image: ./images/product-switcher/product-switcher-sdks-light.png
    slug: sdks
    subtitle: Generate client libraries in multiple languages
  
  - display-name: Docs
    path: ./products/docs/docs.yml
    icon: fa-regular fa-browser
    image: ./images/product-switcher/product-switcher-docs-light.png
    slug: docs
    subtitle: Generate beautiful, interactive documentation websites

  - display-name: Dashboard
    path: ./products/dashboard/dashboard.yml
    icon: fa-regular fa-grid-2
    image: ./images/product-switcher/product-switcher-dashboard-light.png
    slug: dashboard
    subtitle: Manage your Fern projects and settings

  - display-name: CLI Reference
    subtitle: Manage and configure your Fern projects
    path: ./products/cli-api-reference/cli-api-reference.yml
    icon: fa-regular fa-terminal
    image: ./images/product-switcher/product-switcher-cliapi-light.png
    slug: cli-api-reference

  - display-name: API Definitions
    path: ./products/api-def/api-def.yml
    icon: fa-regular fa-book
    image: ./images/product-switcher/openapi-definition-light.png
    slug: api-definitions
    subtitle: Import and configure your API specifications
    announcement:
      message: '<a href="/learn/api-definitions/ferndef/overview">Fern Definition</a> is no longer actively recommended for new projects but remains supported for existing users.'

  - display-name: OpenAPI
    href: /learn/api-definitions/openapi/overview
    icon: fa-regular fa-book
    image: ./images/product-switcher/openapi-definition-light.png
    subtitle: Define REST and webhook APIs
  
  - display-name: AsyncAPI
    href: /learn/api-definitions/asyncapi/overview
    icon: fa-regular fa-bolt
    image: ./images/product-switcher/asyncapi-light.png
    subtitle: Define event-driven and WebSocket APIs

  - display-name: OpenRPC
    href: /learn/api-definitions/openrpc/overview
    icon: fa-regular fa-code
    image: ./images/product-switcher/openrpc-light.png
    subtitle: Define JSON-RPC APIs
  
  - display-name: gRPC
    href: /learn/api-definitions/grpc/overview
    icon: fa-regular fa-plug
    image: ./images/product-switcher/grpc-light.png
    subtitle: Define APIs with Protocol Buffers

css: ./assets/styles.css

footer: ./components/FernFooter.tsx

navbar-links:
  - type: minimal
    text: Book a demo
    url: https://buildwithfern.com/book-demo?utm_source=fern-docs
  - type: secondary
    text: Log in
    url: https://dashboard.buildwithfern.com/login?utm_source=fern-docs
  - type: filled
    text: Start for free
    url: https://dashboard.buildwithfern.com/sign-up?redirect_on_login=%2Fget-started&utm_source=fern-docs

typography:
  bodyFont:
    name: GT-Planar
    paths:
      - path: ./assets/GT-Planar.woff2
        weight: 400
      - path: ./assets/GT-Planar-Medium.woff2
        weight: 500
      - path: ./assets/GT-Planar-Bold.woff2
        weight: 600 700
  headingsFont:
    name: GT-Planar-Bold
    path: ./assets/GT-Planar-Bold.woff2
    weight: 600 700

logo:
  href: / 
  light: ./images/logo-primary.svg
  dark: ./images/logo-white.svg
  height: 20
colors:
  accent-primary:
    dark: "#70E155"
    light: "#008700"
  background:
    dark: "#111113"
    light: "#FFFFFF"
  border: 
    dark: "#393A40"
    light: "#E0E1E6"
  header-background:
    dark: "#111113"
    light: "#FFFFFF"
  card-background:
    dark: "#222325"
    light: "#FFFFFF"
favicon: ./images/favicon_32.png

layout:
  page-width: 1504px
  header-height: 75px
  searchbar-placement: header
  tabs-placement: header

theme:
  page-actions: toolbar
  footer-nav: minimal

settings:
  http-snippets:
    - curl

js:
  - path: ./rive-animation.js
    strategy: afterInteractive

agents:
  page-directive: "For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt."

analytics:
  # posthog:
  #   api-key: ${POSTHOG_API_KEY}
  gtm:
    container-id: GTM-55W3VNDW

experimental:
  mdx-components:
    - ./components
    
# Redirects for new docs structure migration
redirects:

  # ============================================================================
  # ROOT
  # ============================================================================
  - source: /learn
    destination: /learn/home
  - source: /learn/welcome
    destination: /learn/home

  # ============================================================================
  # SDKS
  # ============================================================================

  # SDK capabilities (specifics before catchall)
  - source: /learn/sdks/capabilities/method-names
    destination: /learn/sdks/deep-dives/customize-method-names
  - source: /learn/sdks/capabilities/idiomatic-method-names
    destination: /learn/sdks/deep-dives/customize-method-names
  - source: /learn/sdks/capabilities/auto-pagination
    destination: /learn/sdks/deep-dives/auto-pagination
  - source: /learn/sdks/capabilities/idempotency-headers
    destination: /learn/sdks/deep-dives/idempotency
  - source: /learn/sdks/capabilities/integration-tests
    destination: /learn/sdks/deep-dives/testing
  - source: /learn/sdks/capabilities/augment-with-custom-code
    destination: /learn/sdks/overview/custom-code
  - source: /learn/sdks/capabilities/o-auth-token-refresh
    destination: /learn/sdks/reference/generators-yml#auth-schemes
  - source: /learn/sdks/capabilities/retries-with-backoff
    destination: /learn/sdks/deep-dives/retries-with-backoff
  - source: /learn/sdks/capabilities/web-sockets
    destination: /learn/api-definitions/ferndef/websockets
  - source: /learn/sdks/capabilities/merging-multiple-apis
    destination: /learn/api-definitions/overview/project-structure#multiple-apis
  - source: /learn/sdks/capabilities/:slug*
    destination: /learn/sdks/overview/introduction

  # SDK features (deprecated)
  - source: /learn/sdks/features
    destination: /learn/sdks/overview/capabilities
  - source: /learn/sdks/features/:slug*
    destination: /learn/sdks/overview/capabilities

  # SDK guides (specifics before catchall)
  - source: /learn/sdks/guides/preview-your-sdk-locally
    destination: /learn/sdks/deep-dives/local-previews
  - source: /learn/sdks/guides/generate-your-first-sdk
    destination: /learn/sdks/overview/quickstart
  - source: /learn/sdks/guides/publish-a-public-facing-sdk
    destination: /learn/sdks/overview/introduction
  - source: /learn/sdks/guides/publish-to-package-managers/npm-type-script
    destination: /learn/sdks/generators/typescript/publishing
  - source: /learn/sdks/guides/publish-to-package-managers/pypi
    destination: /learn/sdks/generators/python/publishing
  - source: /learn/sdks/guides/publish-to-package-managers/nuget
    destination: /learn/sdks/generators/csharp/publishing
  - source: /learn/sdks/guides/publish-to-package-managers/pkgsite
    destination: /learn/sdks/generators/go/publishing
  - source: /learn/sdks/guides/publish-to-package-managers/maven-central
    destination: /learn/sdks/generators/java/publishing
  - source: /learn/sdks/guides/publish-to-package-managers/rubygems
    destination: /learn/sdks/generators/ruby/publishing
  - source: /learn/sdks/guides/publish-to-package-managers/packagist
    destination: /learn/sdks/generators/php/publishing
  - source: /learn/sdks/guides/publish-to-package-managers/:slug*
    destination: /learn/sdks/generators/:slug*
  - source: /learn/sdks/package-managers/:slug*
    destination: /learn/sdks/generators/typescript/publishing
  - source: /learn/sdks/guides/:slug*
    destination: /learn/sdks/overview/introduction

  # SDK getting-started (catchall)
  - source: /learn/sdks/getting-started/:slug*
    destination: /learn/sdks/overview/introduction

  # SDK introduction (legacy)
  - source: /learn/sdks/introduction/configuration
    destination: /learn/sdks/overview/introduction
  - source: /learn/sdks/introduction/language-support
    destination: /learn/sdks/overview/introduction
  - source: /learn/sdks/introduction/overview
    destination: /learn/sdks/overview/introduction
  - source: /learn/sdks/introduction/customer-showcase
    destination: /learn/sdks/overview/introduction
  - source: /learn/sdks/introduction/changelog/ts/:slug*
    destination: /learn/sdks/generators/typescript/changelog/:slug*
  - source: /learn/sdks/introduction/changelog/python/:slug*
    destination: /learn/sdks/generators/python/changelog/:slug*
  - source: /learn/sdks/introduction/changelog/csharp/:slug*
    destination: /learn/sdks/generators/csharp/changelog/:slug*
  - source: /learn/sdks/introduction/changelog/go/:slug*
    destination: /learn/sdks/generators/go/changelog/:slug*
  - source: /learn/sdks/introduction/changelog/java/:slug*
    destination: /learn/sdks/generators/java/changelog/:slug*
  - source: /learn/sdks/introduction/changelog/ruby/:slug*
    destination: /learn/sdks/generators/ruby/changelog/:slug*
  - source: /learn/sdks/introduction/changelog/php/:slug*
    destination: /learn/sdks/generators/php/changelog/:slug*

  # SDK overview (renamed pages)
  - source: /learn/sdks/overview/set-up-the-fern-folder
    destination: /learn/sdks/overview/quickstart
  - source: /learn/sdks/overview/github
    destination: /learn/sdks/overview/project-structure
  - source: /learn/sdks/fern-folder
    destination: /learn/sdks/overview/quickstart

  # SDK generators (renamed pages)
  - source: /learn/sdks/generators/mcp-server
    destination: /learn/sdks/overview/introduction
  - source: /learn/sdks/generators/java/publishing-to-maven-central
    destination: /learn/sdks/generators/java/publishing
  - source: /learn/sdks/generators/php/publishing-to-packagist
    destination: /learn/sdks/generators/php/publishing
  - source: /learn/sdks/generators/python/publishing-to-py-pi
    destination: /learn/sdks/generators/python/publishing
  - source: /learn/sdks/generators/typescript/publishing-to-npm
    destination: /learn/sdks/generators/typescript/publishing
  - source: /learn/sdks/generators/java/adding-custom-code
    destination: /learn/sdks/generators/java/custom-code

  # SDK reference
  - source: /learn/sdks/reference/generators-yml-reference
    destination: /learn/sdks/reference/generators-yml
  - source: /learn/sdks/reference/configuration
    destination: /learn/sdks/reference/generators-yml

  # SDK misc legacy paths
  - source: /learn/sdks/client
    destination: /learn/sdks/overview/introduction
  - source: /learn/sdks/src
    destination: /learn/sdks/overview/project-structure
  - source: /learn/sdks/alternatives/speakeasy
    destination: /learn/sdks/overview/introduction

  # ============================================================================
  # DOCS
  # ============================================================================

  # Docs getting-started (legacy)
  - source: /learn/docs/getting-started/customer-showcase
    destination: https://buildwithfern.com/customers
  - source: /learn/docs/getting-started/global-configuration
    destination: /learn/docs/configuration/site-level-settings
  - source: /learn/docs/getting-started/development
    destination: /learn/docs/preview-publish/preview-changes
  - source: /learn/docs/getting-started/publish-your-docs
    destination: /learn/docs/preview-publish/publishing-your-docs
  - source: /learn/docs/getting-started/changelog/:slug*
    destination: /learn/docs/changelog/:slug*

  # Docs building-and-customizing-your-docs (legacy)
  - source: /learn/docs/building-and-customizing-your-docs/navigation
    destination: /learn/docs/configuration/navigation
  - source: /learn/docs/building-and-customizing-your-docs/versioning
    destination: /learn/docs/configuration/versions
  - source: /learn/docs/building-and-customizing-your-docs/announcements
    destination: /learn/docs/customization/announcement-banner
  - source: /learn/docs/building-and-customizing-your-docs/links-and-redirects
    destination: /learn/docs/seo/redirects
  - source: /learn/docs/building-and-customizing-your-docs/customizing-slugs
    destination: /learn/docs/seo/configuring-slugs
  - source: /learn/docs/building-and-customizing-your-docs/hiding-content
    destination: /learn/docs/customization/hiding-content
  - source: /learn/docs/building-and-customizing-your-docs/pull-request-preview
    destination: /learn/docs/preview-publish/preview-changes
  - source: /learn/docs/building-and-customizing-your-docs/product-switching
    destination: /learn/docs/configuration/products
  - source: /learn/docs/building-and-customizing-your-docs/custom-css-global-js
    destination: /learn/docs/customization/custom-css-js
  - source: /learn/docs/building-and-customizing-your-docs/custom-domain
    destination: /learn/docs/preview-publish/setting-up-your-domain
  - source: /learn/docs/building-and-customizing-your-docs/rbac
    destination: /learn/docs/authentication/features/rbac
  - source: /learn/docs/building-and-customizing-your-docs/search
    destination: /learn/docs/customization/search
  - source: /learn/docs/building-your-docs/:slug*
    destination: /learn/docs/building-and-customizing-your-docs/:slug*

  # Docs navigation (legacy)
  - source: /learn/docs/navigation/overview
    destination: /learn/docs/configuration/navigation
  - source: /learn/docs/navigation/versions
    destination: /learn/docs/configuration/versions
  - source: /learn/docs/navigation/announcement-banner
    destination: /learn/docs/customization/announcement-banner
  - source: /learn/docs/navigation/hiding-content
    destination: /learn/docs/customization/hiding-content
  - source: /learn/docs/navigation/products
    destination: /learn/docs/configuration/products
  - source: /learn/docs/navigation/changelogs
    destination: /learn/docs/configuration/changelogs
  - source: /learn/docs/configuration/navigation/navigation
    destination: /learn/docs/configuration/navigation
  - source: /learn/docs/configuration/folder-based-navigation
    destination: /learn/docs/configuration/navigation

  # Docs content → writing-content (legacy)
  - source: /learn/docs/content/write-markdown
    destination: /learn/docs/writing-content/markdown-basics
  - source: /learn/docs/content/components/:slug*
    destination: /learn/docs/writing-content/components/:slug*
  - source: /learn/docs/content/custom-react-components
    destination: /learn/docs/customization/custom-react-components
  - source: /learn/docs/content/frontmatter
    destination: /learn/docs/configuration/page-level-settings
  - source: /learn/docs/content/reusable-snippets
    destination: /learn/docs/writing-content/reusable-snippets
  - source: /learn/docs/content/changelog
    destination: /learn/docs/configuration/changelogs
  - source: /learn/docs/content/visual-editor-beta
    destination: /learn/docs/writing-content/fern-editor
  - source: /learn/docs/content/visual-editor
    destination: /learn/docs/writing-content/fern-editor
  - source: /learn/docs/content
    destination: /learn/docs/writing-content/markdown-basics

  # Docs writing-content (renamed pages)
  - source: /learn/docs/writing-content/markdown
    destination: /learn/docs/writing-content/markdown-basics
  - source: /learn/docs/writing-content/custom-react-components
    destination: /learn/docs/customization/custom-react-components
  - source: /learn/docs/writing-content/custom-react-components/custom-header-and-footer
    destination: /learn/docs/customization/header-and-footer
  - source: /learn/docs/writing-content/reusable-markdown
    destination: /learn/docs/writing-content/reusable-snippets
  - source: /learn/docs/writing-content/visual-editor
    destination: /learn/docs/writing-content/fern-editor
  - source: /learn/docs/writing-content/code-blocks
    destination: /learn/docs/writing-content/components/code-blocks

  # Docs components (renamed)
  - source: /learn/docs/writing-content/components/accordion-groups
    destination: /learn/docs/writing-content/components/accordions
  - source: /learn/docs/writing-content/components/card-groups
    destination: /learn/docs/writing-content/components/cards
  - source: /learn/docs/writing-content/components/embed
    destination: /learn/docs/writing-content/components/download
  - source: /learn/docs/writing-content/components/sticky-tables
    destination: /learn/docs/writing-content/components/tables
  - source: /learn/docs/components/tabs
    destination: /learn/docs/writing-content/components/tabs
  - source: /learn/docs/components/CustomCard
    destination: /learn/docs/customization/custom-react-components

  # Docs customization
  - source: /learn/docs/configuration/global-themes
    destination: /learn/docs/customization/global-themes
  - source: /learn/docs/customization/custom-header-and-footer
    destination: /learn/docs/customization/header-and-footer
  - source: /learn/docs/customization/changelogs
    destination: /learn/docs/configuration/changelogs
  - source: /learn/docs/customization/what-is-docs-yml
    destination: /learn/docs/configuration/site-level-settings
  - source: /learn/docs/customization/project-structure
    destination: /learn/docs/getting-started/project-structure
  - source: /learn/docs/customization/shakespeare-mode
    destination: /learn/docs/getting-started/quickstart

  # Docs configuration
  - source: /learn/docs/configuration/what-is-docs-yml
    destination: /learn/docs/configuration/site-level-settings
  - source: /learn/docs/config/overview
    destination: /learn/docs/configuration/site-level-settings

  # Docs preview-publish (renamed pages)
  - source: /learn/docs/preview-publish/previewing-changes-in-a-pr
    destination: /learn/docs/preview-publish/preview-changes
  - source: /learn/docs/preview-publish/previewing-changes-locally
    destination: /learn/docs/preview-publish/preview-changes

  # Docs api-references
  - source: /learn/docs/api-references/endpoint-errors
    destination: /learn/docs/api-references/customize-api-reference-layout#displaying-endpoint-errors
  - source: /learn/docs/api-references/generate-api-ref#api-reference-configuration-options
    destination: /learn/docs/api-references/customize-api-reference-layout#configuration-options
  - source: /learn/docs/api-references/server-urls
    destination: /learn/docs/api-references/api-explorer#multiple-environments
  - source: /learn/docs/api-references/api-playground
    destination: /learn/docs/api-references/api-explorer
  - source: /learn/docs/api-references/api-playground/:slug*
    destination: /learn/docs/api-references/api-explorer/:slug*
  - source: /learn/docs/api-references/api-explorer/advanced-configuration
    destination: /learn/docs/api-references/api-explorer

  # Docs authentication → new setup/features structure
  - source: /learn/docs/authentication/password-protection
    destination: /learn/docs/authentication/setup/password-protection
  - source: /learn/docs/authentication/sso
    destination: /learn/docs/authentication/setup/sso
  - source: /learn/docs/authentication/jwt
    destination: /learn/docs/authentication/setup/jwt
  - source: /learn/docs/authentication/oauth
    destination: /learn/docs/authentication/setup/oauth
  - source: /learn/docs/authentication/rbac
    destination: /learn/docs/authentication/features/rbac
  - source: /learn/docs/authentication/api-key-injection
    destination: /learn/docs/authentication/features/api-key-injection

  # Docs authentication legacy paths
  - source: /learn/docs/authentication/rbac/overview
    destination: /learn/docs/authentication/features/rbac
  - source: /learn/docs/authentication/api-key-injection/overview
    destination: /learn/docs/authentication/features/api-key-injection
  - source: /learn/docs/authentication/set-up-oauth
    destination: /learn/docs/authentication/setup/oauth
  - source: /learn/docs/authentication/jwt-setup
    destination: /learn/docs/authentication/setup/jwt
  - source: /learn/docs/authentication/oauth-setup
    destination: /learn/docs/authentication/setup/oauth
  - source: /learn/docs/authentication/auth-setup/jwt-setup
    destination: /learn/docs/authentication/setup/jwt
  - source: /learn/docs/authentication/auth-setup/oauth-setup
    destination: /learn/docs/authentication/setup/oauth
  - source: /learn/docs/authentication/rbac/jwt-setup
    destination: /learn/docs/authentication/setup/jwt
  - source: /learn/docs/authentication/rbac/oauth-setup
    destination: /learn/docs/authentication/setup/oauth
  - source: /learn/docs/authentication/api-key-injection/jwt-setup
    destination: /learn/docs/authentication/setup/jwt
  - source: /learn/docs/authentication/api-key-injection/oauth-setup
    destination: /learn/docs/authentication/setup/oauth

  # Docs AI features (renamed pages)
  - source: /learn/docs/ai/scribe-coming-soon
    destination: /learn/docs/ai-features/fern-writer
  - source: /learn/docs/ai/scribe
    destination: /learn/docs/ai-features/fern-writer
  - source: /learn/docs/ai/slack-app
    destination: /learn/docs/ai-features/fern-writer
  - source: /learn/docs/ai/writer
    destination: /learn/docs/ai-features/fern-writer
  - source: /learn/docs/ai/llms-txt
    destination: /learn/docs/ai-features/llms-txt
  - source: /learn/docs/ai/mcp-server
    destination: /learn/docs/ai-features/mcp-server
  - source: /learn/docs/ai-features/writer
    destination: /learn/docs/ai-features/fern-writer
  - source: /learn/docs/ai-features/mcp-server/overview
    destination: /learn/docs/ai-features/mcp-server
  - source: /learn/docs/seo/llms-txt
    destination: /learn/docs/ai-features/llms-txt
  - source: /learn/docs/developer-tools/view-markdown
    destination: /learn/docs/ai-features/markdown
  - source: /learn/docs/scribe-api/slack-scribe/get-scribe-slack-install-link
    destination: /learn/docs/ai-features/fern-writer

  # Docs self-hosted / alternatives
  - source: /learn/docs/enterprise/self-hosted
    destination: /learn/docs/self-hosted/overview
  - source: /learn/docs/alternatives/mintlify
    destination: /learn/docs/getting-started/overview

  # ============================================================================
  # API DEFINITIONS
  # ============================================================================

  # API definition introduction (legacy)
  - source: /learn/api-definition/introduction
    destination: /learn/api-definitions/overview/what-is-an-api-definition
  - source: /learn/api-definition/introduction/what-is-an-api-definition
    destination: /learn/api-definitions/overview/what-is-an-api-definition
  - source: /learn/api-definition/introduction/what-is-the-fern-folder
    destination: /learn/api-definitions/overview/project-structure

  # OpenAPI (specifics before catchall)
  - source: /learn/api-definition/openapi/endpoints
    destination: /learn/api-definitions/openapi/endpoints/http
  - source: /learn/api-definition/openapi/endpoints/:slug*
    destination: /learn/api-definitions/openapi/endpoints/:slug*
  - source: /learn/api-definition/openapi/extensions
    destination: /learn/api-definitions/openapi/extensions/overview
  - source: /learn/api-definition/openapi/extensions/:slug*
    destination: /learn/api-definitions/openapi/extensions/:slug*
  - source: /learn/api-definition/openapi/frameworks
    destination: /learn/api-definitions/openapi/frameworks
  - source: /learn/api-definition/openapi/frameworks/:slug*
    destination: /learn/api-definitions/openapi/frameworks/:slug*
  - source: /learn/api-definition/openapi/webhooks
    destination: /learn/api-definitions/openapi/endpoints/webhooks
  - source: /learn/api-definition/openapi/streaming-and-sse
    destination: /learn/api-definitions/openapi/endpoints/sse
  - source: /learn/api-definition/openapi/audiences
    destination: /learn/api-definitions/openapi/extensions/audiences
  - source: /learn/api-definition/openapi/examples
    destination: /learn/api-definitions/openapi/extensions/request-response-examples
  - source: /learn/api-definition/openapi/:slug*
    destination: /learn/api-definitions/openapi/:slug*
  - source: /learn/api-definitions/openapi/extensions
    destination: /learn/api-definitions/openapi/extensions/overview
  - source: /learn/api-definitions/openapi/extensions/others
    destination: /learn/api-definitions/openapi/extensions/overview
  - source: /learn/api-definitions/openapi/extensions/server-names
    destination: /learn/api-definitions/openapi/extensions/server-names-and-url-templating
  - source: /learn/api-definitions/openapi/overlay-customizations
    destination: /learn/api-definitions/openapi/overrides
  - source: /learn/api-definitions/openapi/automatic-updates
    destination: /learn/api-definitions/openapi/sync-your-open-api-specification
  - source: /learn/api-definitions/openapi/openapi.yml
    destination: /learn/api-definitions/openapi/overview
  - source: /learn/openapi-definition/extensions/webhooks
    destination: /learn/api-definitions/openapi/endpoints/webhooks
  - source: /learn/openapi-definition/empty-page
    destination: /learn/api-definitions/openapi/overview
  - source: /learn/openapi-definition/:slug*
    destination: /learn/api-definitions/openapi/:slug*
  - source: /learn/overview/define-your-api/openapi/extensions
    destination: /learn/api-definitions/openapi/extensions/overview

  # AsyncAPI
  - source: /learn/api-definitions/asyncapi/overlay-customizations
    destination: /learn/api-definitions/asyncapi/overrides
  - source: /learn/api-definitions/asyncapi/extensions/others
    destination: /learn/api-definitions/asyncapi/extensions/overview
  - source: /learn/api-definitions/asyncapi/extensions/server-name
    destination: /learn/api-definitions/asyncapi/extensions/server-names
  - source: /learn/api-definitions/asyncapi/extensions/method-names
    destination: /learn/api-definitions/asyncapi/overview
  - source: /learn/api-definitions/asyncapi/extensions/pagination
    destination: /learn/api-definitions/asyncapi/extensions/overview
  - source: /learn/api-definitions/asyncapi/extensions/streaming
    destination: /learn/api-definitions/asyncapi/extensions/overview
  - source: /learn/api-definitions/asyncapi/extensions/streaming-operations
    destination: /learn/api-definitions/asyncapi/extensions/overview
  - source: /learn/api-definitions/asyncapi/extensions/retry
    destination: /learn/api-definitions/asyncapi/extensions/overview
  - source: /learn/api-definitions/asyncapi/extensions/retry-behavior
    destination: /learn/api-definitions/asyncapi/extensions/overview
  - source: /learn/api-definitions/asyncapi/extensions/error-handling
    destination: /learn/api-definitions/asyncapi/extensions/overview
  - source: /learn/api-definitions/asyncapi/extensions/parameter-names
    destination: /learn/api-definitions/asyncapi/extensions/overview
  - source: /learn/asyncapi-definition/empty-page
    destination: /learn/api-definitions/asyncapi/overview
  - source: /learn/asyncapi-definition/:slug*
    destination: /learn/api-definitions/asyncapi/:slug*

  # OpenRPC
  - source: /learn/api-definitions/openrpc/overlay-customizations
    destination: /learn/api-definitions/openrpc/overrides
  - source: /learn/api-definitions/openrpc/extensions/others
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/sdk-group-name
    destination: /learn/api-definitions/openrpc/extensions/sdk-group-names
  - source: /learn/api-definitions/openrpc/extensions/examples
    destination: /learn/api-definitions/openrpc/extensions/request-response-examples
  - source: /learn/api-definitions/openrpc/extensions/retry
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/pagination
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/streaming
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/streaming-operations
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/retry-behavior
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/timeout
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/timeout-settings
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/error-handling
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/base-path
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/extensions/parameter-names
    destination: /learn/api-definitions/openrpc/extensions/overview
  - source: /learn/api-definitions/openrpc/methods/batch
    destination: /learn/api-definitions/openrpc/methods/rpc-methods
  - source: /learn/api-definitions/openrpc/methods/notifications
    destination: /learn/api-definitions/openrpc/methods/rpc-methods
  - source: /learn/openrpc-definition/empty-page
    destination: /learn/api-definitions/openrpc/overview
  - source: /learn/openrpc-definition/:slug*
    destination: /learn/api-definitions/openrpc/:slug*

  # gRPC (specifics before catchall — was shadowed)
  - source: /learn/api-definitions/grpc/extensions/server-name
    destination: /learn/api-definitions/grpc/servers
  - source: /learn/api-definitions/grpc/extensions/timeout
    destination: /learn/api-definitions/grpc/overview
  - source: /learn/api-definitions/grpc/extensions/:slug*
    destination: /learn/api-definitions/grpc/overrides
  - source: /learn/api-definitions/grpc/overlay-customizations
    destination: /learn/api-definitions/grpc/overrides
  - source: /learn/grpc-definition/empty-page
    destination: /learn/api-definitions/grpc/overview
  - source: /learn/grpc-definition/:slug*
    destination: /learn/api-definitions/grpc/:slug*

  # FernDef (specifics before catchall — comparison-with-open-api was shadowed)
  - source: /learn/api-definition/fern/comparison-with-open-api
    destination: /learn/api-definitions/ferndef/overview
  - source: /learn/api-definition/fern/endpoints
    destination: /learn/api-definitions/ferndef/endpoints
  - source: /learn/api-definition/fern/endpoints/:slug*
    destination: /learn/api-definitions/ferndef/endpoints/:slug*
  - source: /learn/api-definition/fern/api-yml
    destination: /learn/api-definitions/ferndef/api-yml
  - source: /learn/api-definition/fern/api-yml/:slug*
    destination: /learn/api-definitions/ferndef/api-yml/:slug*
  - source: /learn/api-definition/fern/:slug*
    destination: /learn/api-definitions/ferndef/:slug*
  - source: /learn/api-definitions/ferndef/web-sockets
    destination: /learn/api-definitions/ferndef/websockets
  - source: /learn/fern-definition/empty-page
    destination: /learn/api-definitions/ferndef/overview
  - source: /learn/fern-definition/:slug*
    destination: /learn/api-definitions/ferndef/:slug*

  # Shared overrides
  - source: /learn/api-definitions/overview/overrides
    destination: /learn/api-definitions/asyncapi/overrides
  - source: /learn/api-definitions/overrides
    destination: /learn/api-definitions/asyncapi/overrides

  # ============================================================================
  # CLI & API REFERENCE
  # ============================================================================

  # /learn/cli-api/* (specifics before catchall — some were shadowed)
  - source: /learn/cli-api/cli-reference
    destination: /learn/cli-api-reference/cli-reference/overview
  - source: /learn/cli-api/api-reference/:slug*
    destination: /learn/cli-api-reference/cli-reference/overview
  - source: /learn/cli-api/cli-reference/get-started-with-fern-cli
    destination: /learn/cli-api-reference/cli-reference/overview
  - source: /learn/cli-api/cli-reference/cli-overview
    destination: /learn/cli-api-reference/cli-reference/overview
  - source: /learn/cli-api/cli-reference/global-options
    destination: /learn/cli-api-reference/cli-reference/options
  - source: /learn/cli-api/cli-reference/:slug*
    destination: /learn/cli-api-reference/cli-reference/:slug*
  - source: /learn/cli-api/cli/:slug*
    destination: /learn/cli-api-reference/cli-reference/:slug*
  - source: /learn/cli-api/:slug*
    destination: /learn/cli-api-reference/cli-reference/:slug*
  - source: /learn/api/api-reference/:slug*
    destination: /learn/cli-api-reference/cli-reference/overview

  # /learn/cli-reference/* (legacy)
  - source: /learn/cli-reference/cli-overview
    destination: /learn/cli-api-reference/cli-reference/overview
  - source: /learn/cli-reference/overview
    destination: /learn/cli-api-reference/cli-reference/overview
  - source: /learn/cli-reference/get-started
    destination: /learn/cli-api-reference/cli-reference/overview
  - source: /learn/cli-reference/commands
    destination: /learn/cli-api-reference/cli-reference/commands
  - source: /learn/cli-reference/options
    destination: /learn/cli-api-reference/cli-reference/options
  - source: /learn/cli-reference/changelog/:slug*
    destination: /learn/cli-api-reference/cli-reference/changelog/:slug*

  # Fern Public API → CLI Reference
  - source: /learn/api-reference/:slug*
    destination: /learn/cli-api-reference/cli-reference/overview
  - source: /learn/cli-api-reference/api-reference/:slug*
    destination: /learn/cli-api-reference/cli-reference/overview

  # ============================================================================
  # ASK FERN (AI SEARCH)
  # ============================================================================

  # /learn/ask-fern/api-reference (specifics before catchall — were shadowed)
  - source: /learn/ask-fern/api-reference/conversations/get-conversation
    destination: /learn/docs/ai-features/ask-fern/api-reference/overview
  - source: /learn/ask-fern/api-reference/queries/:slug*
    destination: /learn/docs/ai-features/ask-fern/api-reference/overview
  - source: /learn/ask-fern/api-reference/overview
    destination: /learn/docs/ai-features/ask-fern/api-reference/overview
  - source: /learn/ask-fern/api-reference/:slug*
    destination: /learn/docs/ai-features/ask-fern/api-reference/:slug*

  # /learn/ask-fern/features (specifics before catchall — custom-fa-qs was shadowed)
  - source: /learn/ask-fern/features/custom-fa-qs
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/features/analytics
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/features/citations
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/features/insights
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/features/evaluation
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/features/rbac
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/features/slack-app
    destination: /learn/docs/ai-features/ask-fern/slack-app
  - source: /learn/ask-fern/features/scribe-slack-app
    destination: /learn/docs/ai-features/fern-writer

  # /learn/ask-fern/* other specifics
  - source: /learn/ask-fern/getting-started/what-is-ask-fern
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/getting-started/how-it-works
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/configuration/setup
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/configuration/guidance
    destination: /learn/docs/ai-features/ask-fern/guidance
  - source: /learn/ask-fern/configuration/content-sources
    destination: /learn/docs/ai-features/ask-fern/content-sources
  - source: /learn/ask-fern/configuration/documents
    destination: /learn/docs/ai-features/ask-fern/content-sources
  - source: /learn/ask-fern/configuration/locations-and-datasources
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/configuration/custom-prompts
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/overview
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/citations
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/custom-prompting
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ask-fern/customer-showcase
    destination: https://buildwithfern.com/customers
  - source: /learn/ask-fern/:slug*
    destination: /learn/docs/ai-features/ask-fern/:slug*

  # Ask Fern new-location cleanup (/learn/docs/ai-features/ask-fern/*)
  - source: /learn/docs/ai-features/ask-fern/how-it-works
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/docs/ai-features/ask-fern/features
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/docs/ai-features/ask-fern/setup
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/docs/ai-features/ask-fern/discord-bot
    destination: /learn/docs/ai-features/ask-fern/overview

  # /learn/ai-search/* (legacy) — specifics before catchall
  - source: /learn/ai-search/getting-started/ai-search-customer-showcase
    destination: https://buildwithfern.com/showcase#ask-fern-customers
  - source: /learn/ai-search/customer-showcase
    destination: https://buildwithfern.com/customers
  - source: /learn/ai-search/overview
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ai-search/custom-prompting
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ai-search/citations
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ai-search/features/:slug*
    destination: /learn/docs/ai-features/ask-fern/overview
  - source: /learn/ai-search/getting-started/:slug*
    destination: /learn/docs/ai-features/ask-fern/:slug*
  - source: /learn/ai-search/:slug*
    destination: /learn/docs/ai-features/ask-fern/:slug*

  # ============================================================================
  # MISC LEGACY
  # ============================================================================
  - source: /learn/user-feedback
    destination: /learn/docs/user-feedback
  - source: /learn/snippets/:slug*
    destination: /learn/cli-api-reference/cli-reference/overview
  - source: /learn/v2/:slug*
    destination: /learn/:slug*