Document folder-based navigation configuration

fern/docs.yml

@@ -312,6 +312,8 @@ redirects:
     destination: /learn/docs/configuration/navigation
   - source: /learn/docs/navigation/overview
     destination: /learn/docs/configuration/navigation
+  - source: /learn/docs/configuration/folder-based-navigation
+    destination: /learn/docs/configuration/navigation
   - source: /learn/docs/building-and-customizing-your-docs/versioning
     destination: /learn/docs/configuration/versions
   - source: /learn/docs/navigation/versions

fern/products/docs/pages/changelog/2025-11-05.mdx

@@ -0,0 +1,20 @@
+## Folder-based navigation
+
+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.
+
+```yaml docs.yml {6-10}
+navigation:
+  - section: Getting started
+    contents:
+      - page: Introduction
+        path: ./pages/intro.mdx
+      - folder: ./pages/guides
+        title: Guides # Display name for folder section
+        icon: fa-regular fa-book
+        collapsed: true
+        availability: beta # Optional badge to display in navigation
+```
+
+Subfolders become nested sections. Supported options: `title`, `slug`, `icon`, `collapsed`, `hidden`, `skip-slug`, `availability`.
+
+[Learn more about navigation configuration](/learn/docs/configuration/navigation).

fern/products/docs/pages/navigation/overview.mdx

@@ -3,12 +3,8 @@ title: Configure your site navigation
 description: Set up the navigation for your documentation site built with Fern Docs using the docs.yml file, including tabs, sections, pages, and more.
 ---
 
-## Use `docs.yml`
-
 Every Fern Docs website has a special configuration file called `docs.yml`. Use this file to configure the navigation for your documentation site. 
 
-### Example configuration
-
 Here's a complete example of a `docs.yml` file:
 
 <CodeBlock title="An example docs.yml">
@@ -20,8 +16,8 @@ navigation:
     contents:
       - page: Introduction
         path: ./intro.mdx
-      - page: Authentication
-        path: ./auth.mdx
+      - folder: ./auth # directory
+        title: Authentication
   - api: API Reference
 navbar-links:
   - type: secondary
@@ -33,59 +29,77 @@ navbar-links:
 ```
 </CodeBlock>
 
-## Sections, contents, and pages
+## Sections, contents, pages, and folders
 
-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`.
+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`.
 
-In `contents`, list your pages with names and corresponding file paths. The supported file types for pages are `.md` or `.mdx`.
+In `contents`, you can add individual pages, folders, or both:
 
-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.
+- `page` Manually list your pages with names and corresponding file paths.
+- `folder` Auto-discover pages from a directory and add them to your navigation.
 
-{/* <!-- vale off --> */}
-```yaml Example navigation config
+You can combine folder-based navigation with manually defined pages.
+
+<Info title="API Reference section">
+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.
+
+```yaml docs.yml {6}
 navigation:
   - section: Introduction
     contents:
       - page: My page
         path: ./pages/my-page.mdx
   - api: API Reference
 ```
-{/* <!-- vale on --> */}
-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:
-{/* <!-- vale off --> */}
-```yaml Example navigation config
+</Info>
+
+<AccordionGroup>
+<Accordion title="Add a page">
+
+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.
+
+```yaml docs.yml
 navigation:
   - section: Introduction
     contents:
       - page: My page
         path: ./pages/my-page.mdx
       - page: Another page
         path: ./pages/another-page.mdx
-  - api: API Reference
 ```
+</Accordion>
+<Accordion title="Add a folder">
 
-To add another section, add another `section` to the `navigation`. Example:
+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.
 
-```yaml Example navigation config with additional section
+```yaml docs.yml {4-5}
 navigation:
   - section: Introduction
     contents:
-      - page: My page
-        path: ./pages/my-page.mdx
-  - api: API Reference
-  - section: Help center
-    contents:
-      - page: Contact us
-        path: contact-us.mdx
+      - folder: ./pages/getting-started
+        title: Getting started # Optional, defaults to folder name
 ```
-{/* <!-- vale on --> */}
 
-### Hiding content
+For the pages in a folder, Fern automatically converts filenames to titles and URL slugs, creates nested sections from subdirectories, and sorts pages alphabetically.
+
+<Note title="Control page order">
+  Use frontmatter `position` to control page order. Pages with a `position` field are sorted numerically before alphabetically sorted pages.
+  ```jsx /pages/getting-started/quickstart.mdx
+    ---
+    title: Quickstart
+    position: 1
+    ---
+  ```
+</Note>
+</Accordion>
+</AccordionGroup>
+
+## Hiding content
 
-To hide a page or 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.
+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.
 
 {/* <!-- vale off --> */}
-```yaml Example navigation config with additional section {7, 10}
+```yaml docs.yml {7, 10, 12}
 navigation:
   - section: Introduction
     contents:
@@ -94,6 +108,9 @@ navigation:
       - page: Hidden page
         hidden: true
         path: ./pages/my-hidden-page.mdx
+      - folder: .pages/features
+        title: Hidden folder
+        hidden: true
   - section: Hidden sections
     hidden: true
     contents:
@@ -102,9 +119,9 @@ navigation:
 ```
 {/* <!-- vale on --> */}
 
-### Section and page availability
+## Availability
 
-You can set availability for individual pages or 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.
+Set availability for individual pages, sections, or folders. Pages inherit availability from their parent section or folder unless explicitly overridden.
 
 Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. 
 
@@ -115,19 +132,39 @@ navigation:
     contents:
       - page: Code examples # Inherits generally-available
         path: ./pages/code-examples.mdx
-      - page: CLI tools # Inherits generally-available
-        path: ./pages/cli-tools.mdx
+      - folder: ./pages/cli-tools # Inherits generally-available
+        title: CLI tools
       - page: Testing framework
         path: ./pages/testing-framework.mdx
         availability: beta # Overrides section-level availability
-      - page: Performance monitoring
-        path: ./pages/performance-monitoring.mdx
+      - folder: ./pages/performance-monitoring
+        title: Performance monitoring
         availability: in-development # Overrides section-level availability
 ```
 <Note>
-  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).
+  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).
 </Note>
 
+## Folder slugs
+
+Specify a custom URL slug for the folder section. If not provided, a slug will be generated from the folder name.
+
+```yaml docs.yml (4)
+navigation:
+  - folder: ./pages/guides
+    title: Guides
+    slug: user-guides
+```
+
+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.
+
+```yaml docs.yml {4}
+navigation:
+  - folder: ./pages/guides
+    title: Guides
+    skip-slug: true
+```
+
 ## Section overviews
 
 To add an overview page to a section, add a `path` property to the section.
@@ -177,17 +214,20 @@ navigation:
 ![Result of above docs.yml example](https://fern-image-hosting.s3.amazonaws.com/fern/nested-sections.png)
 </Frame>
 
-## Collapsed sections
+## Collapsed sections or folders
 
-You can set sections to be collapsed by default when the page loads by adding `collapsed: true` to a section.
+You can set sections or folders to be collapsed by default when the page loads by adding `collapsed: true`.
 This helps keep the navigation tidy when you have many sections or want to highlight the most important sections by keeping others collapsed.
 
-```yaml {7} Example config with collapsed section
+```yaml {8, 10} Example config with collapsed section
 navigation:
   - section: Getting started
     contents:
       - page: Introduction
         path: ./pages/intro.mdx
+      - folder: ./pages/features
+        title: Features
+        collapsed: true
   - section: Advanced topics
     collapsed: true
     contents:
@@ -199,20 +239,21 @@ navigation:
 
 ## Sidebar icons
 
-Add icons next to sections and pages using the `icon` key.
+Add icons next to sections, pages, and folders using the `icon` key.
 
 <Markdown src="/snippets/icons.mdx" />
 
 {/* <!-- vale off --> */}
-```yaml Example config with different icon files {3, 6, 9}
+```yaml Example config with different icon files {3, 6, 10-11, 14}
 navigation:
   - section: Home
     icon: fa-regular fa-home  # Font Awesome icon
     contents:
       - page: Introduction
         icon: ./assets/icons/intro-icon.svg  # Custom image file
         path: ./pages/intro.mdx
-      - page: Custom Features
+      - folder: .pages/features
+        title: Custom features
         icon: "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='currentColor'><path d='M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z'/></svg>"  # Inline SVG
         path: ./pages/custom.mdx
   - api: API Reference