Customizing slugs within your site

By default, Fern generates the slug of a page based on the navigation structure in the docs.yml file.

1
instances:
2
  - url: plantstore.docs.buildwithfern.com
3
  
4
navigation:
5
  - section: Get Started
6
    contents: 
7
      - page: Welcome 
8
        path: ./docs/pages/welcome.mdx

1
instances:
2
  - url: plantstore.docs.buildwithfern.com
3
  
4
tabs: 
5
  docs:
6
    display-name: Docs
7
  reference: 
8
    display-name: API Reference
9
  
10
navigation:
11
  - tab: docs
12
    layout: 
13
      - section: Get Started
14
        contents: 
15
          - page: Welcome 
16
            path: ./docs/pages/welcome.mdx

Renaming slugs

Modify a page or section slug

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

1
navigation:
2
  - section: Get Started
3
    slug: start
4
    contents: 
5
      - page: Welcome 
6
        slug: intro
7
        path: ./docs/pages/welcome.mdx

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

Modify a tab slug

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

1
tabs: 
2
  docs:
3
    display-name: Docs
4
    slug: guides
5
  reference: 
6
    display-name: API Reference
7
  
8
navigation:
9
  - tab: docs
10
    layout: 
11
      - section: Get Started
12
        contents: 
13
          - page: Welcome 
14
            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 landing page’s slug

To modify the slug used for a tab, you can set the slug within the landing-page object.

1
landing-page: 
2
  page: Page Title
3
  path: path/to/landing-page.mdx
4
  slug: /welcome

Override a page’s slug

You can set the exact slug of a page within its frontmatter. You can read more about the frontmatter configuration here.

1
navigation:
2
  - section: Get Started
3
    slug: start
4
    contents: 
5
      - page: Quick Start 
6
        path: ./docs/pages/quick-start.mdx

You can set the slug in the frontmatter of ./docs/pages/quick-start.mdx to start-up:

1
---
2
slug: start-up
3
---

The page then becomes available at plantstore.docs.buildwithfern.com/start-up.

Renaming slugs for subheadings

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

1
navigation:
2
  - section: Get Started
3
    contents: 
4
      - page: Welcome 
5
        path: ./docs/pages/welcome.mdx

1
...
2
3
## Frequently Asked Questions 
4
...

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

To rename the slug of the subheading, add the desired slug

1
## Frequently Asked Questions [#faqs]

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

Skipping slugs

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

1
instances:
2
  - url: plantstore.docs.buildwithfern.com
3
  
4
navigation:
5
  - section: Get Started
6
    skip-slug: true
7
    contents: 
8
      - page: Welcome 
9
        path: ./docs/pages/welcome.mdx

1
instances:
2
  - url: plantstore.docs.buildwithfern.com
3
  
4
tabs: 
5
  docs:
6
    display-name: Docs
7
    skip-slug: true
8
  reference: 
9
    display-name: API Reference
10
  
11
navigation:
12
  - tab: docs
13
    layout: 
14
      - section: Get Started
15
        skip-slug: true
16
        contents: 
17
          - page: Welcome 
18
            path: ./docs/pages/welcome.mdx