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
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.
The external link check can be skipped by adding
For more options, see the full command line reference.
If it is not part of the current build configuration for some reason,
fx set including the option to build doc_checker:
These are the situations that are reported by doc-checker:
Internal link checks
Links to nonexistent files
Links to files in //docs represented as full URLs
These are links that reference
access a file in //docs. These links should be converted to file paths.
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 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
fuchsia relative paths.
alt text for images
Images must have meaningful
![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
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 files are mainly used to create the information architecture for
These checks enforce the table of contents structure described in _toc.yaml reference.
- top level key
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
section: <toc entry>- (optional) Indented toc entry defining a collapsible section, usually defined via
includeanother _toc.yaml file.
skip_translation: true- (optional) Prevents human and machine translation of all link titles in this entry and any descendents.
status: <string>- (optional) Used with
titleand cannot be used with
include. Applies a predefined status. The status must be one of:
step_group: <string>- (optional) Used to create groups of content that have
nextnavigation links to the bottom of the pages.
style: <string>- (optional) Cannot be used with
include. This style is applied to the
sectionelement. This value must be
title: string- (optional) The link title.
pathproperties are valid paths:
- File paths such as
/referenceto generated reference documentation. These links are validated using external links to
- Special files:
- File paths such as
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
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.
TBD: _What is the use of roadmap.yaml?_
TBD: _What is the use of _drivers_areas.yaml?
Structure of _drivers_epitaphs.yaml
TBD: _What is the use of __driversepitaphs.yaml?
TBD: _What is the use of problems.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?
List of supported systems configurations.
TBD: _What is the use of tools.yaml?_
See: source code
This file defines the redirection rules for deprecated documents.
Structure of glossary.yaml
This file defines the glossary of Fuchsia terminology.
External link checks
Broken external links (resulting in 404)
hl parameter for Google hosted sites
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.