Self-service setup
Self-service setup
Self-service setup
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.
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:
FERN_TOKEN in your repository’s GitHub secrets that authenticates the Fern CLI in your CI/CD workflows, scoped to your organization.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.
Choose a unique identifier for your organization. This will be used in your docs URL and to identify your project in the Dashboard.
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.
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.
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.
Start writing content and customizing your site:
Understand the content and deployment workflows powering your site.
Learn Markdown basics and use components to create rich documentation.
Set colors, typography, navigation, and more in your docs.yml file.
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.
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:
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:
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.
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:
Run the following command to see detailed validation errors with line numbers:
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.