docs/contribute/best-practices/documentation_navigation_toc.md

# Change table of contents navigation

The table of contents is the list of documents that is displayed on the left
side of every page on fuchsia.dev. It is represented by a hierarchical set of
`_toc.yaml` files. The top level `_toc.yaml` file is
[`_toc.yaml`](https://fuchsia.googlesource.com/fuchsia/+show/master/docs/_toc.yaml).

If you add a new document or if you want to change how existing documents are
organized in the source documentation section of
[fuchsia.dev](/docs), you need to change the navigation table of contents, defined in
`_toc.yaml` files. These files are located in the same directory of
the documentation file or in a parent directory.

## Existing document

To change the documentation navigation for an existing document:

1. Locate the corresponding `_toc.yaml` file for the document in the source code
   tree.

   For example, if you want to modify the navigation for the
   [concepts page of Zircon](/docs/concepts/kernel/concepts.md),
   you can see that there is a
   [`_toc.yaml`](https://fuchsia.googlesource.com/fuchsia/+show/master/docs/concepts/kernel/_toc.yaml)
   file in the same directory.

1. Edit the `_toc.yaml` file.
   You have to specify the published location of the document in the
   `_toc.yaml` files instead of the actual path in the Fuchsia source
   code. See [`_toc.yaml` reference](#toc-reference).

## New document

To add navigation for a new document:

1. Locate the closest `_toc.yaml` file for the document.
   If the directory where you created
   the document has a `_toc.yaml` file, use that file. If not, navigate through
   the parent directories until you locate the closest `_toc.yaml` file.

1. Edit the `_toc.yaml` file.
   See [`_toc.yaml` reference](#toc-reference).

## `_toc.yaml` reference {#toc-reference}

A `_toc.yaml` file can contain single entries or expandable sections
with multiple entries:

* Single entry

  A single entry in the table of contents navigation is represented by a title
  and a path in the corresponding `_toc.yaml` file. Each entry must also use
  the correct indentation like the other entries in `_toc.yaml`.

  Paths must follow these requirements:

  * Paths to files should be the full path from the root of the project. For
    example, `/docs/development/api/cli.md`.
  * Paths to directories should not include a trailing slash, and the directory
    must have a file named `README.md`.

  For example, to add an entry for the Zircon `concepts.md`
  page in its respective [`_toc.yaml`](https://fuchsia.googlesource.com/fuchsia/+show/master/docs/concepts/kernel/_toc.yaml),
  you should add an entry:

  ```
  - title: "Kernel concepts"
    path: /docs/concepts/kernel/concepts.md
  ```

* Expandable section

  An expandable section is an expandable group of multiple entries in a table
  of contents. For example, see the expandable sections, such as Networking
  and Graphics, in the
  [Concepts section](/docs/concepts/README.md). Each expandable
  section has an arrow to the left of the section name.

  You can create a group of entries with a `section` element. Each section must
  also use the correct indentation like the other entries in `_toc.yaml`. Then,
  you can add single entries to the section.

  For example, to add a section in the "System" table of contents
  [`_toc.yaml`](https://fuchsia.googlesource.com/fuchsia/+show/master/docs/concepts/_toc.yaml),
  add a `section` group and its corresponding entries. Usually the entries are included from another _toc.yaml file:

  ```yaml
  - title: "Zircon kernel"
    section:
    - include: /docs/concepts/kernel/_toc.yaml
  ```

Once you have made these changes, you can submit your changes for review.