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 from docs.yml. For example, here’s the docs.yml entry that maps the page you are reading now:

1          - page: Write Markdown content
2            path: ./docs/pages/fern-docs/content/write-markdown.mdx

The value for page is used as the content of the top <h1> element of this page. Thus, when adding content to your Markdown pages, begin with <h2> instead of <h1>.

Use a / character to begin a relative URL to another page on your docs site. This routes to the url defined in your docs.yml file, such as example-docs.buildwithfern.com. For example, if you want to link to https://example-docs.buildwithfern.com/overview/introduction, you can write the link in Markdown as follows:

Relative link example
1Read the [Introduction](/learn/overview/introduction).

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.