# Fern Docs Overview > Learn about key features of Fern's Docs Fern Docs provides versatile documentation to support all your content needs, including popular formats like: * **Landing Pages** - High-level introductions with navigation for different audiences * **Guides** - Step-by-step tutorials, user guides, and recipes/cookbooks * **API References** - Auto-generated docs with request/response examples and auto-updating SDK snippets * **Changelogs** - Release notes for new features and fixes ## Key Features Match your docs to your brand with customizable colors, fonts, and styles. Auto-generate API docs from OpenAPI and AsyncAPI specs. Version and manage docs with your Git provider using Markdown or MDX. Test APIs directly in the docs with auto-populated credentials. Example code auto-updates as your SDKs evolve. Use pre-built or custom React components for a polished look. # Docs Customer Showcase Fern Docs is a tool for creating beautiful, customizable developer documentation. Achieve best-in-class docs with a modern and branded look and feel, powered by MDX and your API specification, and integrated seamlessly with CI/CD. Below are some companies building with Fern to elevate their developer experience.

*** ##

Webflow

Auto-populated API key Webflow uses Fern's API Explorer to auto-populate API keys using their custom authentication flow, making it easy for developers to authenticate once and then focus on developing. Check out Webflow's API Explorer here: View the Webflow API Explorer *** ##

Cohere

SSE Landing page

Cohere uses Fern's out-of-the-box components to create a landing page that orients users and aids in developer experience. Their API Explorer further aids in that developer experience, allowing users to test out endpoints in their API, including server-sent events. Check out Cohere's documentation here: View Cohere's landing page View the Cohere API Reference *** ##

Cartesia

WebSockets Custom styling

Cartesia leverages Fern's custom styling capabilities to create modern and branded documentation. They pair these aesthetics with an API Explorer that supports WebSockets, allowing developers to test their Text-To-Speech streaming in real-time. Check out Cartesia's documentation here: View Cartesia's documentation overview View the Cartesia API Reference *** ##

Vellum

SDK documentation Vellum takes advantage of Fern's adaptable layout and styling capabilities to create custom documentation for their UI SDK, in addition to using Fern's auto-generated API reference for their client libraries (which are generated by Fern, as well). Check out their references here: View Vellum's SDK documentation View Vellum's API reference ***

Ready to build best-in-class documentation? [Get started with Fern today](https://buildwithfern.com/learn/docs/getting-started/quickstart). # Quickstart > Start building beautiful documentation in under 5 minutes Docs cascade

With Fern, you can build beautiful developer documentation that matches your brand. Fern supports writing pages (written in Markdown) and generating API Reference documentation (from an OpenAPI Specification). In this guide, we'll show you how to get started with Fern in under 5 minutes. ### Initialize your `fern` folder All the configurations for your docs live in the `fern` folder. Inside, you'll find a `docs.yml` file that contains all the settings for your documentation. Get started by cloning the [starter template](https://github.com/fern-api/docs-starter). ```bash title="SSH" git clone git@github.com:fern-api/docs-starter.git ``` ```bash title="HTTPS" git clone https://github.com/fern-api/docs-starter.git ``` Next, please update the template settings to use your organization. Please edit the details `fern.config.json` and `docs.yml` with your organization name. ```json {2} { "organization": "{{YOUR_ORGANIZATION}}", "version": "0.x.x" } ``` ```yml {2} instances: - url: {{YOUR_ORGANIZATION}}.docs.buildwithfern.com ``` Finally, run `fern generate --docs` to generate your documentation. If you prefer, you can use our CLI to create a new project. Install the CLI by running ```bash npm install -g fern-api ``` Then run ```bash fern init --docs ``` You will see a new `fern` folder in your project with the following structure: ```bash fern ├─ docs.yml └─ fern.config.json ``` Finally, run `fern generate --docs` to generate your documentation. ### Update your docs We provide a white-glove migration service as part of our Enterprise plan. Interested? Request it [here](https://buildwithfern.com/contact). Add content with MDX files. ```markdown --- title: "Page Title" description: "Subtitle (optional)" --- Hello world! ``` Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required. In order for the Markdown page to show up, you'll need to reference them from your `docs.yml` file. You can reference the Markdown page within a section or as a standalone page. ```yml navigation: - page: "Hello World" path: "pages/hello-world.mdx" - section: Overview content: - page: QuickStart path: pages/hello-world.mdx ``` Add an API Reference by adding an OpenAPI Specification to your project. ```bash fern init --openapi /path/to/openapi.yml ``` This will create an `openapi.yml` file in your project. You can reference this file in your `docs.yml` file by adding an api block. ```yml navigation: - api: "API Reference" ``` All of the branding for your docs can be configured in the `docs.yml` file. For example, to set the logos, colors, and fonts for your docs, you can add the following to your `docs.yml` file: ```yml colors: accentPrimary: dark: "#f0c193" light: "#af5f1b" logo: dark: ./docs/assets/logo-dark.svg light: ./docs/assets/logo-light.svg height: 40 href: https://buildwithfern.com/ favicon: ./docs/assets/favicon.png ``` ### Publish to production Fern supports hosting your docs website on a custom domain or on a custom subpath (e.g. [https://domain.com/docs](https://domain.com/docs)). Please reach out to the Fern team at [support@buildwithfern.com](mailto:support@buildwithfern.com) to configure this. Fern supports integrations with a variety of providers such as PostHog, Segment, Intercom, Google Tag Manager, etc. Find out more on this [page](/learn/docs/integrations/overview). Below are some examples of documentation websites that have been published using Fern: } /> } /> } /> } /> } /> } /> } /> } /> # Global Configuration > Customize your documentation using the docs.yml file Not all of the properties in `docs.yml` are documented here. If you'd like to see all properties, please check out the the raw [schema](https://github.com/fern-api/fern/blob/69e74d9c27dc031ec2e84e70b878c40e9e9678a5/packages/cli/configuration/fern/definition/docs.yml#L110-L153) ## Top-level properties Every Fern documentation website needs a `docs.yml` file with the core configuration settings. ```yaml docs.yml title: My Docs logo: href: mydomain.com dark: path/to/logo.png light: path/to/logo.png favicon: path/to/favicon.ico ``` A string that is used as the tab bar title. Learn more about the `logo` configuration [here](/learn/docs/getting-started/global-configuration#logo-configuration). Relative filepath to the favicon. Configure the `primaryAccent` and `background` colors. Learn more about the `colors` configuration [here](/learn/docs/getting-started/global-configuration#colors-configuration). An array of paths you want to configure to permanently redirect to another path. Learn more about the `redirects` configuration [here](/learn/docs/getting-started/global-configuration#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 [here](/learn/docs/getting-started/global-configuration#navbar-links-configuration). Set a custom background image to be displayed behind every page. Learn more about the `background-image` configuration [here](/learn/docs/getting-started/global-configuration#background-image-configuration). Customize the fonts used in your documentation website. Learn more about the `typography` configuration [here](/learn/docs/getting-started/global-configuration#typography-configuration). Customize the layout of your documentation website. Learn more about the `layout` configuration [here](/learn/docs/getting-started/global-configuration#layout-configuration). Creates a landing page for your documentation website. Learn more about the `landing-page` configuration [here](/learn/docs/getting-started/global-configuration#landing-page-configuration). Sets the default language displayed by code snippets in the API Reference. Options include: `typescript`, `python`, `java`, `go`, `ruby`, `csharp`, `curl` ## Instances configuration An `instance` is the backend of a distinct docs website. Each instance is published to a unique domain using the `--instance` flag. It is most common to use instances to configure staging and production docs which publish to separate URLs. ```yaml docs.yml instances: - url: plantstore.docs.buildwithfern.com custom-domain: docs.plantstore.com edit-this-page: github: owner: fern repo: plant-store-docs branch: main ``` 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 [here](/learn/docs/building-your-docs/custom-domain). If `edit-this-page` is set, Fern will add an "Edit this page" link to the bottom of each page that links to the given public GitHub repository. Learn more about the `edit-this-page` object [here](#github-configuration). ## Colors configuration ```yaml docs.yml colors: accent-primary: light: "#418326" dark: "#ADFF8C" background: light: "#ffffff" dark: "#0d0e11" ``` The configured accent primary color for light and dark mode. The configured background colors for light and dark mode. The border color is used for the borders of cards and other elements. If `sidebarBackground` is set, the sidebar will also render a 1px border on the right side. By default, the sidebar will render with a transparent background without a border. If `headerBackground` is set, the header will render with a solid background, with a 1px solid border on the bottom. By default, the header will render with a transparent background, with a 1px faded border on the bottom. The background color of cards and code blocks. ## Logo configuration ```yaml docs.yml logo: href: mydomain.com dark: path/to/logo.png light: path/to/logo.png ``` Where clicking on the logo links you to. Path to the image for the dark mode logo. You can exclude this if you don't have dark mode enabled. SVG format is recommended. Path to the image for the light mode logo. You can exclude this if you don't have light mode enabled. SVG format is recommended. ## Redirects configuration ```yaml docs.yml redirects: - source: "/old-path" destination: "/new-path" - source: "/old-folder/*" destination: "/new-folder/*" ``` The path that you want to redirect from. The path that you want to redirect to. Toggle between **permanent** and **temporary** redirect (default `false`). When true, the status code is 308. When false the status code is 307. ## NavBar links configuration ```yaml docs.yml navbar-links: - type: minimal text: Contact support href: https://example.com/support - type: filled text: Login href: https://example.com/login rounded: false ``` One of `outlined`, `minimal`, or `filled`. This value controls the styling of the button. The url once you click on the button. Example: [https://buildwithfern.com/contact](https://buildwithfern.com/contact) Text inside the button. When `true`, the border radius of the button will be fully rounded. The [Font Awesome icon](https://fontawesome.com/icons) to be used in the button. This icon will appear to the **left** of the text content. Pro and Brand Icons from Font Awesome are supported. The [Font Awesome icon](https://fontawesome.com/icons) to be used in the button. This icon will appear to the **right** of the text content. Pro and Brand Icons from Font Awesome are supported. By default, the `rightIcon` for a `filled` button is set to `arrow-right`. ## Background image configuration ```yaml docs.yml background-image: light: ./path/to/bg-light.svg dark: ./path/to/bg-dark.svg ``` Relative filepath to the light-mode background image. Relative filepath to the dark-mode background image. ## Typography configuration ```yaml docs.yml {2-16} typography: bodyFont: name: Inter-Regular path: ./fonts/Inter-Regular.woff2 headingsFont: name: Inter-Bold paths: - path: ./fonts/Inter-Bold.woff2 weight: "400" style: normal - path: ./fonts/Inter-Bold.woff2 weight: 500 900 # <-- indicates a range of weights style: normal codeFont: name: Roboto-Mono-Regular path: ./fonts/Roboto-Mono-Regular.woff2 ``` Customize page and section titles. If not supplied, defaults to the body font. Learn more about font configuration [here](/learn/docs/getting-started/global-configuration#font-configuration). Customize paragraph text and other body text. Learn more about font configuration [here](/learn/docs/getting-started/global-configuration#font-configuration). Customize code blocks and inline code snippets. Learn more about font configuration [here](/learn/docs/getting-started/global-configuration#font-configuration). ### Font configuration ```yaml title="Basic" {3-4} typography: bodyFont: name: Inter-Regular path: ./fonts/Inter-Regular.woff2 ``` ```yaml title="Variable Font" {3-10} typography: bodyFont: name: Inter-Regular paths: - path: ./fonts/Inter-Bold.woff2 weight: "400" style: normal - path: ./fonts/Inter-Bold.woff2 weight: 500 900 # <-- indicates a range of weights style: normal ``` The name of the font. Defaults to a generated name that will be used to reference your custom font in the eventually injected CSS. Relative filepath to a variable font file. If the font file is not variable, use `paths` instead. Supported font file types are `.woff` and `woff2`. A list of font files for particular weights. Each element in the list includes a `path`, `weight`, and `style` property. ## Layout configuration ```yaml docs.yml layout: header-height: 70px page-width: 1344px content-width: 672px sidebar-width: 336px searchbar-placement: header tabs-placement: header content-alignment: left ``` 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). Defaults to `sidebar`. This setting is ignored when `disable-header` is set to true. Set the placement of the tabs. Can be one of `header` or `sidebar`. Defaults to `sidebar`. This setting is ignored when `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 will not be rendered. Instead, the logo will be rendered as part of the sidebar, and a 1px border will separate the sidebar from the content. ## GitHub configuration ```yaml docs.yml edit-this-page: github: owner: fern repo: plant-store-docs branch: main ``` Be sure the repository is set to **public** visibility. The owner of the GitHub repository where you host your documentation. The name of the GitHub repository where you host your documentation. The branch of the repository you would like the GitHub editor to open a PR to. Default is `main`. ## Landing page configuration ```yaml docs.yml landing-page: page: Page Title path: path/to/landing-page.mdx ``` The name of the landing page. Relative filepath to the desired landing page Markdown file. See [VapiAI's landing page live](https://docs.vapi.ai/welcome) and the associated [Markdown file](https://github.com/VapiAI/docs/blob/main/fern/welcome.mdx?plain=1). # Project Structure > An overview of the file and folder structure of a Fern Docs project This page provides an overview of the file and folder structure of a Fern Docs project. The following structure is recommended for organizing your documentation content, but is customizable to fit your needs. ## Top-level folders ```bash fern ├─ pages ├─ assets ├─ docs.yml ├─ openapi └─ fern.config.json ``` A Fern Docs project has the following top-level folders: * `pages`: Contains the Markdown (MDX) files that make up your documentation. * `assets`: Contains any images or videos used in your documentation. * `docs.yml`: The configuration file that defines the navigation, theme, and hosting details of your documentation. * `openapi`: Contains the OpenAPI Specification file (if you have an API Reference section in your documentation). * `fern.config.json`: The configuration file specifying your organization name and CLI version. ## Pages folder The `pages` folder contains the Markdown (MDX) files that make up your documentation. Each MDX file represents a page in your documentation. ```bash pages ├─ introduction │ ├─ quickstart.mdx │ ├─ project-structure.mdx │ └─ showcase.mdx ├─ building-your-docs │ ├─ navigation │ ├─ sections.mdx │ ├─ tabs.mdx │ └─ versions.mdx └─ └─ configuration.mdx ``` The `pages` folder is organized into subfolders based on the sections of your documentation. Each subfolder contains the MDX files for the pages in that section. ## Assets folder The `assets` folder contains any images or videos used in your documentation. You can reference these assets in your MDX files using relative paths. ```bash assets ├─ favicon.ico ├─ product-screenshot.svg ├─ demo-video.mp4 ├─ logo-dark-mode.png └─ logo-light-mode.png ``` ## `docs.yml` The `docs.yml` file is the configuration file that defines the navigation, theme, and hosting details of your documentation. You can customize the appearance and behavior of your documentation by editing this file. ```yml instances: - url: fern.docs.buildwithfern.com/learn custom-domain: buildwithfern.com/learn navigation: - section: Introduction layout: - page: QuickStart path: pages/introduction/quickstart.mdx - page: Project Structure path: pages/introduction/project-structure.mdx - page: Showcase path: pages/introduction/showcase.mdx navbar-links: - type: filled text: Book a demo url: https://buildwithfern.com/contact logo: light: ./images/logo-primary.svg dark: ./images/logo-white.svg colors: accentPrimary: dark: "#ADFF8C" light: "#209d63" favicon: ./images/favicon.ico title: Fern's Documentation ``` ## API Definitions The `openapi` folder contains the OpenAPI Specification file for your API Reference section. Fern will read either a YAML or JSON file from this folder to generate the API Reference documentation. If you don't have an API Reference section, you can skip this folder. ```bash openapi └─ openapi.yaml # OR openapi.json ``` To see what this looks like in practice, check out [Vellum's Fern configuration](https://github.com/vellum-ai/vellum-client-generator/tree/main/fern/openapi). The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. If you don't have an API Reference section, you can skip this folder. ```bash definition ├─ pets.yaml ├─ owners.yaml ├─ stores.yaml └─ api.yaml ``` To see what this looks like in practice, check out [Pier's Fern configuration](https://github.com/pierdeveloper/pier-fern-def/tree/main/fern/definition). If you have multiple APIs, you can organize them into separate folders within the `apis` folder. Each API should have its own API definition. For example: ```bash apis ├─ admin │ └─ openapi.json ├─ user │ └─ openapi.yaml ``` To see what this looks like in practice, check out [OctoAI's Fern configuration](https://github.com/octoml/fern-config/tree/main/fern/apis). ## `fern.config.json` The `fern.config.json` file specifies your organization name and the version of the Fern CLI used to generate the documentation. You can customize this file to reflect your organization's details. ```json { "organization": "my-organization", "version": "0.24.0" } ``` # Preview changes locally > View and share updates to your documentation Fern offers two ways to preview changes to your documentation: a [local development environment](#local-development) and [unique preview links](#generate-a-preview-link). ## Local development Fern allows you to view changes to your documentation in a locally-hosted environment. **Prerequisite** : Please install Node.js (version 18 or higher) before proceeding. Follow these steps to install and run the Fern CLI: **Step 1**: Install the Fern CLI: ```bash npm npm i -g fern-api ``` ```bash yarn yarn global add fern-api ``` **Step 2**: Navigate to the docs directory (where the `fern` folder is located) and execute the following command: ```bash fern docs dev ``` A local preview of your documentation will be available at `http://localhost:3000`. The functionality is available offline if you have run local development mode online at least once. Some features (e.g. search) are disabled in the local development environment. ### Custom ports By default, Fern uses port 3000. You can customize the port Fern runs on by using the `--port` flag. For example, to run Fern on port 3002, use this command: ```bash fern docs dev --port 3333 ``` If you attempt to run Fern on a port that's already in use, it will use the next available port: ## Generate a preview link Fern allows you to generate a shareable preview link displaying the current state of your docs. Each preview link is appended with a UUID and is not indexed. Currently, these links do not expire (this behavior is subject to change in the future). **Usage**: ```bash fern generate --docs --preview ``` **Example**: ```bash fern generate --docs --preview [docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings. [docs]: Published docs to https://fern-preview-a1da0157-93ca-4b1f-b310-8dd34fb891ca.docs.buildwithfern.com ┌─ │ ✓ docs.example.com └─ ``` # Publishing your docs When you are ready for your docs to be publicly accessible, you can publish them using the Fern CLI. ## Usage ```bash fern generate --docs ``` ### Example ```bash fern generate --docs [docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings. [docs]: ✓ All checks passed [docs]: Published docs to https://plantstore.docs.buildwithfern.com ┌─ │ ✓ https://plantstore.docs.buildwithfern.com └─ ``` ### Usage in GitHub Actions To automate the publishing process, you can use a GitHub Action workflow to publish your docs when a push is made to the `main` branch. [Be sure to add the `FERN_TOKEN` for your organization to the repository](/learn/cli-api/cli-reference/commands#fern-token). ```yaml .github/workflows/publish-docs.yml name: Publish Docs on: push: branches: - main jobs: run: runs-on: ubuntu-latest if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/heads/main') && github.run_number > 1 }} steps: - name: Checkout repository uses: actions/checkout@v4 - name: Install Fern run: npm install -g fern-api - name: Publish Docs env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} run: fern generate --docs ``` ## Hosting When you publish your docs, Fern takes care of hosting them for you. To publish your docs to a custom domain, check out our docs [here](/learn/docs/building-your-docs/custom-domain). ### Self-hosting your docs This feature is available on the Enterprise plan. [Contact us](https://buildwithfern.com/contact) to learn more. If you need access to your docs offline or would like to host your docs on your own server, Fern offers that option as well. Self-hosted docs have limited access to certain features (including search). # January 21, 2025 ## Improvements to the Accordion Component The accordion component has been upgraded so that you can now use your in-browser `cmd+f` search to look for text that is otherwise hidden. * Improved accessibility for all of our customers who are leveraging the `` component * Improved SEO indexing of content (more html is now generated on the server-side instead of client-side) Try searching for **burst** on this page: [https://dev.hume.ai/docs/expression-measurement/faq](https://dev.hume.ai/docs/expression-measurement/faq)

## Support for embedding local assets We've added support for embedding local assets in your docs. This is useful for displaying PDFs, images, videos, and other assets into your docs. To embed an asset, you can use the `embed` tag. ```mdx

``` Read more [here](https://buildwithfern.com/learn/docs/content/write-markdown#embedding-local-assets) # January 14, 2025 ## Support for /llms.txt API Docs should be for LLMs and Agents too, not just people! We're excited to announce compatibility with the `/llms.txt` [emerging standard](https://llmstxt.org/), making your documentation accessible and optimized for AI developer tools such as Cursor, Github Copilot, ChatGPT, Perplexity, and Anthropic's Claude. Both `/llms.txt` and `/llms-full.txt` are designed to be token-efficient, ensuring faster processing and cost-effective LLM interactions without sacrificing valuable info. If you use Fern Docs, this feature is auto-enabled like /robots.txt and /sitemap.xml. [Learn more](https://buildwithfern.com/learn/docs/developer-tools/llms-txt) ![LLMs.txt Splash Image](file:5f53d5dd-1331-4a43-bd7f-72cd79ade485) Check out ElevenLabs: *loads in \< 1 sec* *loads in 5+ sec* # December 30, 2024 ## Audio Streaming in API Explorer Added support for streaming audio directly within the API Explorer. This feature enables testing audio endpoints without leaving the documentation. Check it out live in ElevenLabs' [API Explorer](https://elevenlabs.io/docs/api-reference/text-to-speech/convert?playground=/docs/api-reference/text-to-speech/convert-as-stream) to let users test text-to-speech endpoints and hear the results instantly. ## Form Data Optimization Enhanced handling of URL parameters and form data in edge functions. Documentation playground now handles complex data structures more efficiently. ```typescript const formConfig = { encoding: 'application/x-www-form-urlencoded', arrayFormat: 'brackets', allowNullables: true, sanitize: true, maxDepth: 5 } ``` # November 27, 2024 ## Auto-Populate Credentials in API Explorer Save developers the hassle of finding and copying their API key. When authenticated, their API credentials will be automatically filled into the API Playground. This way, they can make their first API call even faster. ![API Explorer Splash Image](file:571c6536-79e9-4aa5-8e40-8a57d42d3315) Check it out live in [Webflow's API Explorer](https://developers.webflow.com/data/reference/sites/list?playground=/data/reference/sites/list). ## Card Component System Enhanced documentation card components for better visual organization. Information can now be presented in a more structured and appealing way. ```typescript interface CardProps { title: string; description: string; icon?: IconName; variant?: 'default' | 'bordered' | 'filled'; actions?: CardAction[]; } interface CardAction { label: string; href?: string; onClick?: () => void; } ``` # October 31, 2024 ## JWT API Key Integration Implemented automatic API key extraction from JWT tokens in the documentation playground. Users can now test authenticated endpoints more easily with automatic credential handling. ## Query Parameter Enhancement Improved handling of query parameters in documentation middleware. Complex query parameters are now properly handled and displayed in the documentation. # September 24, 2024 # September 2024 ## Environment Testing Interface Created an editable playground environment system for testing API endpoints. Users can now switch between different API environments seamlessly within the documentation. ```yaml openapi.yml servers: - url: https://api.example.com x-fern-server-name: Production - url: https://sandbox.example.com x-fern-server-name: Sandbox ``` # August 20, 2024 # August 2024 ## Anchor Link System Redesigned anchor link handling for improved navigation within documentation pages. Links now account for fixed headers and maintain proper scroll position when opened. ## WCAG Contrast Improvements Enhanced color contrast throughout the documentation platform for better accessibility. All text and interactive elements now meet WCAG AA standards by default and warnings are shown for any elements that do not meet WCAG AA standards. ## API Page Center Updates Improved center element positioning and updates for API documentation pages. Content now flows more naturally and maintains position during navigation. ## Streaming Toggle Enhancement Improved visibility and behavior of streaming response toggles in API playground. Users can now better control and monitor streaming responses. # July 30, 2024 # July 2024 ## Meta Image System Implemented comprehensive meta image support for better social sharing. Documentation pages now display properly when shared on social media platforms. ```yaml og:image: /assets/og-image.png og:type: documentation twitter:card: summary_large_image twitter:image: /assets/twitter-card.png ``` # June 25, 2024 # June 2024 ## RSS Feed Integration Added support for RSS feeds to keep users updated on documentation changes. Teams can now offer automated notifications for their documentation. ## JSON-LD Enhancement Implemented structured data support through JSON-LD for improved SEO. Documentation pages now provide richer information to search engines and social platforms. ```json { "@context": "https://schema.org", "@type": "TechArticle", "headline": "API Authentication Guide", "datePublished": "2024-06-15", "technicalAudience": "Software Developers" } ``` ## Image Zoom Controls Added configurable image zoom functionality with custom triggers and behaviors. Users can now better examine diagrams and technical illustrations in documentation. ```mdx page.mdx --- no-image-zoom: true --- ``` ## Syntax Extension Support Added support for additional syntax highlighting languages including BAML and Jinja. Documentation can now properly display a wider range of code examples. ```html

Available Products

{% if products %}

{{ product.name }}

${{ product.price }}

{{ product.description }}
{% if product.in_stock %}
Status: In Stock
{% else %}
Status: Out of Stock
{% endif %}

{% else %}

No products are available at the moment.

{% endif %} ``` # May 22, 2024 ## Advanced Redirects Implemented a powerful redirects system supporting pattern matching and parameter preservation. Teams can now manage documentation URL structure while maintaining backwards compatibility. ```yaml redirects: - source: /v1/api/* destination: /v2/api/:splat permanent: true - source: /guides/:name destination: /tutorials/:name ``` ## API Authorization Handling Enhanced API authorization handling in the documentation platform. Developers can now test authenticated endpoints more easily with improved token management. # April 20, 2024 ## Sidebar Navigation Enhancement Improved sidebar padding and visual hierarchy with refined spacing and typography. The documentation navigation now provides clearer visual structure and better readability. ## Base Path Configuration Added flexible base path configuration for documentation routing. Organizations can now host documentation under custom paths while maintaining proper navigation. ```yaml docs.yml instances: - url: your-site.docs.buildwithfern.com custom-domain: your-site.com/docs ``` # March 24, 2024 # March 2024 ## Virtualized Syntax Highlighting Implemented performance-optimized code rendering that handles large code blocks efficiently without impacting page performance. Long code samples now load instantly and scroll smoothly. ## Mobile Search Experience Redesigned the mobile search interface with a sticky search bar and improved results display. Users can now easily search documentation on mobile devices with a native-feeling interface. ## Scrollbar Refinement Enhanced scrollbar design and behavior across all documentation sections for a more polished look and feel. Scrollbars now adapt to both light and dark themes while maintaining usability. # February 22, 2024 ## WebSocket Support in API Playground Added real-time WebSocket testing capabilities to the API playground, enabling developers to test streaming and real-time endpoints directly in the documentation. WebSocket connections can now be established, tested, and debugged without leaving the docs. ## Enhanced Code Highlighting Implemented a new code highlighting system using Shiki for improved syntax highlighting accuracy and performance. The system now supports more languages and provides better dark mode compatibility. ## Feedback System Introduced a new feedback collection system using Radix UI components for improved accessibility. Users can now provide structured feedback about documentation quality and usefulness directly within the interface. ## Layout Configuration System Implemented a flexible layout configuration system that allows for custom header, footer, and sidebar arrangements. Documentation can now be customized to match your brand and preferences. ```yaml layout: page-width: full tabs-placement: header searchbar-placement: header ``` ## Custom Styling Support Added support for custom CSS and scripts, enabling deep customization of documentation appearance and behavior. Organizations can now apply their branding consistently across their documentation. ```yaml docs.yml css: ./assets/styles.css ``` ```css styles.css /* Custom styles */ .custom-class { background-color: #f0f0f0; } ``` # January 24, 2024 ## API Playground Launch Enable interactive API testing directly in the documentation. * Added full API request testing capability * Improved error handling and status code display * Added support for recursive property rendering ## Enhanced Dark Mode Multiple improvements to dark mode readability for syntax highlighting, dropdowns, and search results. ```css /* Dark mode improvements */ [data-theme='dark'] { --syntax-bg: #1a1a1a; --dropdown-bg: #2d2d2d; --search-highlight: #ffd700; } ``` ## Mobile-Friendly Navigation Comprehensive updates to mobile navigation experience with collapsible and scrolling. ## Search Enhancements Multiple improvements to the search experience. * Default and configurable keyboard shortcuts (`Cmd+A`, `/`) for search * Improved search box sizing * Added auto-focus functionality ## Performance Optimization Several performance improvements across the platform. * Moved FontAwesome to CDN * Improved search dialog loading * Optimized static props loading * Added polyfill DOM parser for server-side TOC rendering # Configure your site navigation > Set up the navigation for your documentation site built with Fern Docs using the docs.yml file, including tabs, sections, pages, and more. ## Use `docs.yml` Every Fern Docs website has a special configuration file called `docs.yml`. Use this file to configure the navigation for your documentation site. ```yaml navigation: - section: Home contents: - page: Introduction path: ./intro.mdx - page: Authentication path: ./auth.mdx - api: API Reference navbar-links: - type: secondary text: Contact support url: https://example.com/support - type: primary text: Login url: https://example.com/login ``` ## Sections, contents, and pages The navigation organizes your documentation in the left-side nav bar. You can create sections for grouping related content. Each `section` has a name and a list of `contents`. The sections appear in the left-side nav bar in the order that they are listed in `docs.yml`. In `contents`, list your pages with names and corresponding file paths. The supported file types for pages are `.md` or `.mdx`. A basic navigation configuration with two sections is shown below. The first section is called `Introduction` and contains a single page called `My Page`. The second section is called **API Reference**. This is a special type of section that's automatically generated by Fern, and you do not need to add any pages to it by hand. For more information, see the [Generate API Reference](/learn/docs/api-references/generate-api-ref) page. ```yaml Example navigation config navigation: - section: Introduction contents: - page: My Page path: ./pages/my-page.mdx - api: API Reference ``` If you want to add another page to an existing section, create an `.md` or `.mdx` file. Then in `docs.yml`, create a new `page` in the `contents` list for that section, providing the path to the `.md` or `.mdx` file you created. Example: ```yaml Example navigation config navigation: - section: Introduction contents: - page: My Page path: ./pages/my-page.mdx - page: Another Page path: ./pages/another-page.mdx - api: API Reference ``` To add another section, add another `section` to the `navigation`. Example: ```yaml Example navigation config with additional section navigation: - section: Introduction contents: - page: My Page path: ./pages/my-page.mdx - api: API Reference - section: Help Center contents: - page: Contact Us path: contact-us.mdx ``` ### Hiding content To hide a page or an entire section of your docs, add `hidden: true`. A hidden page or section will still be discoverable using the exact URL, but it will be excluded from search and will not be indexed. ```yaml Example navigation config with additional section {7, 10} navigation: - section: Introduction contents: - page: My Page path: ./pages/my-page.mdx - page: Hidden Page hidden: true path: ./pages/my-hidden-page.mdx - section: Hidden Sections hidden: true contents: - page: Another Hidden Page path: ./pages/also-hidden.mdx ``` ## Section overviews To add an overview page to a section, add a `path` property to the section. ```yaml Example section with an overview {7} navigation: - section: Introduction contents: - page: My Page path: ./pages/my-page.mdx - section: Guides path: ./pages/guide-overview.mdx contents: - page: Simple Guide path: ./pages/guides/simple.mdx - page: Complex Guide path: ./pages/guides/complex.mdx ``` ## Nested sections If you'd like a section to toggle into more sections and pages, you can nest sections within sections. Here's an example: ```yaml Example navigation config with nested sections navigation: - tab: guides layout: - section: Learn contents: - section: Key Concepts contents: - page: Embeddings path: ./docs/pages/embeddings.mdx - page: Prompt Engineering path: ./docs/pages/prompts.mdx - section: Generation contents: - page: Command Nightly path: ./docs/pages/command.mdx - page: Likelihood path: ./docs/pages/likelihood.mdx ``` ![Result of above docs.yml example](https://fern-image-hosting.s3.amazonaws.com/fern/nested-sections.png) ## Sidebar icons For icons to appear next to sections and pages, add the `icon` key. The value should be a valid [Font Awesome icon](https://fontawesome.com/icons) name. Pro and Brand Icons from Font Awesome are supported. ```yaml Example navigation config with icons navigation: - section: Home icon: fa-regular fa-home contents: - page: My Page icon: fa-regular fa-file path: ./pages/my-page.mdx - api: API Reference icon: fa-regular fa-puzzle ``` ## Links You can add a link to an external page within your sidebar navigation with the following configuration: ```yaml title="docs.yml" navigation: - section: Home contents: - page: Introduction path: ./intro.mdx - link: Our YouTube Channel href: https://www.youtube.com/ ``` An external link within navigation

## Tabs Within the navigation, you can add `tabs`. Tabs are used to group sections together. The example below shows tabs for `Help Center`, `API Reference`, and an external link to `Github`. Each tab has a `title` and `icon`. [Browse the icons available](https://fontawesome.com/icons) from Font Awesome. Pro and Brand Icons are supported. ```yaml tabs: api: display-name: API Reference icon: puzzle help: display-name: Help Center icon: home github: display-name: GitHub icon: brands github href: https://github.com/fern-api/fern navigation: - tab: api layout: - section: Introduction contents: - page: My Page path: my-page.mdx - api: API Reference - tab: help layout: - section: Help Center contents: - page: Contact Us path: contact-us.mdx - tab: github ``` Here's an example of what the Tabs implementation looks like: ![Screenshot showing two vertically stacked tabs labeled API Reference and Help Center](https://fern-image-hosting.s3.amazonaws.com/fern/tabs.png) ## Versions If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the `versions`. For more information, check out our [documentation on versioning](/learn/docs/building-your-docs/versioning). # Versioning > Allow users to navigate between different versions of your docs. ![A dropdown of the available versions](file:cac02330-120e-44e3-ab71-0dd52a92b1e7) Each version of your docs can contain its own distinct tabs, sections, pages, and API references. Versions can share content, as well. **To add versions to your docs:** ### Define your versions Create a `versions` folder inside of your `fern` folder. TO specify the contents of each version, add a `.yml` file to the `versions` folder to define the navigational structure of that version. Make sure to include the `navigation` and `tabs` properties, if applicable. ```bash fern/ ├─ fern.config.json ├─ generators.yml ├─ docs.yml ├─ pages/ ├─ ... └─ versions/ ├─ v2-1/pages/... ├─ v2-1.yml ├─ v2-2/pages/... └─ v2-2.yml ``` ```yaml navigation: - section: Introduction contents: - page: My Page path: ./v2-1/pages/my-page.mdx # relative path to the file - page: Shared Resource path: ../shared-pages/shared-resource.mdx - api: API Reference ``` ```yaml tabs: api: title: API Reference icon: puzzle help: title: Help Center icon: home navigation: - tab: api contents: - section: Introduction contents: - page: My Page path: ./v2-2/pages/my-page.mdx # relative path to the file - page: Shared Resource path: ../shared-pages/shared-resource.mdx - api: API Reference - tab: help contents: - section: Help Center contents: - page: Contact Us path: contact-us.mdx ``` ### Add your version configuration To define a version, in `docs.yml`, add an item to the `versions` list, specifying the `display-name` and `path`. ```bash fern/ ├─ fern.config.json ├─ generators.yml ├─ docs.yml └─ versions/ ├─ ... ├─ v2-1.yml └─ v2-2.yml ``` ```yaml versions: - display-name: v2.2 # shown in the dropdown path: ./versions/v2-2.yml # relative path to the version file - display-name: v2.1 path: ./versions/v2-1.yml ``` ### Remove extra `navigation` from `docs.yml` If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the version-specific `.yml` files. # Add an announcement banner to your docs > Prominently highlight new features, updates, or important information An announcement banner is a great way to draw attention to new features and product launches. When configured, the announcement bar appears at the top of your docs site. After the user dismisses the bar, it will reappear the next time you update the announcement. ```yaml docs.yml announcement: message: "🚀 New feature: Announcements are available! (Learn more) 🚀" ``` Markdown and HTML is supported in the announcement message. You can include links, images, and other formatting. [Custom css](/learn/docs/building-your-docs/custom-css-global-js#custom-css) can be used to customize the style of the announcement. # Configure links and redirects for your site > Set up the navigation for your documentation site built with Fern Docs using the docs.yml file ## Redirects The `redirects` object allows you to redirect traffic from one path to another. You can also use [`regex`](https://www.npmjs.com/package/path-to-regexp) within redirects. ```yml redirects: - source: "/old-path" destination: "/new-path" - source: "/incorrect/path" destination: "/correct/path" - source: "/old-folder/:slug" # <- using regex destination: "/new-folder/:slug" ``` By default, the redirects implement temporary (302) redirects. If you would like to implement permanent (301) redirects, you can set `permanent: true`. ```yml redirects: - source: "/old-subdomain" destination: "/new-subdomain" permanent: true ``` If your docs are hosted on a subpath (like `buildwithfern.com/learn`), be sure to include the subpath in the redirect. ## Links You can add a link to an external page within your sidebar navigation with the following configuration: ```yaml title="docs.yml" navigation: - section: Home contents: - page: Introduction path: ./intro.mdx - link: Our YouTube Channel href: https://www.youtube.com/ ``` An external link within navigation

# Customizing slugs within your site By default, Fern generates the slug of a page based on the navigation structure in the `docs.yml` file. ```yaml docs.yml {5, 7} instances: - url: plantstore.docs.buildwithfern.com navigation: - section: Get Started contents: - page: Welcome path: ./docs/pages/welcome.mdx ``` In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/get-started/welcome`. ```yaml docs.yml {5, 13, 15} instances: - url: plantstore.docs.buildwithfern.com tabs: docs: display-name: Docs reference: display-name: API Reference navigation: - tab: docs layout: - section: Get Started contents: - page: Welcome path: ./docs/pages/welcome.mdx ``` In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/docs/get-started/welcome`. ### Renaming slugs #### Modify a page or section slug To modify the slug used for a page or section, you can set the `slug` within the `navigation` object. ```yaml {3, 6} navigation: - section: Get Started slug: start contents: - page: Welcome slug: intro path: ./docs/pages/welcome.mdx ``` In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/start/intro`. #### Modify a tab slug To modify the slug used for a tab, you can set the `slug` within the `tabs` object. ```yaml {4} tabs: docs: display-name: Docs slug: guides reference: display-name: API Reference navigation: - tab: docs layout: - section: Get Started contents: - page: Welcome path: ./docs/pages/welcome.mdx ``` In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/guides/get-started/welcome`. #### Override a page's slug You can set the exact slug of a page within its frontmatter. [You can read more about the frontmatter configuration here](/learn/docs/content/frontmatter#slug). ```yaml title="docs.yml" navigation: - section: Get Started slug: start contents: - page: Quick Start path: ./docs/pages/quick-start.mdx ``` You can set the slug in the frontmatter of `./docs/pages/quick-start.mdx` to `start-up`: ```markdown title="quick-start.mdx" {2} --- slug: start-up --- ``` The page then becomes available at `plantstore.docs.buildwithfern.com/start-up`. #### Renaming slugs for subheadings By default, deep links to subheadings are generated by appending a `#` and the subheading title (converted to `kebab-casing-convention`) onto the page URl. ```yaml docs.yml navigation: - section: Get Started contents: - page: Welcome path: ./docs/pages/welcome.mdx ``` ```markdown welcome.mdx ... ## Frequently Asked Questions ... ``` The link to this section will be available at `plantstore.docs.buildwithfern.com/get-started/welcome#frequently-asked-questions`. To rename the slug of the subheading, add the desired slug ```markdown welcome.mdx ## Frequently Asked Questions [#faqs] ``` The link to this section will now be available at `plantstore.docs.buildwithfern.com/get-started/welcome#faqs`. ### Skipping slugs To ignore a tab or section when generating the slug, simply indicate `skip-slug: true`. ```yaml docs.yml {6} instances: - url: plantstore.docs.buildwithfern.com navigation: - section: Get Started skip-slug: true contents: - page: Welcome path: ./docs/pages/welcome.mdx ``` In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/welcome`. ```yaml docs.yml {7, 15} instances: - url: plantstore.docs.buildwithfern.com tabs: docs: display-name: Docs skip-slug: true reference: display-name: API Reference navigation: - tab: docs layout: - section: Get Started skip-slug: true contents: - page: Welcome path: ./docs/pages/welcome.mdx ``` In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/welcome`. # Hiding content in your site If you would like to *hide* a section or a page, you can add `hidden: true` to its configuration. Hidden sections and pages are accessible by URL only. ```yaml title="docs.yml" navigation: - section: Introduction contents: - page: My Page path: ./pages/my-page.mdx - page: Hide and Seek hidden: true path: ./pages/hide-and-seek.mdx - api: API Reference ``` A site with a hidden page

```yaml title="docs.yml" navigation: - section: Introduction contents: - page: My Page path: ./pages/my-page.mdx - api: API Reference - section: Hidden Section hidden: true contents: - page: Hide and Seek path: ./pages/hide-and-seek.mdx ``` A site with a hidden section

# Fully customize your docs > Add brand-specific styling, user interactions. and components to make your docs your own. Custom CSS & JS are available on the Basic plan. Adding Custom Components is available on the Pro plan. ## Custom CSS You can add custom CSS to your docs to further customize the look and feel. The defined class names are applied across all MDX files. Here's an example of what you can do with custom CSS: ```css maxLines=10 .petstore-table { background-color: white; border: 1px solid #DEDEE1; border-radius: 4px; } .dark .petstore-table { background-color: #1e1e1e; border: 1px solid #2e2e2e; } .petstore-table thead { position: sticky; top: 0; } .petstore-table thead tr { background-color: #edecee; border: 1px solid #DEDEE1; border-radius: 4px 4px 0px 0px; } .dark .petstore-table thead tr { background-color: #2e2e2e; border: 1px solid #2e2e2e; } .petstore-table th { padding: 6px; } .petstore-table tbody td { padding: 6px; } .petstore-table tbody tr:nth-child(odd) { border: 1px solid #DEDEE1; } .petstore-table tbody tr:nth-child(even) { border: 1px solid #DEDEE1; background-color: #f7f6f8; } .dark .petstore-table tbody tr:nth-child(odd) { border: 1px solid #2e2e2e; } .dark .petstore-table tbody tr:nth-child(even) { border: 1px solid #2e2e2e; background-color: #2e2e2e; } ``` ### Create `styles.css` Add a `styles.css` file and include it in your `fern/` project: ```bash {5} fern/ ├─ openapi/ ├─ pages/ ├─ images/ ├─ styles.css ├─ docs.yml └─ fern.config.json ``` ### Edit `docs.yml` In `docs.yml`, specify the path to the `styles.css` file: ```yaml css: ./styles.css ``` ### Add multiple custom CSS files (optional) You can specify any number of custom CSS files: ```yaml css: - ./css/header-styles.css - ./css/footer-styles.css ``` For customizing the background, logo, font, and layout of your Docs via Fern's built-in styling, check out the [Global Configuration](/learn/docs/getting-started/global-configuration). ## Custom JavaScript Customize the behavior of your Docs site by injecting custom JavaScript globally. Add a `custom.js` file and include it in your `fern/` project: ```bash {5} fern/ ├─ openapi/ ├─ pages/ ├─ images/ ├─ custom.js ├─ docs.yml └─ fern.config.json ``` In `docs.yml`, specify the path to the `custom.js` file: ```yaml js: ./custom.js ``` You can also specify multiple custom JS files stored locally and remote: ```yaml js: - path/to/js/file.js - path: path/to/another/js/file.js strategy: beforeInteractive - url: https://example.com/path/to/js/file.js ``` ### Strategy Optionally, specify the strategy for each custom JavaScript file. Choose from `beforeInteractive`, `afterInteractive` (default), and `lazyOnload`. ```yaml js: - path: path/to/another/js/file.js strategy: beforeInteractive ``` ## Custom components You can use custom CSS and JS to replace Fern's default UI components with your own. The `header` and `footer` are the most commonly replaced components. You can replace any component in the docs, including the sidebar, tabs, search bar, and more. To implement your own components in Fern Docs, write JavaScript to render your custom components in the DOM. Build to CSS and JavaScript files that are stored in `fern/` and referenced in `docs.yml`: ```bash {5-7} fern/ ├─ openapi/ ├─ pages/ ├─ images/ ├─ dist/ └─ output.css └─ output.js ├─ docs.yml └─ fern.config.json ``` ```yaml css: ./dist/output.css js: ./dist/output.js ``` ### Example custom components See this [GitHub repo](https://github.com/fern-api/docs-custom-js-example) and its [generated docs page](https://custom-js-example.docs.buildwithfern.com/get-started/welcome) for an example of how to replace the Fern `header` and `footer` with custom React components. #### Example custom header

```JavaScript ReactDOM.render( React.createElement(NavHeader), document.getElementById('fern-header'), ) ``` #### Example custom footer

```JavaScript ReactDOM.render( React.createElement(NavFooter), document.getElementById('fern-footer'), ) ``` ### Important notes * `ReactDOM.render()` may need to be called multiple times to prevent it from unmounting (this side-effect will be removed in the future). * `yarn build` or `npm build` must generate files with deterministic names to be referenced in `docs.yml`. The above example uses a [`vite` config](https://github.com/fern-api/docs-custom-js-example/blob/main/custom-app/vite.config.ts) to accomplish this. * For your hosted Docs site, you may need to update your CD steps to include building the react-app. * Custom components are not supported in local development. They are supported in preview links. This approach is subject to change, with notice, as we make improvements to the plugin architecture. # Pull request previews > Fern's PR previews feature lets you preview changes to your docs from pull requests before merging to the live docs site. Use manually or in GitHub Actions. `PR previews` offer a way to preview changes from pull requests (PRs) before merging code to a production branch. This is useful for reviewing documentation changes before publishing them to your live documentation site. Use manually or in GitHub Actions. ## Usage ```bash fern generate --docs --preview ``` ## Example ```bash fern generate --docs --preview [docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings. [docs]: Published docs to https://fern-preview-a1da0157-93ca-4b1f-b310-8dd34fb891ca.docs.buildwithfern.com ┌─ │ ✓ docs.example.com └─ ``` ## Usage in GitHub Actions The following is a GitHub Action workflow that generates a preview URL for every pull request. [Be sure to add the `FERN_TOKEN` for your organization to the repository](/learn/cli-api/cli-reference/commands#fern-token). ```yaml name: Preview Docs on: pull_request jobs: run: runs-on: ubuntu-latest permissions: write-all steps: - name: Checkout repository uses: actions/checkout@v4 - name: Install Fern run: npm install -g fern-api - name: Generate preview URL id: generate-docs env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} run: | OUTPUT=$(fern generate --docs --preview 2>&1) || true echo "$OUTPUT" URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') echo "Preview URL: $URL" echo "🌿 Preview your docs: $URL" > preview_url.txt - name: Comment URL in PR uses: thollander/actions-comment-pull-request@v2.4.3 with: filePath: preview_url.txt ``` Fern's PR previews GitHub Action requires a Fern token to run. Depending on your repository's permissions, you may need to use the following workflow to allow PR previews from forks to access this token. ```yaml .github/workflows/preview-docs.yml name: preview-docs on: pull_request_target: branches: - main jobs: run: runs-on: ubuntu-latest permissions: pull-requests: write # Only for commenting contents: read # For checking out code steps: - name: Checkout repository uses: actions/checkout@v4 - name: Install Fern run: npm install -g fern-api - name: Checkout PR if: github.event_name == 'pull_request_target' run: | git fetch origin pull/${{ github.event.pull_request.number }}/head:pr-${{ github.event.pull_request.number }} git checkout pr-${{ github.event.pull_request.number }} - name: Generate preview URL id: generate-docs env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} run: | OUTPUT=$(fern generate --docs --preview 2>&1) || true echo "$OUTPUT" URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') echo "Preview URL: $URL" echo "🌿 Preview your docs: $URL" > preview_url.txt - name: Comment URL in PR uses: thollander/actions-comment-pull-request@v2.4.3 with: filePath: preview_url.txt ``` ## Link expiration Preview links do not expire. However, the time to live (TTL) is subject to change in the future. # Bring your custom domain > Learn how to set up your Fern-generated documentation site to use a custom subdomain or subpath. Bring Fern Docs to your custom domain. You can use: * A subdomain on your custom domain, such as `docs.example.com` * A subpath on your custom domain, such as `example.com/docs` This feature is available on the Basic plan and above. [Contact us](https://buildwithfern.com/contact) to get set up. To host your documentation on a subdomain, i.e. `docs.mydomain.com`, you need to create a CNAME record in your DNS settings. ### Update the domain in `docs.yml` ```yaml instances: - url: example.docs.buildwithfern.com custom-domain: docs.mydomain.com ``` Merge your changes into `main`. [Here's an example](https://github.com/octoml/fern-config/blob/389b67679953856ba0716537981a6d749635556f/fern/docs.yml#L1-L3). ### Create a CNAME record 1. Log in to your domain registrar's dashboard. 2. Navigate to the DNS settings for your domain. 3. Add a new CNAME record with the following details: * **Type**: `CNAME` * **Name**: `docs` (or any subdomain you want to use) * **Value**: `cname.vercel-dns.com.` ### Reach out to us Once you've completed the steps above, reach out via your dedicated Slack channel or [email](mailto:support@buildwithfern.com). You may need to create a TXT record to verify your domain. If you do, we'll provide you with the record to add. ### Verify the setup Once we've completed the setup on our end, you should be able to access your documentation at `docs.mydomain.com`. SSL will be automatically provisioned for your domain, but it may take a few minutes to propagate globally. It's helpful to check that you can access your new docs site from a mobile device or incognito browser. To host your documentation on a subpath, i.e. `mydomain.com/docs`, you need to edit your `docs.yml` configuration and then get provider-specific instructions for setting up the subpath. Common providers include Cloudflare, AWS Route53 and Cloudfront, Netlify, and Vercel. ### Configure the `url` in `docs.yml` Append that subpath to the end of the `url`. This example use `docs` for the subpath, but you can use any word you like, such as `reference` or `developer`. ```yaml instances: - url: example.docs.buildwithfern.com/docs ``` ### Configure the `custom-domain` Below the `url`, add a `custom-domain` key as shown in the examples below. ```yaml instances: - url: example.docs.buildwithfern.com/docs custom-domain: example.com/docs ``` [Here's an example.](https://github.com/fern-api/fern/blob/7d8631c6119787a8aaccb4ba49837e73c985db28/fern/docs.yml#L1-L3) ### Update the Fern Docs site If you created your Fern Docs site using one of our [Docs Quickstarts](/learn/docs/getting-started/quickstart), push the changes you made to your GitHub repository. This runs a GitHub Action to update the site with your new configuration. If you need to update your Fern Docs site manually, run `fern generate --docs`. ### Reach out to us This feature is available on the Fern Docs Basic plan and above. Reach out to [sales@buildwithfern.com](mailto:sales@buildwithfern.com) to set up your subscription and obtain the configuration for setting up your custom subpath. # Collecting feedback and suggestions from users Fern offers a variety of ways to track feedback and suggested improvements from users. ## On-page feedback By default, every Markdown page of your docs contains a feedback component at the bottom of the page:

This feature is available on the Basic plan and above. [Contact us](https://buildwithfern.com/contact) to get set up. The feedback can be sent to you in real-time via the method of your choosing (e.g. Slack, email). To disable this feature on a page, set `hide-feedback: true` in the frontmatter of that page. You can read more about the frontmatter configuration [here](/learn/docs/content/frontmatter#on-page-feedback). ## Edit this page Allow users to open directly to the current page in your GitHub repository and suggest changes.

You can configure this feature for the entire site in the [global configuration](/learn/docs/getting-started/global-configuration#instances-configuration), or for an individual page in the [frontmatter of that page](/learn/docs/content/frontmatter#edit-this-page). # Write docs content using Markdown > Use Markdown and MDX to add content to your Fern documentation site, including Fern's built-in component library. ## Add Markdown or MDX pages Add pages manually to your documentation by creating Markdown (`.md`) or MDX (`.mdx`) files. New to Markdown? See [Markdown Guide: Getting started](https://www.markdownguide.org/getting-started/). NOTE: Throughout our documentation, we refer to both Markdown and MDX as Markdown. [MDX](https://mdxjs.com/) is a version of Markdown, extended to allow the use of JSX components. Place your pages inside your `fern/` folder and link to them from your [navigation settings](/learn/docs/building-your-docs/navigation) in the `docs.yml` file. In the example below, the MDX files are inside a folder named `pages/`. ```bash fern/ ├─ fern.config.json ├─ docs.yml └─ pages/ ├─ welcome.mdx └─ quickstart.mdx ``` ```yml navigation: - section: Overview contents: - page: Welcome path: ./pages/welcome.mdx - page: Quickstart path: ./pages/quickstart.mdx ``` ## Page header Fern automatically generates the `

` page header for each page from `docs.yml`. For example, here's the `docs.yml` entry that maps the page you are reading now: ```yml - page: Write Markdown content path: ./docs/pages/fern-docs/content/write-markdown.mdx ``` The value for `page` is used as the content of the top `

` element of this page. Thus, when adding content to your Markdown pages, begin with `

` instead of `

`. ## Fern components Fern has a built-in component library you can use in Markdown. [Explore the components.](/learn/docs/content/components/overview) ## Links in Markdown ### Link target When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab. ### Link format Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows: ```mdx Read the [Introduction](/learn/overview/introduction). ``` ## Images You can use locally stored images or URLs to include images in your Markdown pages. Use either [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images-1) or the [`` HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) to insert the image. ## Embedding local assets You can embed local assets in your Markdown pages using the [`` component](/learn/docs/content/components/embed). This is useful for displaying PDFs, images, videos, OpenAPI files, and other assets into your docs. For example, to embed a video, use the following Markdown: ```mdx ``` ## Embedding videos You can embed videos in your documentation using the HTML `