Document folder-based navigation configuration #1765
Merged
+106
−43
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add comprehensive documentation for the new folder configuration feature that allows automatic navigation generation from a folder of markdown files. The documentation covers: - Basic usage and how it works - Filename to title/slug conversion rules - Nested folder support - All configuration options (title, slug, icon, collapsed, hidden, etc.) - Combining folder and manual navigation - Controlling page order with frontmatter - Use cases and real-world examples Includes example from Slack's documentation showing the feature in action. Co-Authored-By: Deep Singhvi <[email protected]>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
fern/products/docs/pages/navigation/folder-based-navigation.mdx
Outdated
Show resolved
Hide resolved
|
|
||
| **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. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'regularly' if it's not important to the meaning of the statement.
|
|
||
| **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 |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Example from Slack' should use sentence-style capitalization.
- Remove standalone folder-based-navigation.mdx page - Add concise 'Add pages from a folder' section to navigation overview - Create reusable snippet at /fern/snippets/folder-nav-basic.mdx - Add redirect from old URL to navigation overview - Add changelog entry for 2025-11-05 - Keep documentation dry and concise as requested Co-Authored-By: Deep Singhvi <[email protected]>
devalog
approved these changes
Nov 5, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Refactor folder-based navigation documentation to be concise and integrated
Summary
Per user feedback, the standalone folder-based navigation page was too verbose. This PR refactors the documentation to be dry and concise by:
folder-based-navigation.mdx, 259 lines) and integrating it as a short subsection in the navigation overview page (~7 lines)/fern/snippets/folder-nav-basic.mdxfor the basic example to avoid duplication/learn/docs/configuration/folder-based-navigation) to the navigation overview pageThe new documentation is minimal: introduces the
folderconfiguration with one example, mentions that subfolders become nested sections, and lists the supported options (title,slug,icon,collapsed,hidden,skip-slug,availability).Review & Testing Checklist for Human
/learn/docs/configuration/navigationcorrectly<Markdown src="/snippets/folder-nav-basic.mdx" />reference works in both the navigation overview page and the changelog entry#add-pages-from-a-folder) on the navigation overview pagefern docs devand navigate to the navigation overview page to ensure it renders correctly with proper formatting and the snippet resolvesNotes
what-is-docs-yml.mdxto avoid unnecessary duplication