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.
fx doc-checker
The external link check can be skipped by adding --local-links-only
.
For more options, see the full command line reference.
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:
[missing doc](/docs/does_not_exist.md)
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.
[unnessary link](https://fuchsia.dev/fuchsia-src/get-started/learn-fuchsia.md)
[correct link](/docs/get-started/learn-fuchsia.md)
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)
These are links that point to paths beyond the //docs directory. These should be converted to fuchsia
relative paths.
[source file](/docs/../src/BUILD.gn)
[source file](/src/BUILD.gn)
alt
text for imagesImages must have meaningful alt
text.
![Diagram of the state transitions](/docs/state-machine.png "State machine")
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 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 fuchsia.dev.
These checks enforce the table of contents structure described in _toc.yaml reference.
top level key toc
entries are one of:
break: true
- (optional) Adds a vertical breakcontents: <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:
/docs/somewhere/file.md
http://
or https://
URLs./reference
to generated reference documentation. These links are validated using external links to fuchsia.dev/reference
./CONTRIBUTING.md
and /CODE_OF_CONDUCT.md
.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
.
TBD: What is the structure of areas.yaml
TBD: What is the use of eng_council.yaml?
TBD: What is the use of metadata.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?
TBD: What is the use of drivers_epitaphs.yaml?
TBD: What is the use of problems.yaml?
This file defines redirections to another page for a given URL.
TBD: What is the use of supported_cpu_architecture.yaml?
List of supported systems configurations.
See Supported system config list
TBD: What is the use of tools.yaml?
See: source code
This file defines the redirection rules for deprecated documents.
See: Redirect the pages to the deprecation notice.
This file defines the glossary of Fuchsia terminology.
Note: External links are not checked during presubmits. These checks can be skipped by adding the --local-links-only
flag.
[broken link](https://mispeeled.com)
hl
parameter for Google hosted sitesThe 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.