Self-service setup | Fern Documentation

The self-service workflow guides you through creating a new Fern Docs site in a few steps. If you’re looking for an existing site you’ve already set up, search for your organization instead.

Prefer to set things up manually using the CLI? See the Quickstart instead.

What gets created

When you complete the self-service workflow, Fern publishes your documentation to a brand-new site and creates a GitHub repository containing your site configuration (docs.yml), Markdown pages, and any API specifications. Your repo includes a CLAUDE.md file pre-populated with Fern documentation in llms.txt format, giving AI coding assistants context for working with Fern.

The setup process also creates and configures:

Organization: An organization using your org ID, with you as a member.
Fern API key: A FERN_TOKEN in your repository’s GitHub secrets that authenticates the Fern CLI in your CI/CD workflows, scoped to your organization.
GitHub Action: A workflow that runs fern generate --docs whenever you push changes to your main branch, automatically rebuilding and publishing your documentation.

After setup, you have full ownership of this repository. Push changes to your main branch to trigger an automatic rebuild and publish of your docs, or manage settings through the Fern Dashboard.

Setup steps

Enter your organization name

Choose a unique identifier for your organization. This will be used in your docs URL and to identify your project in the Dashboard.

Upload your API spec (optional)

Upload an OpenAPI specification to generate API Reference documentation. You can skip this step if you don’t have a spec or want to add one later.

Configure your branding

Enter an existing website URL (like your marketing site or blog) so Fern can automatically match your brand style. Alternatively, pick a primary color and upload a logo manually.

Your site is live!

Fern publishes your documentation to a live URL you can visit immediately. Add your GitHub account as a collaborator to take ownership of the repository. From there, you can edit files, push changes, and open pull requests just like any other Git repo. Each push to the main branch triggers the GitHub Action to rebuild and publish your docs automatically. You can also manage your site settings in the Dashboard.

Next steps

Start writing content and customizing your site:

How Fern Docs work

Understand the content and deployment workflows powering your site.

Write your docs

Learn Markdown basics and use components to create rich documentation.

Configure your site

Set colors, typography, navigation, and more in your docs.yml file.

Monitoring builds

Your documentation rebuilds automatically whenever you push changes to your main branch. To check the status of a build, go to the Actions tab in your GitHub repository. Each workflow run shows whether the build succeeded, along with any errors or warnings.

Troubleshooting

Fern API key issues

If your documentation build fails with an authentication error, the FERN_TOKEN may not be set correctly. To resolve this:

Install the Fern CLI if you haven’t already:

$ npm install -g fern-api

Add yourself as a collaborator to the repository if needed, then clone it locally.

Run the following command from within your Fern project directory to generate a new API key:

$ fern token

This generates an API key scoped to your organization (as defined in fern.config.json).

Copy the API key and add it as a repository secret named FERN_TOKEN.
Go to the Actions tab in your repository and re-run the failed workflow.

API spec errors

If your build fails due to issues parsing your API specification, you can troubleshoot locally:

Clone your documentation repository locally if you haven’t already.

Install the Fern CLI:

$ npm install -g fern-api

Run the following command to see detailed validation errors with line numbers:
```
$ fern check --from-openapi
```
This command prints validation errors directly from your OpenAPI specification, including the line numbers where the errors originate.

Once you’ve resolved the errors in your API spec, commit and push the changes to trigger a new build.