blob: 6babe671d64f8eff81872ba1fbadedfbc4b1088c [file] [log] [blame] [view] [edit]
# Updating site navigation and TOC files
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/HEAD/docs/_toc.yaml).
If you add a new document to fuchsia.dev, or if you move existing documentation within the site,
you need to change the site navigation, 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/HEAD/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/HEAD/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/index.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/HEAD/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.