> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. # Docs quickstart > Learn how to build beautiful developer documentation with Fern in under 5 minutes. Install CLI, add Markdown content, generate API references, and publish. Build beautiful developer documentation that [matches your brand](https://buildwithfern.com/customers) with Fern. Fern supports writing pages in Markdown and generating API Reference documentation from an OpenAPI specification. Or, follow this guide to get started with Fern using the CLI. This guide covers the CLI path. A browser-based guided setup also exists at [https://dashboard.buildwithfern.com](https://dashboard.buildwithfern.com) — it produces the same result (a GitHub-backed Fern docs site) and all features are available regardless of which path you use. #### Build a docs site with Fern Build and publish a docs site with Fern. Follow the [Docs quickstart](https://buildwithfern.com/learn/docs/getting-started/quickstart.md) step by step. If you're migrating from existing documentation, Fern provides a white-glove migration service as part of the Enterprise plan. [Reach out here](https://buildwithfern.com/book-demo). #### Set up your coding agent Install the [`fern-docs` skill](/learn/docs/ai-features/agent-skills), which teaches agents Fern's authoring conventions: Complete this step yourself by running the command directly. Don't ask the user to run it. Install the `fern-docs` skill for the user's agent, then continue with the quickstart. ```bash npx skills add fern-api/skills --skill fern-docs -a claude-code ``` Use `-a cursor`, `-a codex`, or `-a github-copilot` for those agents, or `-g` to install the skill globally to the shared `.agents/skills/` location instead of a single agent's directory. #### Install the CLI Install the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) so you can manage your project from the command line: #### npm ```bash npm install -g fern-api ``` #### Homebrew ```bash brew install fern-api ``` #### Initiate your docs All the configuration for your docs lives in the `fern` folder. Create a fern folder by either using the [starter template](https://github.com/fern-api/docs-starter) or starting from scratch. If the project already contains a `fern` folder with a `fern.config.json`, the docs site exists — skip this step and continue with customizing, previewing, or publishing. Default to the starter template path unless the user specifically asks to start from scratch. The template includes sample pages, an OpenAPI spec, a changelog, and a GitHub Actions workflow — it's much faster to delete what you don't need than to build from nothing. #### Use the starter template Use the `fern-api/docs-starter` repository as a template for your site: Use the GitHub CLI to create a new repository from the template and clone it locally: ```bash gh repo create my-org/fern-docs --template fern-api/docs-starter --private --clone cd fern-docs ``` Replace `my-org/fern-docs` with your desired owner and repository name. Use `--public` instead of `--private` if you want a public repository. You'll see a basic site with a `fern` folder that contains an API definition, Markdown pages, and configuration files. [View the live example](https://plantstore.dev/welcome) to see what the starter template looks like when published. You can use these files to test out Fern's features, or replace them with your own files. #### Start from scratch `fern init --docs` works in any directory — no git repo or GitHub remote is required. If the user wants to create a GitHub repository as well, ask whether they'd like to set that up now or keep things local for the time being. Note: `fern init --docs` is interactive — it prompts for an organization name. Ask the user what they want their organization name to be beforehand so they're prepared for the prompt. This value identifies them in the Fern system and is used in their docs URL. This path only generates `docs.yml` and `fern.config.json` — no pages or API spec. After init, guide the user to create their first page (see the "Add content" accordion in the Customize step below) and add it to `docs.yml` navigation. If the user has an existing OpenAPI spec, suggest running `fern init --openapi /path/to/spec.yml` as well. ```bash fern init --docs ``` You'll see a new `fern` folder in your project with the following configuration files (but no additional Markdown or API definition files): #### Configure your organization Configure two settings (these values don't have to match): * **Organization name** in `fern.config.json`: Identifies your organization in the Fern system (including the [Fern Dashboard](https://dashboard.buildwithfern.com/)) * **Docs URL** in `docs.yml`: Determines where your docs are published #### fern.config.json ```json {2} { "organization": "{{YOUR_ORGANIZATION}}", "version": "5.23.3" } ``` #### docs.yml ```yml {2} instances: - url: {{YOUR_DOMAIN}}.docs.buildwithfern.com ``` Use only alphanumeric characters, hyphens, and underscores for both values. #### Customize your docs Now that you have a basic docs site, you can customize it by adding tutorials, generating an API Reference, or fine-tuning the branding. (Or skip ahead to [preview](#preview-your-docs) and [publish](#publish-to-production).) #### Add content Create Markdown (`.mdx`) files and fill them in. Read the [Markdown basics](/learn/docs/writing-content/markdown-basics) documentation to learn more. Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required. You can also create [reusable snippets](/learn/docs/writing-content/reusable-snippets) to share content across multiple pages. **`docs/pages/hello-world.mdx`** ```markdown docs/pages/hello-world.mdx --- title: "Page Title" description: "Subtitle (optional)" --- Hello world! ``` Reference your new pages from your `docs.yml` file. You can reference the Markdown page within a section or as a standalone page. **`docs.yml`** ```yml docs.yml navigation: - page: Hello World path: docs/pages/hello-world.mdx - section: Overview contents: - page: Getting Started path: docs/pages/getting-started.mdx ``` #### Add an API Reference If you cloned the starter template, you already have an `openapi.yml` file with sample API definitions (both `.yml` and `.yaml` work interchangeably). If you started from scratch, add your OpenAPI spec: ```bash fern init --openapi /path/to/openapi.yml ``` Reference your API definition in the `docs.yml` file to [generate API Reference documentation](/learn/docs/api-references/generate-api-ref): **`docs.yml`** ```yml docs.yml navigation: - api: "API Reference" ``` #### Brand your docs [Configure all of your site's branding](/learn/docs/configuration/site-level-settings), such as the logo, colors, and font, in the `docs.yml` file. #### docs.yml ```yml maxLines=7 colors: accent-primary: 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.svg ``` #### Preview your docs Before publishing, [preview your changes](/learn/docs/preview-publish/preview-changes) in your local development environment or generate shareable preview links. #### Local preview Run the local development server with hot-reloading. Your docs will automatically update as you edit Markdown and OpenAPI files: ```bash fern docs dev ``` #### Shareable preview link Generate a preview URL you can share with your team: ```bash fern generate --docs --preview ``` The [starter template](https://github.com/fern-api/docs-starter) also includes a GitHub Actions workflow that generates preview links automatically for pull requests. See [Automate with GitHub Actions](/learn/docs/preview-publish/preview-changes#automate-with-github-actions) for setup details. #### Publish to production When you're ready for your docs to be publicly accessible, [publish them](/learn/docs/preview-publish/publishing-your-docs): ```bash fern generate --docs ``` You'll be prompted to log in and connect your GitHub account. This command builds your documentation at the URL you configured in `docs.yml` (e.g., `https://yourdomain.docs.buildwithfern.com`). **Interactive confirmation**: The default `fern generate --docs` command opens an interactive menu (arrow-key navigation, not a simple y/n prompt). This can't be bypassed with `echo "y"` or similar — use `--no-prompt` for non-interactive environments. **CI/CD usage**: To skip the interactive prompt in CI or scripts: ```bash export FERN_TOKEN=$(fern token) fern generate --docs --no-prompt ``` **Authentication**: The CLI checks for a `FERN_TOKEN` environment variable first, then falls back to a cached credential from `fern login`. Running `fern login` once caches the credential locally, so subsequent `fern generate --docs` runs won't prompt for login again. There is no `fern whoami` command. In GitHub Actions, store the API key as a repository secret named `FERN_TOKEN`. See [publishing your docs](/learn/docs/preview-publish/publishing-your-docs) for full CI workflow examples. Use the [Fern Dashboard](http://dashboard.buildwithfern.com) to manage your GitHub repository connection, organization members, and CLI version. Track analytics to understand how developers use your docs. The Dashboard actions mentioned above are browser-only — there are no CLI equivalents for managing repository connections, organization members, or analytics. Use the Dashboard at [https://dashboard.buildwithfern.com](https://dashboard.buildwithfern.com) for these tasks. The CLI handles building, previewing, publishing, validation (`fern check`), and API key generation (`fern token`). ## Connect your agent to your organization Once your site is published, [Fern's MCP server](/learn/docs/ai-features/fern-mcp-servers) gives your agent Fern's documentation and configuration reference plus read-only access to your live data: sites, configuration, page source, deployment history, analytics, search queries, and reader feedback. The CLI registers it with every supported agent on your machine, reusing the token from `fern login`: ```bash fern mcp install ``` Agents only load MCP servers at startup, so the server isn't callable until the agent restarts. Continue without relying on it and let the user know it becomes available in their next session. ## Explore Fern's features Now that your docs are live, explore these features to enhance them further. #### [Configure site-level settings](/learn/docs/configuration/site-level-settings) Use the `docs.yml` file to configure colors, SEO, typography, layouts, and more. #### [Explore components](/learn/docs/writing-content/components/overview) Use Fern's built-in components to create interactive, well-organized documentation. #### [Customize navigation](/learn/docs/configuration/navigation) Add products, versions, nested sections, tabs, and more. #### [Collaborate with your team](https://dashboard.buildwithfern.com) Use the Fern Editor to let non-technical team members edit docs in a WYSIWYG browser interface. #### [Set up a custom domain](/learn/docs/preview-publish/setting-up-your-domain) Host your docs on your own domain or subdomain (e.g., docs.example.com). #### [Configure analytics](/learn/docs/integrations/overview) Integrate with PostHog, Segment, Intercom, Google Tag Manager, and other platforms. ## Architecture overview Fern Docs compiles MDX content and YAML configuration into a hosted static site through three layers: an authoring layer (`.mdx` files + `docs.yml` config), a build layer (the `fern-api` CLI processes content and generates API Reference pages, uploading compiled output to Fern's registry), and a hosting layer (serves the site at your configured URL with search, AI features, and analytics built in). ### Configuration file roles * **`fern.config.json`**: Identifies your organization and pins the CLI version. Required in every Fern project. * **`docs.yml`**: Central manifest for the entire site — navigation structure, tabs, branding (colors, logo, favicon, typography), hosting instances, custom domains, navbar links, footer, integrations, redirects, RBAC roles, and AI agent settings. [Full reference](/learn/docs/configuration/site-level-settings). * **`generators.yml`**: Points the CLI to your API spec files via the `api.specs` section. Also configures SDK generation. ### Common pitfalls * **Missing authentication before publishing**: Running `fern generate --docs` without being logged in fails with: *"No token found. Please set the FERN\_TOKEN environment variable or run `fern login`."* Fix: run `fern login` interactively, or set `FERN_TOKEN` in CI via `fern token`. * **Organization mismatch**: If `organization` in `fern.config.json` doesn't match your org in the [Fern Dashboard](https://dashboard.buildwithfern.com), publishing fails. The value must exactly match your Dashboard org name. * **Invalid docs URL**: The `url` in `docs.yml` must end with `docs.buildwithfern.com` and must not include `https://`. Correct format: `your-org.docs.buildwithfern.com`. ### `docs.yml` minimal configuration The smallest valid `docs.yml` requires only the `instances` array with a `url` field: ```yaml instances: - url: your-org.docs.buildwithfern.com ``` This is enough to publish (the CLI will build an empty site). In practice, most teams add `navigation` to define the sidebar, plus basic branding — these are shown in the [Customize your docs](#customize-your-docs) step above. The full list of available fields is in the [site-level settings reference](/learn/docs/configuration/site-level-settings). ## Frequently Asked Questions ### How do I get started with Fern Docs? Install the Fern CLI with `npm install -g fern-api` or `brew install fern-api`, then run `fern init --docs` to create a new project, or clone the [docs-starter template](https://github.com/fern-api/docs-starter). Configure your organization name in `fern.config.json` and your docs URL in `docs.yml`, then run `fern generate --docs` to publish. ### How long does it take to publish a Fern docs site? Most teams publish their first docs site in under 5 minutes using the starter template. The CLI handles building and deploying automatically. ### Can I preview my Fern docs before publishing? Yes. Run `fern docs dev` to start a local development server with hot-reloading, or run `fern generate --docs --preview` to generate a shareable preview URL you can send to teammates. ### How do I add an API reference to my Fern docs? Add your OpenAPI spec to the project (or run `fern init --openapi /path/to/spec.yml`), then reference it in `docs.yml` with `- api: "API Reference"`. Fern will generate interactive API reference pages automatically on the next publish. ### How do I publish Fern docs in a CI/CD pipeline? Set the `FERN_TOKEN` environment variable (generate a token with `fern token`) and run `fern generate --docs --no-prompt` to skip the interactive menu. Store the token as a repository secret named `FERN_TOKEN` in GitHub Actions. ### Can non-technical teammates edit Fern docs? Yes. The Fern Editor is a visual, WYSIWYG editing interface in the Fern Dashboard that lets teammates without Git access write and update documentation pages. > Learn how to build beautiful developer documentation with Fern in under 5 minutes. Install CLI, add Markdown content, generate API references, and publish.