You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Auto-generate navigation from a folder of markdown files using the new `folder` configuration. Instead of manually listing each page in `docs.yml`, point to a folder. Fern discovers all `.md` and `.mdx` files and adds them to the navigation.
4
+
5
+
```yaml docs.yml {6-10}
6
+
navigation:
7
+
- section: Getting started
8
+
contents:
9
+
- page: Introduction
10
+
path: ./pages/intro.mdx
11
+
- folder: ./pages/guides
12
+
title: Guides # Display name for folder section
13
+
icon: fa-regular fa-book
14
+
collapsed: true
15
+
availability: beta # Optional badge to display in navigation
Copy file name to clipboardExpand all lines: fern/products/docs/pages/navigation/overview.mdx
+84-43Lines changed: 84 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,12 +3,8 @@ title: Configure your site navigation
3
3
description: Set up the navigation for your documentation site built with Fern Docs using the docs.yml file, including tabs, sections, pages, and more.
4
4
---
5
5
6
-
## Use `docs.yml`
7
-
8
6
Every Fern Docs website has a special configuration file called `docs.yml`. Use this file to configure the navigation for your documentation site.
9
7
10
-
### Example configuration
11
-
12
8
Here's a complete example of a `docs.yml` file:
13
9
14
10
<CodeBlocktitle="An example docs.yml">
@@ -20,8 +16,8 @@ navigation:
20
16
contents:
21
17
- page: Introduction
22
18
path: ./intro.mdx
23
-
- page: Authentication
24
-
path: ./auth.mdx
19
+
- folder: ./auth # directory
20
+
title: Authentication
25
21
- api: API Reference
26
22
navbar-links:
27
23
- type: secondary
@@ -33,59 +29,77 @@ navbar-links:
33
29
```
34
30
</CodeBlock>
35
31
36
-
## Sections, contents, and pages
32
+
## Sections, contents, pages, and folders
37
33
38
-
The navigation organizes your documentation in the left-side nav bar. You can create sections for grouping related content. Each `section` has a name and a list of `contents`. The sections appear in the left-side nav bar in the order listed in `docs.yml`.
34
+
Sections organize your documentation in the left-side nav bar. Each `section` has a name and a list of `contents`. Sections appear in the order listed in `docs.yml`.
39
35
40
-
In `contents`, list your pages with names and corresponding file paths. The supported file types for pages are `.md` or `.mdx`.
36
+
In `contents`, you can add individual pages, folders, or both:
41
37
42
-
A basic navigation configuration with two sections is shown below. The first section is called `Introduction` and contains a single page called `My Page`. The second section is called **API Reference**. This is a special type of section that's automatically generated by Fern, and you don't need to add any pages to it by hand. For more information, see the [Generate API Reference](/learn/docs/api-references/generate-api-ref) page.
38
+
- `page`Manually list your pages with names and corresponding file paths.
39
+
- `folder`Auto-discover pages from a directory and add them to your navigation.
43
40
44
-
{/* <!-- vale off --> */}
45
-
```yaml Example navigation config
41
+
You can combine folder-based navigation with manually defined pages.
42
+
43
+
<Info title="API Reference section">
44
+
Use the special `api` key to create an automatically generated API Reference section. You don't need to add any pages to it manually. For more information, see the [Generate API Reference](/learn/docs/api-references/generate-api-ref) page.
45
+
46
+
```yaml docs.yml {6}
46
47
navigation:
47
48
- section: Introduction
48
49
contents:
49
50
- page: My page
50
51
path: ./pages/my-page.mdx
51
52
- api: API Reference
52
53
```
53
-
{/* <!-- vale on --> */}
54
-
If you want to add another page to an existing section, create an `.md` or `.mdx` file. Then in `docs.yml`, create a new `page` in the `contents` list for that section, providing the path to the `.md` or `.mdx` file you created. Example:
55
-
{/* <!-- vale off --> */}
56
-
```yaml Example navigation config
54
+
</Info>
55
+
56
+
<AccordionGroup>
57
+
<Accordion title="Add a page">
58
+
59
+
Create an `.md` or `.mdx` file. Then in `docs.yml`, add a new `page` to the `contents` list, providing the path to the file you created.
60
+
61
+
```yaml docs.yml
57
62
navigation:
58
63
- section: Introduction
59
64
contents:
60
65
- page: My page
61
66
path: ./pages/my-page.mdx
62
67
- page: Another page
63
68
path: ./pages/another-page.mdx
64
-
- api: API Reference
65
69
```
70
+
</Accordion>
71
+
<Accordion title="Add a folder">
66
72
67
-
To add another section, add another `section` to the `navigation`. Example:
73
+
Create a directory with one or more `.md` or `.mdx` files. Add a `folder` key to your navigation configuration with the relative path to the directory you just created. Fern discovers all files in the directory and adds them to the navigation.
68
74
69
-
```yaml Example navigation config with additional section
75
+
```yaml docs.yml {4-5}
70
76
navigation:
71
77
- section: Introduction
72
78
contents:
73
-
- page: My page
74
-
path: ./pages/my-page.mdx
75
-
- api: API Reference
76
-
- section: Help center
77
-
contents:
78
-
- page: Contact us
79
-
path: contact-us.mdx
79
+
- folder: ./pages/getting-started
80
+
title: Getting started # Optional, defaults to folder name
80
81
```
81
-
{/* <!-- vale on --> */}
82
82
83
-
### Hiding content
83
+
For the pages in a folder, Fern automatically converts filenames to titles and URL slugs, creates nested sections from subdirectories, and sorts pages alphabetically.
84
+
85
+
<Note title="Control page order">
86
+
Use frontmatter `position` to control page order. Pages with a `position` field are sorted numerically before alphabetically sorted pages.
87
+
```jsx /pages/getting-started/quickstart.mdx
88
+
---
89
+
title: Quickstart
90
+
position: 1
91
+
---
92
+
```
93
+
</Note>
94
+
</Accordion>
95
+
</AccordionGroup>
96
+
97
+
## Hiding content
84
98
85
-
To hide a pageor an entire section of your docs, add `hidden: true`. A hidden page or section will still be discoverable using the exact URL, but it will be excluded from search and won't be indexed.
99
+
To hide a page, folder, or section, add `hidden: true`. Hidden content (including all pages within a folder) is still accessible via direct URL but is excluded from search and won't be indexed.
86
100
87
101
{/* <!-- vale off --> */}
88
-
```yaml Example navigation config with additional section {7, 10}
102
+
```yaml docs.yml {7, 10, 12}
89
103
navigation:
90
104
- section: Introduction
91
105
contents:
@@ -94,6 +108,9 @@ navigation:
94
108
- page: Hidden page
95
109
hidden: true
96
110
path: ./pages/my-hidden-page.mdx
111
+
- folder: .pages/features
112
+
title: Hidden folder
113
+
hidden: true
97
114
- section: Hidden sections
98
115
hidden: true
99
116
contents:
@@ -102,9 +119,9 @@ navigation:
102
119
```
103
120
{/* <!-- vale on --> */}
104
121
105
-
### Section and page availability
122
+
## Availability
106
123
107
-
You can set availability for individual pagesor entire sections. When you set availability for a section, all pages within that section inherit the same availability unless explicitly overridden at the page level.
124
+
Set availability for individual pages, sections, or folders. Pages inherit availability from their parent section or folder unless explicitly overridden.
108
125
109
126
Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`.
If you have different versions of your docs, section and page availability should be set in [the `.yml` files that define the navigational structure for each version](/learn/docs/configuration/versions#define-your-versions).
145
+
If you have different versions of your docs, section, folder, and page availability should be set in [the `.yml` files that define the navigational structure for each version](/learn/docs/configuration/versions#define-your-versions).
129
146
</Note>
130
147
148
+
## Folder slugs
149
+
150
+
Specify a custom URL slug for the folder section. If not provided, a slug will be generated from the folder name.
151
+
152
+
```yaml docs.yml (4)
153
+
navigation:
154
+
- folder: ./pages/guides
155
+
title: Guides
156
+
slug: user-guides
157
+
```
158
+
159
+
Skip adding the folder's slug to the URL path. This is useful when you want the pages to appear at the parent level in the URL structure.
160
+
161
+
```yaml docs.yml {4}
162
+
navigation:
163
+
- folder: ./pages/guides
164
+
title: Guides
165
+
skip-slug: true
166
+
```
167
+
131
168
## Section overviews
132
169
133
170
To add an overview page to a section, add a `path` property to the section.
@@ -177,17 +214,20 @@ navigation:
177
214
178
215
</Frame>
179
216
180
-
## Collapsed sections
217
+
## Collapsed sections or folders
181
218
182
-
You can set sections to be collapsed by default when the page loads by adding `collapsed: true` to a section.
219
+
You can set sections or folders to be collapsed by default when the page loads by adding `collapsed: true`.
183
220
This helps keep the navigation tidy when you have many sections or want to highlight the most important sections by keeping others collapsed.
184
221
185
-
```yaml {7} Example config with collapsed section
222
+
```yaml {8, 10} Example config with collapsed section
186
223
navigation:
187
224
- section: Getting started
188
225
contents:
189
226
- page: Introduction
190
227
path: ./pages/intro.mdx
228
+
- folder: ./pages/features
229
+
title: Features
230
+
collapsed: true
191
231
- section: Advanced topics
192
232
collapsed: true
193
233
contents:
@@ -199,20 +239,21 @@ navigation:
199
239
200
240
## Sidebar icons
201
241
202
-
Add icons next to sectionsand pages using the `icon` key.
242
+
Add icons next to sections, pages, and folders using the `icon` key.
203
243
204
244
<Markdown src="/snippets/icons.mdx" />
205
245
206
246
{/* <!-- vale off --> */}
207
-
```yaml Example config with different icon files {3, 6, 9}
247
+
```yaml Example config with different icon files {3, 6, 10-11, 14}
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?v=4&size=40){kind=avatar}
0 commit comments