diff --git a/fern/docs.yml b/fern/docs.yml index c6e6601f4..c14e214cf 100644 --- a/fern/docs.yml +++ b/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 diff --git a/fern/products/docs/pages/changelog/2025-11-05.mdx b/fern/products/docs/pages/changelog/2025-11-05.mdx new file mode 100644 index 000000000..3f703f09d --- /dev/null +++ b/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). diff --git a/fern/products/docs/pages/navigation/overview.mdx b/fern/products/docs/pages/navigation/overview.mdx index f9d2f05b0..20c3b38a0 100644 --- a/fern/products/docs/pages/navigation/overview.mdx +++ b/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: @@ -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,16 +29,21 @@ navbar-links: ``` -## 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. -{/* */} -```yaml Example navigation config +You can combine folder-based navigation with manually defined pages. + + +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: @@ -50,10 +51,14 @@ navigation: path: ./pages/my-page.mdx - api: API Reference ``` -{/* */} -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: -{/* */} -```yaml Example navigation config + + + + + +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: @@ -61,31 +66,40 @@ navigation: path: ./pages/my-page.mdx - page: Another page path: ./pages/another-page.mdx - - api: API Reference ``` + + -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 ``` -{/* */} -### 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. + + + 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 + --- + ``` + + + + +## 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. {/* */} -```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: ``` {/* */} -### 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 ``` - 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). +## 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) -## 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,12 +239,12 @@ 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. {/* */} -```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 @@ -212,7 +252,8 @@ navigation: - 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: "" # Inline SVG path: ./pages/custom.mdx - api: API Reference