Your site's sidebar navigation is defined in a
navigation.yaml file in the
root of your project directory (same directory as the
doctave.yaml file). See navigation reference for full details.
Your project must have a
navigation.yaml file in order to function correctly.
How to get started
Make sure you have a
navigation.yml file in the same directory as
navigation.yml might look like this:
- heading: Title of the section items: - label: Page One href: /page-one.md - label: Page Two href: /page-one.md items: - label: Nested page href: /page-two/nested-page.md
This will generate the following navigation structure:
External links in navigation
You can add external links to your navigation by using the
- heading: External links items: - label: Doctave external: https://doctave.com
Creating multiple sections
To create more than one section, add multiple root level sections into your
- heading: Title of section 1 items: - label: Page One href: /page-one.md - heading: Title of section 2 items: - label: Page Two href: /page-one.md
Nested navigation sections
Each section can contain subheadings (which can contain further subheadings). To represent this in
navigation.yml, you can add subheadings as the
items of a section (or another subheading).
- heading: Title of the section items: - label: Page One href: /page-one.md items: - subheading: Nested pages items: - label: Nested page one href: /page-two/nested-page.md - label: Nested page two href: /page-two/nested-page.md
This will generate the following nested navigation structure:
Generate navigation from an OpenAPI specification
You can let Doctave generate links to your OpenAPI spec directly from the spec itself.
Add an element to an
items list, that references an OpenAPI spec that you have listed in your
- heading: API Reference items: - open_api_spec: openapi.json
This will generate links for each OpenAPI Tag, with their associated operations as collapsed child items.
The order of the links is determined by the order in which your tags appear in your OpenAPI specification file.
If you don't want to render links to all the pages generated by your OpenAPI
spec, you can use the
only: field to filter which tags show up in the
- heading: Access Control API items: - open_api_spec: openapi.json only: # <- Only render links for the following 2 OpenAPI tags: - Authentication - Authorization
Collapse a section
To collapse and hide sections, you can use the
collapsible properties of the section or subheading.
collapsed property will cause the list to not be shown by default, but
it can be expanded on click.
In contrast, the
collapsible property doesn't hide the list by default,
but lets the reader toggle the visibility themselves.
- heading: Title of the section collapsible: true # <= This is new items: - label: Page One href: /page-one.md - label: Page Two href: /page-one.md
Conditionally show navigation items
Sections in the navigation can be shown based on a condition, using the
- heading: API Reference show_if: user_preferences: plan: one_of: - Growth - Enterprise
In the above example, we're telling Doctave to only show the API Reference section if the user has selected as their plan either Growth or Enterprise. See more in the User Preferences section.
Conditionals are based on matchers which you can use to determine when a section or link should be shown.
equals is the simplest matcher. It checks that the given plan is an exact match.
show_if: user_preferences: plan: equals: Enterprise
one_of matcher expects as an argument
a list of values to match against.
show_if: user_preferences: plan: one_of: - Growth - Enterprise
Was this page helpful?