Document folder-based navigation configuration

fern/products/docs/docs.yml

@@ -19,6 +19,8 @@ navigation:
         path: ./pages/customization/what-is-docs-yml.mdx
       - page: Navigation
         path: ./pages/navigation/overview.mdx
+      - page: Folder-based navigation
+        path: ./pages/navigation/folder-based-navigation.mdx
       - page: Tabs and tab variants
         path: ./pages/navigation/tabs.mdx
         slug: tabs

fern/products/docs/pages/navigation/folder-based-navigation.mdx

@@ -0,0 +1,259 @@
+---
+title: Folder-based navigation
+description: Automatically generate navigation from a folder of markdown files in your Fern Docs site.
+---
+
+The folder configuration allows you to automatically generate navigation from a folder of markdown files. Instead of manually listing each page in your `docs.yml` file, you can point to a folder and Fern will automatically discover and add all markdown files to your navigation.
+
+This feature is useful when you have many pages in a section and want to avoid manually maintaining the navigation structure, or when you want to quickly add multiple pages without updating the configuration file.
+
+## Basic usage
+
+To use folder-based navigation, add a `folder` key to your navigation configuration with the relative path to a folder containing markdown files:
+
+```yaml docs.yml
+navigation:
+  - section: Getting started
+    contents:
+      - page: Introduction
+        path: ./pages/intro.mdx
+      - folder: ./pages/guides
+        title: Guides
+```
+
+In this example, Fern will automatically discover all markdown files (`.md` and `.mdx`) in the `./pages/guides` folder and add them to the navigation under a section titled "Guides".
+
+## How it works
+
+When you use the `folder` configuration, Fern:
+
+1. Scans the specified folder for all markdown files (`.md` and `.mdx`)
+2. Automatically generates page titles from filenames (e.g., `getting-started.mdx` becomes "Getting Started")
+3. Generates URL slugs from filenames (e.g., `getting-started.mdx` becomes `getting-started`)
+4. Sorts pages and sections alphabetically by title
+5. Creates nested sections for subdirectories
+
+### Filename to title conversion
+
+Fern converts filenames to human-readable titles using the following rules:
+
+- Removes file extensions (`.md` or `.mdx`)
+- Replaces hyphens and underscores with spaces
+- Capitalizes the first letter of each word
+
+Examples:
+- `getting-started.mdx` → "Getting Started"
+- `api_reference.md` → "Api Reference"
+- `quickstart.mdx` → "Quickstart"
+
+### Filename to slug conversion
+
+Fern converts filenames to URL slugs using the following rules:
+
+- Removes file extensions (`.md` or `.mdx`)
+- Converts to lowercase
+- Replaces spaces with hyphens
+- Removes special characters
+
+Examples:
+- `Getting Started.mdx` → `getting-started`
+- `API Reference.md` → `api-reference`
+- `Quick Start!.mdx` → `quick-start`
+
+## Nested folders
+
+Fern automatically creates nested sections for subdirectories within your folder. Each subdirectory becomes a collapsible section in the navigation.
+
+For example, with this folder structure:
+
+```
+pages/
+  guides/
+    getting-started.mdx
+    advanced/
+      custom-code.mdx
+      webhooks.mdx
+    integrations/
+      slack.mdx
+      github.mdx
+```
+
+And this configuration:
+
+```yaml docs.yml
+navigation:
+  - folder: ./pages/guides
+    title: Guides
+```
+
+Fern will generate this navigation structure:
+
+- Guides
+  - Getting Started
+  - Advanced
+    - Custom Code
+    - Webhooks
+  - Integrations
+    - Slack
+    - Github
+
+## Configuration options
+
+The `folder` configuration supports several optional properties to customize the generated navigation:
+
+### Title
+
+Specify a custom title for the folder section. If not provided, the folder name will be used.
+
+```yaml docs.yml
+navigation:
+  - folder: ./pages/tech-ref
+    title: Technical Reference
+```
+
+### Slug
+
+Specify a custom URL slug for the folder section. If not provided, a slug will be generated from the folder name.
+
+```yaml docs.yml
+navigation:
+  - folder: ./pages/guides
+    title: Guides
+    slug: user-guides
+```
+
+### Icon
+
+Add an icon next to the folder section in the navigation.
+
+```yaml docs.yml
+navigation:
+  - folder: ./pages/guides
+    title: Guides
+    icon: fa-regular fa-book
+```
+
+### Collapsed
+
+Set the folder section to be collapsed by default when the page loads.
+
+```yaml docs.yml
+navigation:
+  - folder: ./pages/advanced
+    title: Advanced topics
+    collapsed: true
+```
+
+### Hidden
+
+Hide the folder section from the navigation. The pages will still be accessible via direct URLs but won't appear in the sidebar.
+
+```yaml docs.yml
+navigation:
+  - folder: ./pages/internal
+    title: Internal documentation
+    hidden: true
+```
+
+### Skip slug
+
+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
+navigation:
+  - folder: ./pages/guides
+    title: Guides
+    skip-slug: true
+```
+
+### Availability
+
+Set the availability status for all pages in the folder section. Options are `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`.
+
+```yaml docs.yml
+navigation:
+  - folder: ./pages/beta-features
+    title: Beta features
+    availability: beta
+```
+
+## Combining folder and manual navigation
+
+You can combine folder-based navigation with manually defined pages and sections. This allows you to have some pages automatically discovered while maintaining explicit control over others.
+
+```yaml docs.yml
+navigation:
+  - section: Overview
+    contents:
+      - page: Introduction
+        path: ./pages/intro.mdx
+      
+      - folder: ./pages/guides
+        title: Guides
+      
+      - page: FAQ
+        path: ./pages/faq.mdx
+```
+
+In this example, the "Overview" section contains a manually defined "Introduction" page, followed by all pages from the `guides` folder, and then a manually defined "FAQ" page.
+
+## Controlling page order with frontmatter
+
+By default, pages discovered from a folder are sorted alphabetically by their generated titles. To control the order of pages, you can add a `position` field to the frontmatter of your markdown files:
+
+```mdx getting-started.mdx
+---
+title: Getting started
+position: 1
+---
+
+Your content here...
+```
+
+```mdx advanced-topics.mdx
+---
+title: Advanced topics
+position: 2
+---
+
+Your content here...
+```
+
+Pages with a `position` field will be sorted numerically before alphabetically sorted pages. Pages without a `position` field will appear after positioned pages in alphabetical order.
+
+## Use cases
+
+Folder-based navigation is particularly useful in these scenarios:
+
+**Large documentation sets**: When you have dozens or hundreds of pages, manually maintaining the navigation structure in `docs.yml` becomes tedious. Folder-based navigation lets you organize pages in the filesystem and have the navigation generated automatically.
+
+**Frequently updated content**: If you regularly add new pages to a section, folder-based navigation eliminates the need to update `docs.yml` every time you add a page.
+
+**Changelog or blog sections**: For date-based content like changelogs, you can organize files by date in a folder and have them automatically appear in the navigation.
+
+**Team collaboration**: When multiple team members are adding documentation, folder-based navigation reduces merge conflicts in the `docs.yml` file since new pages don't require configuration changes.
+
+## Example from Slack
+
+Here's a real-world example from Slack's documentation that combines manually defined pages with folder-based navigation:
+
+```yaml docs.yml
+navigation:
+  - tab: overview
+    layout:
+      - page: Introduction
+        path: ../../docs/pages/realtime-server-sdk/v4/index.mdx
+
+      - folder: ../../docs/pages/realtime-server-sdk/v4/tech-ref
+        title: Technical Reference
+
+      - folder: ../../docs/pages/realtime-server-sdk/v4/guides
+        title: Guides
+```
+
+In this configuration:
+- The "Introduction" page is explicitly defined with a specific path
+- The "Technical Reference" section is automatically generated from all files in the `tech-ref` folder
+- The "Guides" section is automatically generated from all files in the `guides` folder
+
+This approach provides a clean balance between explicit control for important pages and automatic discovery for content-heavy sections.