The command line tool `doc-checker` performs several checks on the documentation
source. Checks that do not need to access external links are performed as
presubmit checks when submitting changes to the //docs directory.

The primary goal of doc-checker is to make sure all the documents in the `//docs`
directory are part of the interconnected graph made up of `_toc.yaml` files and
in-page links are reachable when the documentation is published on
fuchsia.dev. Other checks inspect the links themselves to enforce documentation
standards and consistency.

## Running doc-checker

    fx doc-checker

The external link check can be skipped by adding `--local-links-only`.

For more options, see the [full command line reference](https://fuchsia.dev/reference/tools/fx/cmd/doc-checker.md).

If it is not part of the current build configuration for some reason,
re-run `fx set` including the option to build doc_checker:
`--with //tools/doc_checker:doc_checker`.

These are the situations that are reported by doc-checker:

## Internal link checks

### Links to nonexistent files

    [missing doc](/docs/does_not_exist.md)

### Links to files in //docs represented as full URLs

These are links that reference `fuchsia.googlesource.com` or `fuchsia.dev` and
access a file in //docs. These links should be converted to file paths.

#### Incorrect

    [unnessary link](https://fuchsia.dev/fuchsia-src/get-started/learn-fuchsia.md)

#### Correct

    [correct link](/docs/get-started/learn-fuchsia.md)

### Links to inactive Fuchsia projects

These are projects that are included in the Fuchsia source tree which have been
merged into Fuchsia or completed deprecated. The list of [valid projects](https://source.corp.google.com/fuchsia/tools/doc_checker/src/link_checker.rs;l=49%5D)
is part of the source code.


         [invalid old project](https://fuchsia.googlesource.com/garnet/+/refs/heads/main)

### Links with relative paths past //docs

These are links that point to paths beyond the //docs directory. These should be
converted to `fuchsia` relative paths.

#### Incorrect

      [source file](/docs/../src/BUILD.gn)

#### Correct

       [source file](https://cs.opensource.google/fuchsia/fuchsia/+/main:/src/BUILD.gn)

### Missing `alt` text for images

Images must have meaningful `alt` text.

    ![Diagram of the state transitions](/docs/state-machine.png "State machine")

### Including markdown fragment files

Markdown file fragments are included in another markdown file by using

```
<<relative-path-to/_file.md>>
```

The path must be relative to the current .md source file---absolute paths
cannot be used. The `<< >>` directive is a block directive and so must appear
on a line by itself.

## YAML data file checks

YAML files in fuchsia.dev are used to store documentation content in a structured
format which is then rendered through the use of Jinja templates. Any YAML file
that is prefixed with a `_` indicates that the YAML is not published as a
standalone file, but only rendered through the use of a template. If a YAML
file is not prefixed with `_`, the YAML file is published on fuchsia.dev and can
be viewed as a plain YAML file.

### _toc.yaml checks

`_toc.yaml` files are mainly used to create the information architecture for
fuchsia.dev.

These checks enforce the table of contents structure described in
[_toc.yaml reference](https://fuchsia.dev/docs/contribute/docs/documentation-navigation-toc#toc-reference).

- top level key `toc`
- entries are one of:

  - `break: true` - *(optional)* Adds a vertical break
  - `contents: <list of toc entries>` - *(optional)* The contents of a custom tab.
  - `heading: <string>` - *(optional)* The heading for a group of links.
  - `include: <path to _toc.yaml>` - *(optional)* Includes another _toc.yaml.
  - `name: <string>` - *(optional)* Name of this tab.
  - `path: <string>` - *(optional)* Path or URL to a page.
  - `path_attributes: <mapping>` - *(optional)* Name-value pairs of attributes for the link created based on the `path` property.
  - `section: <toc entry>` - *(optional)* Indented toc entry defining a collapsible section, usually defined via `include` another _toc.yaml file.
  - `skip_translation: true` - *(optional)* Prevents human and machine translation of all link titles in this entry and any descendants.
  - `status: <string>` - *(optional)* Used with `heading` or `title` and cannot be used with `break` or `include`. Applies a predefined status. The status must be one of:
  - `alpha`
  - `beta`
  - `deprecated`
  - `experimental`
  - `external`
  - `limited`
  - `new`
  - `step_group: <string>` - *(optional)* Used to create groups of content that have `prev` and `next` navigation links to the bottom of the pages.
  - `style: <string>` - *(optional)* Cannot be used with `break` or `include`. This style is applied to the `heading` or `section` element. This value must be `accordion`.
  - `title: string` - *(optional)* The link title.
- `path` properties are valid paths:

  - File paths such as `/docs/somewhere/file.md`
  - `http://` or `https://` URLs.
  - `/reference` to generated reference documentation. These links are validated using external links to `fuchsia.dev/reference`.
  - Special files: `/CONTRIBUTING.md` and `/CODE_OF_CONDUCT.md`.

### Pages not referenced in _toc.yaml graph

Markdown pages in //docs must appear in a `_toc.yaml` that is included in the
graph of table of contents created from the root _toc.yaml in
`//docs/_toc.yaml`.

### Structure of _areas.yaml

TBD: _What is the structure of _***areas***.yaml__

### Structure of _eng_council.yaml

TBD: _What is the use of _**eng_council.yaml** *?*

### Structure of _metadata.yaml

TBD: _What is the use of ***metadata.yaml***?_

### Structure of _rfcs.yaml

This file defines the metadata for RFC documents.

See [RFC metadata](https://fuchsia.dev/docs/contribute/governance/rfcs/create_rfc#create-metadata).

### Structure of_roadmap.yaml

TBD: _What is the use of ***roadmap.yaml***?_

### Structure of_drivers_areas.yaml

TBD: _What is the use of _**drivers_areas.yaml** *?*

### Structure of _drivers_epitaphs.yaml

TBD: _What is the use of __**drivers*epitaphs*.yaml** *?*

### Structure of_problems.yaml

TBD: _What is the use of ***problems.yaml***?_

### Structure of_redirects.yaml

This file defines redirections to another page for a given URL.

### Structure of _supported_cpu_architecture.yaml

TBD: _What is the use of _**supported_cpu_architecture.yaml** *?*

### Structure of_supported_sys_config.yaml

List of supported systems configurations.

See [Supported system config list](https://fuchsia.dev/docs/contribute/governance/rfcs/0130_supported_hardware#initial_supported_sys_configyaml_list)

### Structure of_tools.yaml

TBD: _What is the use of ***tools.yaml***?_

See: [source code](https://source.corp.google.com/fuchsia/tools/doc_checker/src/yaml.rs;l=185)

### Structure of_deprecated-docs.yaml

This file defines the redirection rules for deprecated documents.

See: [Redirect the pages to the deprecation notice](https://fuchsia.dev/docs/contribute/docs/deprecating-docs#redirect_the_pages_to_the_deprecation_notice).

### Structure of _glossary.yaml

This file defines the glossary of Fuchsia terminology.

See: [Adding a glossary term](https://fuchsia.dev/docs/contribute/docs/glossary-entries#add_a_glossary_entry)

## External link checks

> [!NOTE]
> **Note:** External links are not checked during presubmits. These checks can be skipped by adding the `--local-links-only` flag.

### Broken external links (resulting in 404)

        [broken link](https://mispeeled.com)

### Including the `hl` parameter for Google hosted sites

The `hl` parameter indicates the user's host language. This parameter should
not be included in the URL since it disables the automatic redirection to
translated pages if they exist.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/contribute/docs/doc-checker.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/contribute/docs/doc-checker.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/docs/doc-checker.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/contribute/docs/doc-checker.md "Edit the source code of this page")