Writing content

Markdown basics

View as Markdown

Learn how to use Markdown and MDX to add content to your documentation, including headers, components, and links.

Terminology

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 Markdown or MDX pages

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/.

Example folder structure
$fern/
$├─ fern.config.json
$├─ docs.yml
$└─ pages/
$  ├─ welcome.mdx
$  └─ quickstart.mdx
docs.yml
1navigation:
2  - section: Overview
3    contents:
4      - page: Welcome
5        path: ./pages/welcome.mdx
6      - page: Quickstart
7        path: ./pages/quickstart.mdx

Page header

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”:

docs.yml
1- page: Markdown basics
2  path: ./pages/component-library/writing-content/markdown-basics.mdx

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.)

Internal link example
1Learn about [how Fern SDKs work](/learn/sdks/overview/how-it-works).
2
3Configure [sidebar icons](/learn/docs/configuration/navigation#sidebar-icons) to add visual cues to your navigation.

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>.

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. It does not crawl your deployed site or follow external URLs. To check links on a published site, use 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.

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).

docs.yml
1navigation:
2  - section: Home
3    contents:
4      - page: Introduction
5        path: ./intro.mdx
6      - link: Our YouTube channel
7        href: https://www.youtube.com/
8        target: _blank

Learn more about links and other navigational elements.

Tables

Create tables using standard Markdown syntax with pipes (|) and hyphens (-):

1| Column 1 | Column 2 | Column 3 |
2|----------|----------|----------|
3| Row 1    | Data     | Data     |
4| Row 2    | Data     | Data     |

For more advanced table features like sticky headers for longer datasets, see the Table component documentation.

Fern components

Fern has a built-in component library you can use in Markdown. Explore the components.