Your docs can look this good:
- Click on the "Use this template" button. You must be logged into GitHub.
- Create a new repository. Name it anything you like;
docs
is a common naming choice.
Clone your newly created repository and open it in your favorite integrated development environment (IDE) or code editor.
The files and folders discussed in the following steps will be inside a fern
folder in your repository.
In the fern.config.json
file, replace the placeholder organization name with your actual organization name. For example:
{
"organization": "YourOrganization",
"version": "0.16.25"
}
In the docs.yml
file, update the docs URL to match your organization's naming convention. For example:
instances:
- url: your-organization.docs.buildwithfern.com
Install the Fern CLI globally by running:
npm install -g fern-api
As this is a global command, you can run it from any location. The CLI commands in the following steps must be run from within your repository.
If you will be using Fern Definitions to describe your API, skip to Step 6.
If you will be using the OpenAPI Specification (OAS), follow these steps:
- Delete the
definition
folder. - Run:
fern init --openapi URL_OR_PATH_TO_YOUR_OPENAPI_SPEC
Examples:
fern init --openapi https://petstore3.swagger.io/api/v3/openapi.json
fern init --openapi ../apis/openapi.yml
You can use a URL to an OAS file online, or you can use a local path. The file must be formatted as JSON or YAML.
Confirm that you see a new folder named openapi
and that it contains the OAS file you specified, in YAML format.
Generate and publish your documentation with the following command:
fern generate --docs
You will be prompted to log in and connect your GitHub account.
Once the documentation is generated, you will receive a URL where your documentation is published. For example:
┌─
│ ✓ your-organization.docs.buildwithfern.com
└─
To update your API definitions:
- For Fern Definitions, update the files in the
definition
folder. - For OpenAPI Specification, update the file in the
openapi
folder. YAML and JSON file formats are supported.
Next, modify the markdown pages located in the docs/pages
folder, such as the Welcome page.
Further tailor your documentation to match your brand by adjusting settings in the docs.yml
file.
To re-publish the updates to your documentation, run fern generate --docs
again.
To preview updates to your documentation before publishing changes, run fern generate --docs --preview
.
Fern has a built-in component library for you to use. Explore the components.
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:
- url: your-organization.docs.buildwithfern.com
custom-domain: docs.your-organization.com
For advanced documentation features and options, view the full configuration docs.
Good luck creating beautiful and functional documentation! 🌿