Site-level settings
Site-level settings
Customize colors, typography, logo, layout, navbar links, and analytics in docs.yml
Site-level settings
Customize colors, typography, logo, layout, navbar links, and analytics in docs.yml
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 for advanced use cases.
To enable intelligent YAML validation and autocompletion in your editor, add this line at the top of your docs.yml file:
This enables real-time schema validation and autocompletion based on Fern’s complete schema.
Every Fern documentation website requires a docs.yml file that contains the core configuration settings. Here are the essential top-level properties you can configure:
A string that’s used as the tab bar title.
Set a custom logo for your site. Learn more about the logo configuration.
Relative filepath to the favicon. The path is relative to the YAML file where it is set (e.g., docs.yml).
Configure the primaryAccent and background colors. Learn more about the colors configuration.
An array of paths you want to configure to permanently redirect to another path. Learn more about the
redirects configuration.
Array of names and urls of links you want to include as a call to action. Learn more about the
navbar-links configuration.
Set a custom background image to be displayed behind every page. Learn more about the
background-image configuration.
Customize the fonts used in your documentation website. Learn more about the typography configuration.
Customize the layout of your documentation website. Learn more about the
layout configuration.
Customize the settings of your documentation website. Learn more about the
settings configuration.
Creates a landing page for your documentation website. Learn more about the
landing-page configuration.
Sets the default language displayed by code snippets in the API Reference.
Options include: typescript, python, java, go, ruby, csharp, php, swift, curl
Configure SEO metadata for your documentation website. Learn more about the
metadata configuration.
The name of a global theme to apply to this site. The CLI fetches the named theme from Fern’s registry at publish time and merges its branding fields (logo, colors, fonts, layout, CSS, JS, and more) into the local docs.yml. Use this to share a consistent visual identity across multiple documentation sites.
Path to a custom React component file (TSX or JSX) to replace Fern’s default header. The component must have a default export. Learn more about custom header and footer components.
Path to a custom React component file (TSX or JSX) to replace Fern’s default footer. The component must have a default export. Learn more about custom header and footer components.
An instance is the backend of a distinct docs website. Each instance is published to a unique domain using the --instance flag. It’s most common to use instances to configure staging and production docs which publish to separate URLs.
Configure one or more documentation websites.
The URL where your Fern documentation is deployed. Must contain the suffix docs.buildwithfern.com.
The custom domain where your documentation is hosted. Learn more about setting up a custom domain.
If specified, adds an “Edit this page” link to the bottom of each page that links to the given public GitHub repository. You can optionally set a launch target to control where the link directs users. Learn more about the edit-this-page configuration.
Specify which audiences this instance serves (e.g., internal developers, beta testers, public customers).
You can use audiences to control which versions and products appear in each documentation instance, enabling you to create separate sites for different user groups. Content is included when its audience tag matches the instance audience. Content without an audience tag is included by default. Learn more about configuring instance audiences for products and/or versions.
When true, the CLI uses basepath-aware publishing so multiple independent repositories can publish to the same custom domain with different basepaths. The url and custom-domain must share the same basepath when this is enabled. Learn more about multi-source docs.
Configure your documentation’s color palette for both light and dark modes. Only accent-primary is required — all other colors have sensible defaults. These colors are also automatically available as CSS custom properties in your custom stylesheets.
The primary brand color used for interactive elements like links, buttons, and highlighted text. Configure separate colors for light and dark modes to ensure proper contrast and visibility.
The main background color for all documentation pages. Choose colors that provide good contrast with text and complement your brand colors. Dark mode colors should reduce eye strain.
Used for dividing lines, borders around elements, and visual separators. Choose subtle colors that create clear boundaries without being too prominent.
Background color for the navigation sidebar. When specified, includes a 1px border on the right side. If omitted, the sidebar uses a transparent background without a border.
Background color for the top navigation header. When specified, includes a 1px solid border on the bottom. If omitted, the header uses a transparent background with a subtle gradient border.
Background color for cards, code blocks, and other contained elements. Should be slightly different from the main background to create visual hierarchy while maintaining readability.
Configure your site logo with separate images for light and dark modes, a clickable link, and optional display text.
The URL that users will be directed to when clicking the logo. Typically your company’s homepage or app.
Path to your dark mode logo file, relative to the YAML file where it is set (e.g., docs.yml). SVG format is recommended for optimal quality. Example: assets/images/logo-dark.svg
Path to your light mode logo file, relative to the YAML file where it is set (e.g., docs.yml). SVG format is recommended for optimal quality. Example: assets/images/logo-light.svg
Text to display to the right of the logo image. This is useful for adding a label like “Docs” or “API” next to your logo.
Custom height for the logo in pixels. Use this to adjust the logo size if the default height doesn’t fit your design.
Redirect traffic from one path to another, either as exact paths or regex patterns. The Configure redirects guide covers examples and ordering rules in depth.
The relative path you want to redirect from (e.g., /old-path). Must be a relative path, not an absolute URL. Must not include search parameters (e.g., ?key=value).
The path you want to route to. Can be an internal path (/new-path) or an external URL (https://example.com). External URLs must include the full address, including https.
By default, uses the 308 status code to instructs clients and search engines to cache the redirect forever. Set to false only if you need a temporary redirect using the 307 status code, which won’t be cached.
Add navigation links and buttons to the top navigation bar of your documentation site.
One of outlined, minimal, filled, github, or dropdown. This value controls the styling of the button.
The URL once you click on the button. Example: https://buildwithfern.com/book-demo
The URL to a GitHub repository. Similar to href, but specifically for GitHub repository links. This field is used when type is set to github. Example: https://github.com/example-company/fern
Text inside the button.
When true, the border radius of the button will be fully rounded.
The icon to be used in the button. This icon will appear to the left of the text content.
Icons can be in three formats:
fa-solid fa-rocket. Pro and Brand Icons from Font Awesome are supported../assets/icons/my-icon.svg or ../assets/icons/my-icon.png). Paths are relative to the YAML file where the icon is referenced (e.g., docs.yml). For example, if you set an icon in fern/products/my-product.yml, the path ./assets/icon.svg resolves to fern/products/assets/icon.svg. If you set it in fern/docs.yml, the same path resolves to fern/assets/icon.svg."<svg>...</svg>").The icon to be used in the button. This icon will appear to the right of the text content.
Icons can be in three formats:
fa-solid fa-rocket. Pro and Brand Icons from Font Awesome are supported../assets/icons/my-icon.svg or ../assets/icons/my-icon.png). Paths are relative to the YAML file where the icon is referenced (e.g., docs.yml). For example, if you set an icon in fern/products/my-product.yml, the path ./assets/icon.svg resolves to fern/products/assets/icon.svg. If you set it in fern/docs.yml, the same path resolves to fern/assets/icon.svg."<svg>...</svg>").By default, the rightIcon for a filled button is set to arrow-right.
Specifies where to open the linked URL. For typical documentation sites, links can open in the same tab (_self) or new tab (_blank). For documentation embedded in a dashboard or iframe, links can open in the parent frame (_parent) or topmost frame (_top).
Items to display in the dropdown menu when type is set to dropdown.
The text to display for the link.
The URL the link points to.
Font Awesome icon that displays to the left of the text.
Font Awesome icon that displays to the right of the text
When true, the link will have fully rounded borders.
Specifies where to open the linked URL.
Add clickable social media and community links to your documentation site footer to improve discoverability and engagement.
Footer links provide visual navigation to your social channels. To configure SEO metadata and social media tags at the page or site level, see metadata configuration.
URL to your GitHub repository or organization.
URL to your Slack community or workspace.
URL to your X (formerly Twitter) profile.
URL to your Twitter profile. Use footer-links.x for the new X branding.
URL to your LinkedIn company page or profile.
URL to your YouTube channel.
URL to your Instagram profile.
URL to your Facebook page.
URL to your Discord server invite.
URL to your Hacker News profile.
URL to your Medium publication or profile.
URL to your main website or homepage.
Set a custom background image to display behind every page of your documentation site.
Relative filepath to the light-mode background image. The path is relative to the YAML file where it is set (e.g., docs.yml).
Relative filepath to the dark-mode background image. The path is relative to the YAML file where it is set (e.g., docs.yml).
Customize the fonts used for body text, headings, and code blocks across your documentation site.
The font used for all body text including paragraphs, lists, and general content. For optimal performance, use WOFF2 format.
The font used for headings, titles, and other prominent text elements. Can be the same as your body font if you prefer a unified look. Supports multiple weights for different heading levels.
The font used for code blocks and inline code. Monospace fonts are recommended for better code readability. Popular choices include JetBrains Mono, Fira Code, and Source Code Pro.
The name of the font. Defaults to a generated name that will be used to reference your custom font in the eventually injected CSS.
The path to your font file, relative to the YAML file where it is set (e.g., docs.yml). Use this when you have a single font file. For multiple font files (like separate files for bold, italic etc), use paths instead.
The weight of the font. Can be a number (400, 700) or a range for variable fonts (400 700). Common values: 400 (normal), 700 (bold).
The font style, either “normal” or “italic”. Defaults to “normal” if not specified.
A list of font files for particular weights. Each element in the list includes a path, weight, and style property.
Control the dimensions and placement of structural elements like the header, sidebar, content area, and search bar.
Sets the height of the header. Defaults to 4rem (64px). Valid options are {number}rem or {number}px.
Sets the maximum width of the docs layout, including the sidebar and content. Defaults to 88rem (1408px).
Valid options are {number}rem, {number}px, or full.
Sets the maximum width of the Markdown article content. Defaults to 44rem (704px).
Valid options are {number}rem or {number}px.
Sets the width of the sidebar in desktop mode. Defaults to 18rem (288px). Valid options are {number}rem or {number}px.
Sets the placement of the searchbar. Can be one of header, sidebar or header-tabs (places the searchbar in the header but on the tabs row).
disable-header is set to true.Set the placement of the tabs. Can be one of header or sidebar.
disable-header is set to true.Set the placement of the product and version switchers. Can be one of header or sidebar.
disable-header is set to true.Set the alignment of the Markdown content. Can be one of center or left.
Defaults to center.
If set to true, the header won’t be rendered. Instead, the logo will be rendered as part of the sidebar, and a 1px border will separate the sidebar from the content.
If set to true, the navigation links (previous, next) at the bottom of the page won’t be rendered. This can be overridden on a per-page basis using the frontmatter.
If set to true, the feedback form won’t be rendered. This can be overridden on a per-page basis using the frontmatter.
If set to true, a sticky table of contents bar is shown below the header on mobile and tablet viewports (under the xl breakpoint). The bar displays a scroll progress indicator and the current heading, and expands to the full table of contents when tapped.
Only applies to pages using the guide and overview layouts. The bar is hidden when a page has fewer than two headings or when hide-toc: true is set in the page frontmatter.
Customize the visual style of specific UI elements across your documentation site.
Sets the visual style of the navigation sidebar. default shows the full sidebar with section headers and icons; minimal displays a cleaner, simplified sidebar without decorative elements.
Sets the visual style of the main content body. default uses a flat background; canvas adds a subtle card-like container around the content area.
Configures the navigation tabs. Accepts a string (default or bubble) for style-only configuration, or an object with style, alignment, and placement properties for full control.
When set to a string, default uses underlined tabs and bubble displays tabs with rounded pill-shaped backgrounds.
Sets the visual style of the navigation tabs. default uses underlined tabs; bubble displays tabs with rounded pill-shaped backgrounds.
Sets the horizontal alignment of the tabs when placement is header. left aligns tabs to the left; center horizontally centers them. When placement is sidebar, alignment has no effect.
Sets the placement of the tabs. header displays tabs in the top navigation header; sidebar displays them in the left sidebar.
Takes precedence over layout.tabs-placement when both are set. This setting is ignored when layout.disable-header is set to true.
Sets the visual style of the page action buttons. default shows individual icon buttons; toolbar groups actions into a compact horizontal toolbar.
Sets the visual style of the footer navigation links. default shows full previous/next cards with titles and descriptions; minimal displays simple text links.
Sets the visual style of the product switcher. default displays a dropdown selector; toggle displays a horizontal toggle bar.
Configure site-wide behavior such as search, code display, 404 handling, and environment variable substitution.
The text to display in the searchbar.
If set to true, the searchbar will be disabled. Use this if you want to use a custom search solution.
If set to true, the API Explorer will bypass the proxy when sending requests directly to your API.
When this feature is enabled, your API must have Cross-Origin Resource Sharing (CORS) enabled to allow requests from the documentation domain.
If set to true, the code blocks will be displayed in dark mode, regardless of the selected theme.
Legacy alias for settings.search.default-filter-by-current-product. If either is true, default filtering is enabled.
Use settings.search instead for finer control over how search is scoped to the current product or version.
Controls how search results are scoped to the current product or version for sites with multiple products or versions.
Boosts results from the current product and version higher in the ranking without hiding results from other products.
Auto-selects the current product as a facet filter so only current-product results are shown by default. Users can remove the filter to broaden their search.
Controls the display of HTTP snippets in the API Reference. HTTP snippets are enabled by default for all languages.
false to disable HTTP snippets completelyIf set to true, when a user navigates to a page that doesn’t exist, they will be redirected to the home page.
By default, a 404 page will be displayed.
If set to true, the TypeScript snippets will be displayed as JavaScript snippets in the API Reference.
If set to true, all analytics integrations configured in the analytics configuration will be disabled. This includes Google Analytics 4, Google Tag Manager, PostHog, and any other analytics providers you have configured.
Sets the default method for deriving page and section titles across all folder navigations. By default (filename), titles are derived from file names. Set to frontmatter to use the title field from each file’s frontmatter instead (falls back to filename if not set). Individual folders can override this global default using the per-folder title-source setting.
If set to true, replaces ${ENV_VAR} expressions with environment variable values at build time. Useful for injecting API keys, base URLs, or version numbers into your docs.
Substitution works in Markdown/MDX files and API specifications (OpenAPI). JavaScript files are excluded to avoid conflicts with template literals.
To output a literal ${VAR}, escape it as \$\{VAR\}.
During local preview (fern docs dev), undefined variables resolve to empty strings. During publishing, undefined variables cause the build to fail.
Configure the page action buttons that appear throughout your documentation. By default, Copy Page (copy-page), View as Markdown (view-as-markdown), Ask AI (ask-ai), ChatGPT (chatgpt), Claude (claude), Claude Code (claude-code), and Cursor (cursor) are enabled.
To hide page actions on an individual page, use the hide-page-actions frontmatter property.
The default page action to display. Options: copy-page, view-as-markdown, ask-ai, chatgpt, claude, claude-code, cursor, vscode.
When enabled, displays a button that allows users to copy the entire page content to their clipboard for easy sharing or reference. To control what content appears in the copied output, use <llms-ignore> tags.
When enabled, displays a button that allows users to view the raw Markdown source of the current page. Users can also view Markdown by appending .md to the page URL. To control what content appears in the Markdown output, use <llms-ignore> tags.
When enabled, displays an “Ask AI” button that allows users to ask questions about the page content using AI-powered assistance.
Controls the “Open in ChatGPT” button, which sends the page content to ChatGPT for further exploration and Q&A. Set to false to hide it.
Controls the “Open in Claude” button, which sends the page content to Claude for further exploration and Q&A. Set to false to hide it.
Controls the “Connect to Claude Code” button, which copies a claude mcp add command to the clipboard so users can register the docs site’s MCP server with Claude Code. Displays by default when Ask Fern is enabled. Set to false to hide it.
Controls the “Connect to Cursor” button, which installs the docs site’s MCP server in Cursor via a deeplink. Displays by default when Ask Fern is enabled. Set to false to hide it.
When enabled, displays an “Open in VS Code” button that allows users to open the page content in Visual Studio Code for editing and development. Requires Ask Fern to be enabled.
Define custom page action buttons with your own titles, icons, and URLs. Custom actions appear alongside the built-in page actions and can link to external tools, editors, or any URL.
An array of custom page action configurations. Each custom action appears as a button in the page actions menu.
The title displayed for the custom action button.
Optional helper text displayed below the title in the action menu.
The URL to navigate to when the action is clicked. Supports the following placeholders:
{slug}: The current page’s slug (e.g., getting-started/quickstart){domain}: The current domain (e.g., docs.example.com){url}: The full URL of the current page (e.g., https://docs.example.com/getting-started/quickstart)Icon to display for the custom action.
Icons can be in three formats:
fa-solid fa-rocket. Pro and Brand Icons from Font Awesome are supported../assets/icons/my-icon.svg or ../assets/icons/my-icon.png). Paths are relative to the YAML file where the icon is referenced (e.g., docs.yml). For example, if you set an icon in fern/products/my-product.yml, the path ./assets/icon.svg resolves to fern/products/assets/icon.svg. If you set it in fern/docs.yml, the same path resolves to fern/assets/icon.svg."<svg>...</svg>").When set to true, this custom action becomes the default action displayed prominently in the page actions area.
If you set default: true on a custom action, don’t also set page-actions.default to avoid conflicts.
Add an “Edit this page” link to the bottom of each documentation page, making it easy for readers to suggest changes. Configure it per instance in your docs.yml file.
When using launch: github, the GitHub repository must be public for the “Edit this page” link to work correctly. With launch: dashboard, users with editor access can edit via Fern Editor regardless of repository visibility.
The GitHub organization that owns the documentation repository.
The name of the GitHub repository containing your fern folder.
The branch of the repository you would like the GitHub editor to open a PR to. Default is main.
Controls the behavior of the “Edit this page” button. When set to dashboard, clicking the button opens a screen where users can choose between starting a Fern Editor session for that page or going straight to the source in GitHub (best for internal sites). Defaults to github, which links directly to the file on GitHub (best for public-facing sites).
Set a dedicated landing page that serves as the entry point to your documentation site.
The name of the landing page.
Relative filepath to the desired landing page Markdown file. The path is relative to the YAML file where it is set (e.g., docs.yml).
The slug of the landing page. Defaults to the page name.
The slug can also be overridden in the frontmatter of the landing page Markdown file.
Configure site-wide Open Graph and Twitter Card metadata to control how your documentation appears in social media previews and search results.
The name of your website for Open Graph tags.
The title shown in social media previews.
The description shown in social media previews.
The canonical URL of your documentation.
The image shown in social media previews. Recommended size is 1200x630 pixels.
The width of your Open Graph image in pixels.
The height of your Open Graph image in pixels.
The locale of your content (e.g., “en_US”).
URL to your company logo.
The title shown in Twitter Card previews.
The description shown in Twitter Card previews.
Your company’s Twitter handle.
The image shown in Twitter Card previews.
The Twitter handle for your website.
The Twitter Card type. Options are summary, summary_large_image, app, or player.
When true, enables dynamic OG image generation for pages that don’t have a custom og:image set.
A custom background image for dynamically generated OG images. Can be a URL or a relative file path. Relative paths are resolved from the YAML file where this property is set (e.g., docs.yml).
The host of your documentation website. This will be used to set the canonical URL for metadata tags and documents like the sitemap.
Defaults to the URL defined in the instances configuration.
Integrate third-party analytics providers to track usage across your documentation site.
Your Google Analytics 4 measurement ID. Must start with “G-”.
Your Google Tag Manager container ID. Must start with “GTM-”.
Configuration for PostHog Analytics integration.
Your PostHog project API key. Defaults to the api-host of “https://us.i.posthog.com”.
Configure third-party integrations that require hosting verification files on your docs site.
Relative path to a Context7 verification file. When set, Fern hosts the file at /context7.json on your docs site. Learn more about the Context7 integration.
Specify Ask Fern to control where it appears and what content it can access.
Additional content sources that Ask Fern should index and search. For more details, see Additional content sources.
The URL of the website to index. Ask Fern will crawl and index the content from this URL.
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.
By default, Ask Fern uses system prompts to finetune AI search results. Add a custom prompt to override it.
See Anthropic’s prompting guide for ideas and examples.
Configure directives and custom files for AI agent consumption. By default, Fern auto-generates llms.txt and llms-full.txt and prepends a directive to every page served to AI agents. Use the agents key to customize this behavior:
Text prepended to each page’s Markdown output when served to AI agents. The directive is injected after the frontmatter metadata section but before the page body. Human-facing documentation is unaffected. When not set, a default directive is used that points agents to your site’s .md URLs, llms.txt, and llms-full.txt. Set to an empty string to disable the directive entirely.
Controls which frontmatter field is preferred for one-line page descriptions in llms.txt. Defaults to description. If the preferred field isn’t present in a page’s frontmatter, Fern falls back to other fields (description, subtitle, og:description, headline, excerpt).
Path to a custom llms.txt file, relative to docs.yml. When set, this file is served at the root-level /llms.txt endpoint instead of the auto-generated version. Nested paths continue to use the auto-generated output.
Path to a custom llms-full.txt file, relative to docs.yml. When set, this file is served at the root-level /llms-full.txt endpoint instead of the auto-generated version. Nested paths continue to use the auto-generated output.
Path to a custom robots.txt file, relative to docs.yml. When set, this file is served verbatim at /robots.txt. See Custom robots.txt for details.
Configure AI-generated examples for your API Reference pages.
Controls AI-generated examples for API Reference pages. When enabled, realistic example values are generated instead of placeholder values like "string". Manual examples in x-fern-examples or OpenAPI example properties always take priority. Set to false to disable AI examples entirely.
Instructions to guide the content and style of AI-generated examples in your API Reference. Use this to align examples with your brand or domain. Limited to 500 characters.
Configure the severity of validation rules run by fern check. Each rule can be set to "warn" (non-blocking) or "error" (blocking).
Severity for broken link detection. Defaults to error for broken internal links and warn for malformed URLs. Replaces the deprecated --broken-links and --strict-broken-links CLI flags.
Severity for OpenAPI example validation.
Severity for non-component OpenAPI reference validation. Flags $ref values that point outside the #/components section of an OpenAPI spec.
Severity for local OpenAPI reference validation. Checks that local $ref values resolve to existing definitions.
Severity for circular redirect validation. Detects redirect chains that loop back to a previously visited path.
Severity for docs endpoint URL validation. Checks that endpoint URLs referenced in docs.yml are well-formed.
Severity for missing redirect detection. Compares the current docs navigation against the previously published state and flags pages that were removed or moved to a new URL without a corresponding redirect in docs.yml. Requires authentication (fern login or the FERN_TOKEN environment variable). The check is skipped on first publish, when unauthenticated, or when the network is unavailable.
Configure experimental features in the experimental section of your docs.yml.
Controls dynamic SDK snippets that allow users to modify parameters and see code examples update in real time. Dynamic snippets are enabled by default and supported across all languages. Follow the SDK snippets setup instructions to configure. Set to false to use static SDK snippets instead.