diff --git a/fern/pages/docs/building-your-docs/navigation.mdx b/fern/pages/docs/building-your-docs/navigation.mdx index b2116e0ad0e..fd7f901f0c3 100644 --- a/fern/pages/docs/building-your-docs/navigation.mdx +++ b/fern/pages/docs/building-your-docs/navigation.mdx @@ -29,16 +29,16 @@ navbar-links: ## Sections, contents, and pages -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 that they are listed in `docs.yml`. +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 that they are 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`. 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 do not 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. ```yaml Example navigation config -navigation: +navigation: - section: Introduction - contents: + contents: - page: My Page path: ./pages/my-page.mdx - api: API Reference @@ -47,9 +47,9 @@ navigation: 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 -navigation: +navigation: - section: Introduction - contents: + contents: - page: My Page path: ./pages/my-page.mdx - page: Another Page @@ -58,38 +58,77 @@ navigation: ``` To add another section, add another `section` to the `navigation`. Example: + ```yaml Example navigation config with additional section -navigation: +navigation: - section: Introduction - contents: + contents: - page: My Page path: ./pages/my-page.mdx - api: API Reference - section: Help Center - contents: + contents: - page: Contact Us path: contact-us.mdx ``` ### 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 will not be indexed. + +```yaml Example navigation config with additional section {7, 10} +navigation: + - section: Introduction + contents: + - page: My Page + path: ./pages/my-page.mdx + - page: Hidden Page + hidden: true + path: ./pages/my-hidden-page.mdx + - section: Hidden Sections + hidden: true + contents: + - page: Another Hidden Page + path: ./pages/also-hidden.mdx +``` + +## Section overviews + +To add an overview page to a section, add a `path` property to the section. + +```yaml Example section with an overview {7} +navigation: + - section: Introduction + contents: + - page: My Page + path: ./pages/my-page.mdx + - section: Guides + path: ./pages/guide-overview.mdx + contents: + - page: Simple Guide + path: ./pages/guides/simple.mdx + - page: Complex Guide + path: ./pages/guides/complex.mdx +``` ## Nested sections + If you'd like a section to toggle into more sections and pages, you can nest sections within sections. Here's an example: + ```yaml Example navigation config with nested sections navigation: - tab: guides layout: - section: Learn - contents: + contents: - section: Key Concepts - contents: + contents: - page: Embeddings path: ./docs/pages/embeddings.mdx - page: Prompt Engineering path: ./docs/pages/prompts.mdx - section: Generation - contents: + contents: - page: Command Nightly path: ./docs/pages/command.mdx - page: Likelihood @@ -105,10 +144,10 @@ navigation: For icons to appear next to sections and pages, add the `icon` key. The value should be a valid [Font Awesome icon](https://fontawesome.com/icons) name. Pro and Brand Icons from Font Awesome are supported. ```yaml Example navigation config with icons -navigation: +navigation: - section: Home icon: fa-regular fa-home - contents: + contents: - page: My Page icon: fa-regular fa-file path: ./pages/my-page.mdx @@ -118,10 +157,10 @@ navigation: ## Links -You can add a link to an external page within your sidebar navigation with the following configuration: +You can add a link to an external page within your sidebar navigation with the following configuration: ```yaml title="docs.yml" -navigation: +navigation: - section: Home contents: - page: Introduction @@ -131,10 +170,9 @@ navigation: ``` -An external link within navigation + An external link within navigation - ## Tabs Within the navigation, you can add `tabs`. Tabs are used to group sections together. The example below shows tabs for `Help Center`, `API Reference`, and an external link to `Github`. Each tab has a `title` and `icon`. [Browse the icons available](https://fontawesome.com/icons) from Font Awesome. Pro and Brand Icons are supported. @@ -174,10 +212,10 @@ tabs: Here's an example of what the Tabs implementation looks like: -![Screenshot showing two vertically stacked tabs labeled API Reference and Help Center](https://fern-image-hosting.s3.amazonaws.com/fern/tabs.png) + ![Screenshot showing two vertically stacked tabs labeled API Reference and Help + Center](https://fern-image-hosting.s3.amazonaws.com/fern/tabs.png) ## Versions -If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the `versions`. For more information, check out our [documentation on versioning](/learn/docs/building-your-docs/versioning). - +If you have multiple versions of your documentation, you can introduce a dropdown version selector by specifying the `versions`. For more information, check out our [documentation on versioning](/learn/docs/building-your-docs/versioning).