Navigation

Your site's sidebar navigation is defined in a navigation.yaml file in the root of your project directory (same directory as the docapella.yaml file). Similarly, each tab or subtab can have their own navigation structure.

Your project must have a root navigation file file in order to build your project.

Example navigation.yaml

A simple 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

Links are grouped into sections , where each section has a heading .

External links in navigation

You can add external links to your navigation by using the external property.

- heading: External links
  items:
  - label: Docapella
    external: https://docapella.com

Creating multiple sections

To create more than one section, add multiple root level sections into your navigation.yml .

- 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

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 Docapella 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 docapella.yaml :

- 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.

Filtering tags

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 navigation.

- 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 collapsed and collapsible properties of the section or subheading.

The 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