Write docs content using Markdown

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.

NOTE: Throughout our documentation, we refer to both Markdown and MDX as Markdown. MDX is a version of Markdown, extended to allow the use of JSX components.

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

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

Fern components

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

When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab.

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

Images

You can use locally stored images or URLs to include images in your Markdown pages. Use either Markdown syntax or the <img> HTML tag to insert the image.

1![Alt text](./path/to/image.png "Optional title")

Common image attributes:

AttributeDescription
srcURL or path to the image file
altAlternative text for accessibility
titleTooltip text shown on hover
width and heightDimensions of the image in pixels

For more details about the HTML image element and its attributes, see the MDN documentation on the img element.

Embedding local assets

You can embed local assets in your Markdown pages using the <embed> component. This is useful for displaying PDFs, images, videos, OpenAPI files, and other assets into your docs.

For example, to embed a video, use the following Markdown:

1<embed src="./path/to/asset.mp4" type="video/mp4" />

Embedding videos

You can embed videos in your documentation using the HTML <video> tag. This gives you control over video playback settings like autoplay, looping, and muting.

1<video
2 src="path/to/your/video.mp4"
3 width="854"
4 height="480"
5 autoplay
6 loop
7 playsinline
8 muted
9>
10</video>

You can also wrap the video in a container div for additional styling:

1<div class="card-video">
2 <video
3 src="path/to/your/video.mp4"
4 width="854"
5 height="480"
6 autoplay
7 loop
8 playsinline
9 muted
10 >
11 </video>
12</div>

Common video attributes:

AttributeDescription
srcURL or path to the video file
width and heightDimensions of the video player
autoplayVideo starts playing automatically
loopVideo repeats when finished
playsinlineVideo plays inline on mobile devices instead of fullscreen
mutedVideo plays without sound
controlsShows video player controls (play/pause, volume, etc.)

For more details about the HTML video element and its attributes, see the MDN documentation on the video element.

LaTeX

Fern supports LaTeX math equations. To use LaTeX, wrap your inline math equations in $. For example, $(x^2 + y^2 = z^2)$ will render x2+y2=z2x^2 + y^2 = z^2.

For display math equations, wrap the equation in $$. For example:

1$$
2% \f is defined as #1f(#2) using the macro
3\f\relax{x} = \int_{-\infty}^\infty
4 \f\hat\xi\,e^{2 \pi i \xi x}
5 \,d\xi
6$$
\fx=\fξ^e2πiξxdξ% \f is defined as #1f(#2) using the macro \f\relax{x} = \int_{-\infty}^\infty \f\hat\xi\,e^{2 \pi i \xi x} \,d\xi

Diagrams

Fern supports creating diagrams within your Markdown using Mermaid. Mermaid offers a variety of diagrams, including flowcharts, entity-relationship models, and Gantt charts. To include a Mermaid diagram in your Markdown file, create a codeblock marked with mermaid.

1```mermaid
2erDiagram
3 CUSTOMER ||--o{ PLANT-ORDER : places
4 PLANT-ORDER ||--|{ PLANT-ID : contains
5 CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
6```
Built with