# Markdown basics

> Use Markdown and MDX to add content to your Fern documentation site, including headers, components, and links.

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

<Note title="Terminology">
  Throughout this documentation, "Markdown" refers to both Markdown and MDX. [MDX](https://mdxjs.com/) is a version of Markdown, extended to allow the use of JSX components.
</Note>

## 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](https://www.markdownguide.org/getting-started/).

Place your pages inside your `fern/` folder and link to them from your [navigation settings](/learn/docs/building-your-docs/navigation) in the `docs.yml` file.

In the example below, the MDX files are inside a folder named `pages/`.

<CodeBlock title="Example folder structure">
  ```bash
  fern/
  ├─ fern.config.json
  ├─ docs.yml
  └─ pages/
    ├─ welcome.mdx
    └─ quickstart.mdx
  ```
</CodeBlock>

<CodeBlock title="docs.yml">
  ```yml
  navigation:
    - section: Overview
      contents:
        - page: Welcome
          path: ./pages/welcome.mdx
        - page: Quickstart
          path: ./pages/quickstart.mdx
  ```
</CodeBlock>

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

```yml
          - page: Write Markdown content
            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>`.

## Links in Markdown

### Link format

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:

<CodeBlock title="Relative link example">
  ```mdx
  Read the [Introduction](/learn/overview/introduction).
  ```
</CodeBlock>

### Link target

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

```yaml title="docs.yml" {8}
navigation:
  - section: Home
    contents:
      - page: Introduction
        path: ./intro.mdx
      - link: Our YouTube channel
        href: https://www.youtube.com/
        target: _blank
```

[Learn more](/learn/docs/configuration/navigation) about links and other navigational elements.

## Tables

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

```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data     | Data     |
| Row 2    | Data     | Data     |
```

For more advanced table features like sticky headers for longer datasets, see the [Table component](/learn/docs/writing-content/components/tables) documentation.

## Fern components

Fern has a built-in component library you can use in Markdown. [Explore the components.](/learn/docs/content/components/overview)