Fern Docs Quickstart with Fern Definition

Create beautiful documentation in under 5 minutes, using the Fern Definition format to define your API.

Here's an example.

• Node 18 or higher
• A GitHub account

1. Click on the Use this template button. You must be logged into GitHub.
2. Choose the option to create a new repository. Name it fern-docs.

Clone your newly created repository locally and open it in your favorite code editor, such as Visual Studio Code.

The fern/ folder in your repository contains these files and folders:

├─ definition/
  ├─ api.yml
  ├─ pet.yml
  ├─ store.yml
  └─ user.yml
├─ docs/
  ├─ assets/
    ├─ favicon.png
    ├─ logo_dark_mode.png
    └─ logo_light_mode.png
  └─ pages/
    ├─ sdks.mdx
    └─ welcome.mdx
    ├─ docs.yml
├─ fern.config.json
└─ generators.yml

The definition/ folder contains Fern Definition files for a sample API called Swagger Petstore. Fern uses these files to generate the API Reference section of your docs site.

The files inside the pages/ folder are used to generate other documentation pages, such as a Welcome page. The docs.yml file sets up site navigation and custom styles.

In the repository that you cloned locally, open the fern.config.json file, which looks like this:

{
  "organization": "Petstore",
  "version": "0.x.x"
}

Replace "Petstore" with your own organization name within the quotes. Spaces are permitted. Leave the version number unchanged.

Open the docs.yml file and locate the url, which looks like this:

instances:
  - url: petstore-ferndef.docs.buildwithfern.com

Replace petstore-ferndef with your own organization's name. Use only alphanumeric characters, hyphens, and underscores. Do not use spaces, and leave the rest of the URL (.docs.buildwithfern.com) unchanged.

Install the Fern CLI tool globally by running:

npm install -g fern-api

When prompted, log into and connect your GitHub account.

Run the following command:

fern generate --docs

Once the documentation is generated, Fern displays the URL where you can view the published documentation. For example:

┌─
│ ✓  petstore-ferndef.docs.buildwithfern.com
└─

Instead of petstore-ferndef, you should see the organization name that you added to docs.yml in Step 3.

You must run fern generate --docs after any modifications to re-generate and publish your documentation site.

To preview updates to your documentation before publishing changes, run fern generate --docs --preview.

To modify the API Reference:

• Update or replace the Fern Definition files in the definition/ folder. See our documentation on how to define your API with Fern Definition.

To modify the other docs pages or add new pages:

• Update the files located in the docs/pages/ folder, such as welcome.mdx. See our documentation on how to write content with Markdown and MDX.

To configure site navigation, styles, and see other configuration options:

• See Fern Docs Configuration Overview.

To learn about Fern's built-in component library you can use in Markdown:

• See the Component Library.

If you wish to use a custom subdomain like https://docs.YOUR_ORGANIZATION.com or a subpath like https://YOUR_ORGANIZATION.com/docs, you can subscribe to the Starter plan. Once subscribed, update docs.yml with the custom domain configuration, replacing YOUR_ORGANIZATION with your own.

- url: YOUR_ORGANIZATION.docs.buildwithfern.com
  custom-domain: docs.YOUR_ORGANIZATION.com

Good luck creating beautiful and functional documentation! 🌿

Need help? Email us at ([email protected])[mailto:[email protected]] or join our Discord community.

Your docs can look this good:

• Flatfile's API Reference
• Sugeragent's Docs
• Credal's Docs