Work in progress. This repository contains the Unleash documentation built with Fern.
- Node.js 20+
- Fern CLI (installed globally):
npm install -g fern-apiStart the local development server:
npm run devThis will:
- Fetch the latest OpenAPI spec from the hosted Unleash instance
- Split it into three separate API definitions (see API Structure)
- Save them to
fern/apis/*/openapi.json - Build the custom footer component (see Custom Footer)
- Start the dev server at
http://localhost:3000
If you don't need to fetch the latest OpenAPI spec or rebuild the footer, you can run the Fern dev server directly for faster startup:
fern docs devIf you need to run commands separately:
# Fetch OpenAPI spec only
npm run fetch
# Build footer only
npm run build:footer
# Start dev server without fetching or building footer
fern docs dev
# Build docs (with automatic fetch and footer build)
npm run buildThe Unleash API documentation is split into three separate API definitions to enable better organization and URL structure:
- Client API (
fern/apis/client-api/): Contains only endpoints with the "Client" tag - Frontend API (
fern/apis/frontend-api/): Contains only endpoints with the "Frontend API" tag - Admin API (
fern/apis/admin-api/): Contains all remaining endpoints (excludes Client and Frontend API tags)
The scripts/fetch-openapi.mjs script:
- Fetches the complete OpenAPI spec from
https://us.app.unleash-hosted.com/ushosted/docs/openapi.json - Filters the spec by OpenAPI tags to create three separate files:
filterOpenApiSpec(data, ['Client'])→fern/apis/client-api/openapi.jsonfilterOpenApiSpec(data, ['Frontend API'])→fern/apis/frontend-api/openapi.jsonfilterOpenApiSpec(data, null, ['Client', 'Frontend API'])→fern/apis/admin-api/openapi.json
- Strips image markdown (
![Unleash Enterprise]and![Beta]) that doesn't work in Fern - Replaces server URL with
https://app.unleash-instance.example.com
We build a custom footer built with React. The footer source code is in footer/src/ and is compiled to fern/footer-dist/.
Fern supports custom JavaScript and CSS that can replace or enhance the default components. The footer is built as a React component using Vite:
- Source:
footer/src/FernFooter.tsxandfooter/src/main.css - Output:
fern/footer-dist/output.jsandfern/footer-dist/output.css - Config: Referenced in
fern/docs.ymlundercssandjssections
The footer is built automatically when running npm run dev or npm run build. To build it manually:
npm run build:footerOr directly:
cd footer && npm install && npm run buildCheck for errors and warnings (does not fail on broken links):
fern check --warnings --broken-linksCheck with strict mode (fails on broken links):
fern check --strict-broken-linksGenerate a preview URL:
fern generate --docs --preview