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-full.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 token: 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.

You can use the Fern Dashboard to manage your GitHub repository connection, organization members, domains, and CLI version.

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. You can also add your GitHub account as a collaborator to push changes and manage the repository, or head to the Dashboard to manage your site settings.

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 token 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 token:

$ fern token

This generates a token scoped to your organization (as defined in fern.config.json).

Copy the token 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.