Document folder-based navigation configuration #1765
+261
−0
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}
|
|
||
| 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. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'quickly' if it's not important to the meaning of the statement.
|
|
||
| **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.
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.
Document folder-based navigation configuration
Summary
This PR adds comprehensive documentation for the folder-based navigation feature that allows users to automatically generate navigation from a folder of markdown files instead of manually listing each page in
docs.yml.Changes:
fern/products/docs/pages/navigation/folder-based-navigation.mdx(259 lines)fern/products/docs/docs.ymlto include the new page in the Configuration section, positioned after "Navigation"What the documentation covers:
title,slug,icon,collapsed,hidden,skip-slug,availabilitypositionfieldReview & Testing Checklist for Human
Test the folder configuration feature - Create a test docs project with a folder of markdown files and verify the feature actually works as documented. Key things to test:
.mdand.mdxfiles?skip-slug,availability,collapsed) work as documented?Verify frontmatter position sorting - I documented that you can add a
positionfield to frontmatter to control page order. I found evidence of this in git commits but didn't verify the implementation. Please test:position: 1,position: 2, etc. in frontmatterCheck configuration options completeness - Verify all the options I documented (
title,slug,icon,collapsed,hidden,skip-slug,availability) actually work with folder configuration and aren't just generic options that don't apply.Verify the Slack example - The example from Slack's documentation (lines 238-257) is based on the Slack conversation quote. Please verify this example is accurate and complete.
Preview the documentation - Build the docs locally or check the PR preview to ensure:
Notes
fern/apis/docs-yml/definition/docs.ymland implementation inpackages/cli/configuration-loader/src/docs-yml/navigationUtils.ts