# 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.

Follow this guide to get started with Fern using the CLI, or use the [self-service setup](/learn/docs/getting-started/self-service-setup) for a guided UI flow.

<Note>
  Migrating from existing documentation? Fern provides a white-glove migration service as part of the Enterprise plan. [Reach out here](https://buildwithfern.com/contact).
</Note>

<Steps toc={true}>
  <Step title="Install the CLI">
    Install the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) so you can manage your project from the command line:

    ```bash
    npm install -g fern-api
    ```
  </Step>

  <Step title="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

    <AccordionGroup>
      <Accordion title="Clone the starter template">
        <CodeBlocks>
          ```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
          ```
        </CodeBlocks>

        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.

        <Files>
          <Folder name="fern" defaultOpen>
            <Folder name="docs" comment="Markdown content and assets">
              <Folder name="pages">
                <File name="welcome.mdx" />

                <File name="sdks.mdx" />

                <File name="light.mdx" />

                <File name="concepts.mdx" />

                <Folder name="tutorials" />

                <Folder name="get-started" />

                <Folder name="capabilities" />
              </Folder>

              <Folder name="changelog" comment="Version history and release notes" />

              <Folder name="assets" />

              <Folder name="snippets" comment="Reusable content blocks">
                <File name="note.mdx" />
              </Folder>
            </Folder>

            <File name="docs.yml" comment="Defines navigation, theme, and hosting details" />

            <File name="fern.config.json" comment="Specifies org name and CLI version" />

            <File name="generators.yml" comment="Configures SDK generation" />

            <File name="openapi.yaml" comment="API definition" />
          </Folder>

          <File name="README.md" />
        </Files>
      </Accordion>

      <Accordion title="Start from scratch">
        ```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):

        <Files>
          <Folder name="fern" defaultOpen>
            <File name="docs.yml" comment="Defines navigation, theme, and hosting details" />

            <File name="fern.config.json" comment="Specifies org name and CLI version" />
          </Folder>
        </Files>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="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

    <CodeBlock title="fern.config.json">
      ```json {2}
      {
        "organization": "{{YOUR_ORGANIZATION}}",
        "version": "3.57.0"
      }
      ```
    </CodeBlock>

    <CodeBlock title="docs.yml">
      ```yml {2}
      instances:
        - url: {{YOUR_DOMAIN}}.docs.buildwithfern.com
      ```
    </CodeBlock>

    <Note>
      Use only alphanumeric characters, hyphens, and underscores for both values.
    </Note>
  </Step>

  <Step title="Customize your docs">
    Now that you have a basic docs site, you can customize it by adding tutorials, generating an API Reference, or finetuning the branding. (Or skip ahead to [preview](#preview-your-docs) and [publish](#publish-to-production).)

    <AccordionGroup toc={true}>
      <Accordion title="Add content">
        Create Markdown (`.mdx`) files and fill them in. Read the [Markdown basics](/learn/docs/writing-content/markdown-basics) documentation to learn more.

        <Note>
          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.
        </Note>

        ```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.

        ```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
        ```
      </Accordion>

      <Accordion title="Add an API Reference">
        If you cloned the starter template, you already have an `openapi.yaml` file with sample API definitions. 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):

        ```yml docs.yml
        navigation:
          - api: "API Reference"
        ```
      </Accordion>

      <Accordion title="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.

        <CodeBlock title="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
          ```
        </CodeBlock>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Preview your docs">
    Before publishing, [preview your changes](/docs/preview-publish/preview-changes) in your local development environment or generate shareable preview links.

    <Tabs>
      <Tab title="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
        ```
      </Tab>

      <Tab title="Shareable preview link">
        Generate a preview URL you can share with your team:

        ```bash
        fern generate --docs --preview
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="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
    ```

    This command builds your documentation at the URL you configured in `docs.yml` (e.g., `https://yourdomain.docs.buildwithfern.com`).

    <Info>
      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.
    </Info>
  </Step>
</Steps>

## Explore Fern's features

Now that your docs are live, explore these features to enhance them further.

<CardGroup>
  <Card title="Configure site-level settings" icon="sliders" href="/learn/docs/configuration/site-level-settings">
    Use the `docs.yml` file to configure colors, SEO, typography, layouts, and more.
  </Card>

  <Card title="Explore components" icon="cubes" href="/learn/docs/writing-content/components/overview">
    Use Fern's built-in components to create interactive, well-organized documentation.
  </Card>

  <Card title="Customize navigation" icon="sitemap" href="/learn/docs/configuration/navigation">
    Add products, versions, nested sections, tabs, and more.
  </Card>

  <Card title="Collaborate with your team" icon="users" href="https://dashboard.buildwithfern.com">
    Use the Fern Editor to let non-technical team members edit docs in a WYSIWYG browser interface.
  </Card>

  <Card title="Set up a custom domain" icon="globe" href="/learn/docs/preview-publish/setting-up-your-domain">
    Host your docs on your own domain or subdomain (e.g., docs.example.com).
  </Card>

  <Card title="Configure analytics" icon="chart-line" href="/learn/docs/integrations/overview">
    Integrate with PostHog, Segment, Intercom, Google Tag Manager, and other platforms.
  </Card>
</CardGroup>