Documentation widgets are a way to simplify and single source information for use in the documentation.
The Fuchsia.dev documentation widgets are created with Jinja2 macros and are also supported in markdown format. The transformation of the widgets from markdown to an actual Jinja2 macro happens before the page is published on fuchsia.dev. For more information on Jinja2 macros, see macros.
All of the documentation widgets are defined in //docs/_common/_doc_widgets.md.
Prerequisites: (only for HTML/Jinja2)
Before you can use the documentation widgets in HTML/Jinja2, you must import them into your markdown (.md) file. At the top of your file, specify the following:
{% import 'fuchsia-src/_common/_doc_widgets.md' as widgets %}
General widgets
inline_toc
Creates a bulleted list of a table of contents (TOC) based on a _toc.yaml
file.
Examples
Bulleted list of a TOC:
Rendered
- Overview
- Documentation standards
- Document types
- Documentation style guide
- Markdown reference guide
- Code sample style guide
- Adding a glossary term
- Using documentation widgets
- Update site navigation and TOC
- Modifying non-inclusive words in mdlint
- Deprecating documentation
- Automated documentation checks - doc-checker
- Markdown linter - mdlint
- Shortlinks
HTML/Jinja2
{% set tocmeta | yamlloads %}
{% include "fuchsia-src/contribute/docs/_toc.yaml" %} {% endset %}{{ widgets.inline_toc () }}
Usage
Due to limitations, you cannot specify the _toc.yaml
file as a parameter of
the widget.
{% set tocmeta | yamlloads %}
{% include "_toc_file.yaml" %}
{% endset %}
{{ widgets.inline_toc () }}
Parameters
This widget does not use parameters, make sure to specify the prerequisites before using this widget.
Glossary
These widgets are specifically created to work with the glossary terms defined in //docs/glossary/glossary.yaml.
In order to enable over-hover definitions, you must use one of the syntaxes listed below. The markdown version is recommended. Using any other syntax will result in simple links without over-hover definitions.
For more information on adding a term to the glossary, see Adding glossary entries.
glossary_simple
Creates a hover-over definition of the short_description
of a term with
a link to the glossary term. Optionally, this term can be unclickable.
Examples
Clickable over-hover definition:
Rendered
Definition of ABI .
Non-clickable over-hover definition:
Rendered
Definition of ABI .
Usage
There are several ways of using this widget:
Markdown
- Xref link (preferred):
[display_name][glossary.term]
Alternatively, you don't need to specify display_name
, which lets the actual term
be used as the display_name
:
[glossary.term]
For both formats, you must define the Xref at the bottom of the markdown file. For example:
[glossary.display_name]: /docs/glossary/README.md#term
- Inline link:
[display_name](/docs/glossary/README.md#term)
- Inline link (shortened):
[display_name](/docs/glossary#term)
HTML/Jinja2
{{ widgets.glossary_simple ('term', 'display_name', 'notClickable')}}
Parameters
Markdown
Parameters | |
---|---|
display_name |
Required Specify the text in your markdown file that will have hover over text. Not required when using the xref syntax of [glossary.term]. In that case, the glossary term is used as the display_name. |
term |
Required Specify a term that is defined in the _glossary.yaml file. |
HTML/Jinja2
Parameters | |
---|---|
term |
Required Specify a term that is defined in the _glossary.yaml file. |
display_name |
Optional Specify the text in your markdown file that will have hover over text. |
notClickable |
Optional Required if using display_name Determines
if the term gets a link to the full glossary. If this is not
specified, the term will become clickable and have a link to its glossary
entry. |
glossary_box
Creates a definition box of the full_description
of a term. If the term
does not have a full_description
, the short_description
is used.
The definition box also displays an edit button for contributors to edit the glossary.
Examples
Definition box:
Rendered
Usage
There are several ways of using this widget:
Markdown
- Xref link (preferred):
[display_name][glossary.box.term]
Then, you must define the Xref at the bottom of the markdown file. For example:
[glossary.box.display_name]: /docs/glossary/README.md#term
- Inline link:
[display_name](/docs/glossary/README.md?style=box#term)
- Inline link (shortened):
[display_name](/docs/glossary?style=box#term)
HTML/Jinja2
{{ widgets.glossary_box ('term', 'display_name') }}
Parameters
Parameters term
Required
Specify a term that is defined in the _glossary.yaml file.display_name
Required
This parameter is required to prevent errors, but does not do anything.Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-07-16 UTC.
[{ "type": "thumb-down", "id": "missingTheInformationINeed", "label":"Missing the information I need" },{ "type": "thumb-down", "id": "tooComplicatedTooManySteps", "label":"Too complicated / too many steps" },{ "type": "thumb-down", "id": "outOfDate", "label":"Out of date" },{ "type": "thumb-down", "id": "samplesCodeIssue", "label":"Samples / code issue" },{ "type": "thumb-down", "id": "otherDown", "label":"Other" }] [{ "type": "thumb-up", "id": "easyToUnderstand", "label":"Easy to understand" },{ "type": "thumb-up", "id": "solvedMyProblem", "label":"Solved my problem" },{ "type": "thumb-up", "id": "otherUp", "label":"Other" }] {"lastModified": "Last updated 2024-07-16 UTC."} [[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-07-16 UTC."],[],[]]