> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Configuring slugs

> Customize URL paths in your Fern documentation site. Rename slugs for pages, sections, tabs, landing pages, and subheadings, or skip them entirely.

Fern automatically generates a URL slug for each navigation item and joins them into every page's full URL. You can [rename](#renaming-slugs) a slug, [skip](#skipping-slugs) a level, or [override](#override-with-a-frontmatter-slug) a page's path in its frontmatter.

## How slugs are generated

By default, Fern derives each navigation item's slug from its display name in `docs.yml`, lowercasing the name, replacing spaces with hyphens, and stripping special characters such as parentheses. Pages in [folder-based navigation](/learn/docs/configuration/navigation#add-a-folder) take their slugs from filenames instead.

| Navigation item | Slug derived from         | Example         | Auto-generated slug |
| --------------- | ------------------------- | --------------- | ------------------- |
| Product         | `display-name`            | `My Product`    | `my-product`        |
| Version         | `display-name`            | `v3 (Latest)`   | `v-3-latest`        |
| Tab             | `display-name`            | `API Reference` | `api-reference`     |
| Section         | `section` name            | `Key Concepts`  | `key-concepts`      |
| Folder          | Directory name or `title` | `api-guides`    | `api-guides`        |
| Page            | `page` name               | `Quick Start`   | `quick-start`       |

A page's full URL joins these slugs from the outermost scope inward — product, version, tab, section and folder, then page.

#### Example without tabs

**`docs.yml`**

```yaml docs.yml {5, 7}
instances:
  - url: plantstore.docs.buildwithfern.com
  
navigation:
  - section: Get Started
    contents: 
      - page: Welcome 
        path: ./docs/pages/welcome.mdx
```

In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/get-started/welcome`.

#### Example with tabs

**`docs.yml`**

```yaml docs.yml {5, 13, 15}
instances:
  - url: plantstore.docs.buildwithfern.com
  
tabs: 
  docs:
    display-name: Docs
  reference: 
    display-name: API Reference
  
navigation:
  - tab: docs
    layout: 
      - section: Get Started
        contents: 
          - page: Welcome 
            path: ./docs/pages/welcome.mdx
```

In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/docs/get-started/welcome`.

## Renaming slugs

Set the `slug` property in `docs.yml` or in a page's frontmatter to customize the URL path. Where you set it determines how much of the URL it replaces:

* **`docs.yml`**: replaces only that navigation item's own segment.
* **Page [frontmatter](#override-with-a-frontmatter-slug)**: replaces the page's entire section and folder hierarchy, and takes precedence over a `docs.yml` slug on the same page.
* **Product and version prefixes**: preserved in both cases.

Changing a slug updates the page's URL. Run [`fern check`](/learn/cli-api-reference/cli-reference/general-commands#fern-check) to detect pages that moved without a [redirect](/learn/docs/seo/redirects#catching-missing-redirects), so existing links don't break.

### Modify a tab slug

To modify the slug used for a tab, set the `slug` within the `tabs` object.

**`docs.yml`**

```yaml docs.yml {4}
tabs: 
  docs:
    display-name: Docs
    slug: guides
  reference: 
    display-name: API Reference
  
navigation:
  - tab: docs
    layout: 
      - section: Get Started
        contents: 
          - page: Welcome 
            path: ./docs/pages/welcome.mdx
```

In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/guides/get-started/welcome`.

### Modify a page or section slug

To modify the slug used for a page or section, set the `slug` within the `navigation` object.

**`docs.yml`**

```yaml docs.yml {3, 6}
navigation:
  - section: Get Started
    slug: start
    contents: 
      - page: Welcome 
        slug: intro
        path: ./docs/pages/get-started/welcome.mdx
```

In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/start/intro`.

### Modify a landing page's slug

To modify the slug used for a landing page, set the `slug` within the `landing-page` object.

**`docs.yml`**

```yaml title="docs.yml" {4}
landing-page: 
  page: Page Title
  path: path/to/landing-page.mdx
  slug: /welcome
```

### Rename subheading slugs

By default, deep links to subheadings are generated by appending a `#` and the subheading title (converted to `kebab-casing-convention`) onto the page URL.

**`docs.yml`**

```yaml docs.yml
navigation:
  - section: Get Started
    contents: 
      - page: Welcome 
        path: ./docs/pages/welcome.mdx
```

**`welcome.mdx`**

```jsx welcome.mdx
...

## Frequently Asked Questions 
...
```

The link to this section will be available at `plantstore.docs.buildwithfern.com/get-started/welcome#frequently-asked-questions`.

To rename the slug of a `##` or `###` subheading, add the desired slug:

**`welcome.mdx`**

```jsx welcome.mdx
## Frequently Asked Questions [#faqs]
```

The link to this section will now be available at `plantstore.docs.buildwithfern.com/get-started/welcome#faqs`.

### Override with a frontmatter slug

Use a frontmatter `slug` when a page needs a short, memorable URL independent of its sidebar position — a top-level quickstart, a campaign landing page, or a page that moved but must keep its old URL.

Given the [page and section slugs](#modify-a-page-or-section-slug) that place **Welcome** at `/start/intro`, adding a `slug` to the page's frontmatter replaces that entire hierarchy:

**`./docs/pages/get-started/welcome.mdx`**

```markdown title="./docs/pages/get-started/welcome.mdx"
---
slug: welcome
---
```

The page now resolves to `plantstore.docs.buildwithfern.com/welcome`, taking precedence over the `docs.yml` slugs. It still appears in the sidebar under "Get Started", but its URL no longer reflects that structure.

A frontmatter slug never escapes a [product](/learn/docs/configuration/navigation#add-a-product) or [version](/learn/docs/configuration/navigation#add-a-version) prefix. A **Quickstart** page inside the product `platform` with frontmatter `slug: quickstart` resolves to `/platform/quickstart` — not `/quickstart` — and in version `v2` of that product, `/platform/v2/quickstart`.

To move a page to the absolute root of your docs, place it outside any product or version in your navigation.

## Skipping slugs

To ignore a tab or section when generating the slug, simply indicate `skip-slug: true`.

#### Example without tabs

**`docs.yml`**

```yaml docs.yml {6}
instances:
  - url: plantstore.docs.buildwithfern.com
  
navigation:
  - section: Get Started
    skip-slug: true
    contents: 
      - page: Welcome 
        path: ./docs/pages/welcome.mdx
```

In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/welcome`.

#### Example with tabs

**`docs.yml`**

```yaml docs.yml {7, 15}
instances:
  - url: plantstore.docs.buildwithfern.com
  
tabs: 
  docs:
    display-name: Docs
    skip-slug: true
  reference: 
    display-name: API Reference
  
navigation:
  - tab: docs
    layout: 
      - section: Get Started
        skip-slug: true
        contents: 
          - page: Welcome 
            path: ./docs/pages/welcome.mdx
```

In the example above, the **Welcome** page would be hosted at `plantstore.docs.buildwithfern.com/welcome`.

> Customize URL paths in your Fern documentation site. Rename slugs for pages, sections, tabs, landing pages, and subheadings, or skip them entirely.