跳转至

{% include "docs/glossary/_common/_glossary_header.md" %}

{% import 'docs/_common/_doc_widgets.md' as widgets %}

{% comment %}

This is used to do the initial import statement in the doc due to a copybara limitation

[ABI][glossary.ABI] glossary.ABI endcomment %}

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{: .external}.

All of the documentation widgets are defined in [//docs/_common/_doc_widgets.md][doc-widgets].

Prerequisites: (only for HTML/Jinja2) {#widgets-prereq}

Note: This is not required if you use markdown syntax. You only need to use an import statement when using the HTML/Jinja2 version of the widgets.

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:

{% verbatim %}
{% import 'docs/_common/_doc_widgets.md' as widgets %}
{% endverbatim %}

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}

    {% set tocmeta | yamlloads %} {% include "docs/contribute/docs/_toc.yaml" %} {% endset %} {{ widgets.inline_toc () }}

  • {HTML/Jinja2}

    {% verbatim %} {% set tocmeta | yamlloads %}

    {% include "docs/contribute/docs/_toc.yaml" %}

    {% endset %}

    {{ widgets.inline_toc () }}

    {% endverbatim %}

Usage

Note: This widget does not have a markdown equivalent and must also import the widgets on the page. For more information on how to import widgets, see Prerequisites: (only for HTML/Jinja2).

Due to limitations, you cannot specify the _toc.yaml file as a parameter of the widget.

{% verbatim %}
{% set tocmeta | yamlloads %}
{% include "<var>_toc_file</var>.yaml" %}
{% endset %}
{{ widgets.inline_toc () }}
{% endverbatim %}

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 [//glossary/_glossary.yaml][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-add].

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:

Note: This option is only available when using the Jinja2 syntax.

  • {Rendered}

    Definition of {{ widgets.glossary_simple ('ABI', 'ABI', 'notClickable')}}.

Usage

There are several ways of using this widget:

  • {Markdown}

  • Xref link (preferred):

{% verbatim %}[display_name][glossary.term]{% endverbatim %}

Alternatively, you don't need to specify {{"<var>display_name</var>"}}, which lets the actual term be used as the {{"<var>display_name</var>"}}:

{% verbatim %}[glossary.term]{% endverbatim %}

For both formats, you must define the Xref at the bottom of the markdown file. For example:

{% verbatim %}[glossary.display_name](../../glossary/README.md#term{%) endverbatim %}
  • Inline link:
{% verbatim %}[display_name](../../glossary/README.md#term){% endverbatim %}
  • Inline link (shortened):
{% verbatim %}[display_name](../../glossary#term){% endverbatim %}
  • {HTML/Jinja2}

Note: To use the glossary widgets in any HTML markup, you muse use the JINJA2 syntax. This is useful when creating HTML tables. Also, make sure to follow the Prerequisites: (only for HTML/Jinja2).

{% verbatim %}{{ widgets.glossary_simple ('<var>term</var>', '<var>display_name</var>', '<var>notClickable</var>')}}{% endverbatim %}

Parameters

Note: When using the widgets in Jinja2 there are additional parameters available.

  • {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 {% verbatim %}[glossary.term]{% endverbatim %}. 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}

    ABI

Usage

Note: The definition box should not be used inside of other markdown elements such as paragraphs. It should only be used between other elements such as pagraphs, headings, lists, etc... If you use the definition box inside a paragraph it will cause text around it to get wrapped.

There are several ways of using this widget:

  • {Markdown}

  • Xref link (preferred):

    {% verbatim %}[display_name][glossary.box.term]{% endverbatim %}

    Then, you must define the Xref at the bottom of the markdown file. For example:

    {% verbatim %}glossary.box.display_name endverbatim %}

  • Inline link:

    {% verbatim %}display_name{% endverbatim  %}

  • Inline link (shortened):

    {% verbatim %}display_name{% endverbatim %}

  • {HTML/Jinja2}

Note: The display_name parameter does not do anything and is only defined to ensure consistency with the usage of the simple glossary widgets. Also, make sure to follow the Prerequisites: (only for HTML/Jinja2).

{% verbatim %}{{ widgets.glossary_box ('<var>term</var>', '<var>display_name</var>') }}{% endverbatim %}

Parameters

Note: The parameters for markdown and Jinja2 are the same.

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.

doc-widgets }}docs/_common/_doc_widgets.md glossary-yaml }}{{ glossary_file }}

glossary-add

最后更新: 2022 年 12 月 31 日（Saturday） 21:06 CST