Documentation widgets

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

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_nameDetermines 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.