Learn how to use Markdown and MDX to add content to your documentation, including headers, components, and links.
Throughout this documentation, “Markdown” refers to both Markdown and MDX. MDX is a version of Markdown, extended to allow the use of JSX components.
Add pages manually to your documentation by creating Markdown (.md) or MDX (.mdx) files. New to Markdown? See Markdown Guide: Getting started.
Place your pages inside your fern/ folder and link to them from your navigation settings in the docs.yml file.
In the example below, the MDX files are inside a folder named pages/.
Fern automatically generates the <h1> page header for each page using the page value in docs.yml. For example, the following entry sets the page header for this page to “Markdown basics”:
Because the <h1> is generated automatically, you should begin your page content with <h2> headers instead of <h1>.
To link to another page on your docs site, write the destination’s published site path, starting with a /. Fern builds this path from the slugs in your docs.yml and product YAML files, not from the file’s location on disk. To link to a heading on another page, append #anchor to the path.
File-relative paths like ./ and ../ aren’t supported for inter-page links — use the published site path instead. (File-relative paths are still correct for images and other media and for path: references inside YAML config.)
In versioned docs, the same path lands on a different version depending on whether you write the unversioned form (default version) or the versioned form (e.g. /learn/docs/v2/getting-started). For inline version-specific content within a single page, use <If versions=…> or <Versions>.
Fern provides two ways to catch broken links. The broken-links rule — run by fern check, including during fern docs dev — validates each internal link against the navigation tree built from your local YAML. To check links on a published site, use fern docs link check or the Fern Dashboard.
Use api: link syntax to link to API endpoints or API Reference sections in any Markdown content. Fern resolves these links at build time, so you don’t need to hardcode slugs.
Use api:METHOD/path, where METHOD is an HTTP method (GET, POST, PUT, PATCH, DELETE) and /path is the endpoint path from your API definition. Path parameters use curly braces, such as api:GET/v2/payments/{paymentId}.
For projects with multiple APIs, prefix with the API name: api:API-NAME:METHOD/path.
Use api:apiName, where apiName matches the API name in your generators.yml file. This is useful when your project has multiple APIs and you want to link to the root landing page of a specific API Reference.
Control where links open with the target property. Available for product, tab, navbar, and page links. For typical documentation sites, links can open in the same tab (_self) or new tab (_blank). For documentation embedded in a dashboard or iframe, links can open in the parent frame (_parent) or topmost frame (_top).
Learn more about links and other navigational elements.
Create tables using standard Markdown syntax with pipes (|) and hyphens (-):
For more advanced table features like sticky headers for longer datasets, see the Table component documentation.
Fern has a built-in component library you can use in Markdown. Explore the components.