Fuchsia.dev uses a yaml glossary-yaml file to define all Fuchsia specific terminology.
This format allows Fuchsia to use single-source definitions to be edited in a single location and updated throughout the documentation. These definitions can then be used throughout documentation using documentation widgets, which then allows you to use inline definitions or full definitions in your documents.
Additionally, Fuchsia has a main filterable glossary page.
Add a glossary entry
To add a glossary definition, you need to edit the yaml glossary-yaml to include information about your definition:
Reference
| Glossary definition | |
|---|---|
term | Required
Define the glossary term. |
short_description | Required
Define a short description for your glossary term. This definition must be short, preferably a single sentence. This definition can then be used to have definitions as hover-over text. You must use HTML syntax. However, if you have a simple definition that is a single sentence or paragraph, you can use plain text. For example, this is the definition for the term ABI . |
full_description | Optional
Define a full for your glossary term. This description should be complete and fully explain the term. You must use HTML syntax, including for links. However, if you have a simple definition that is a single sentence or paragraph, you can use plain text. For a link, use this format: <a href="link_location">link_title</a>
|
see_also | Optional
Create a list of related links for the term. This can be links to other terms or related documentation. You must use HTML syntax.
|
related_guides | Optional
Create a list of related guides for the term. This should
only be links to guides located in
|
area | Required
Define a list of the areas that your glossary term pertains to. These areas make the glossary terms filterable on the glossary page. You must use HTML syntax.
Valid areas Valid areas
|
Sample
- term: 'ABI'
short_description: 'The binary-level interface to the system.'
full_description: 'The <a href="/docs/concepts/packages/system.md">Application Binary Interface</a> (ABI)
for a system is the binary-level interface to the system. Typically you don''t
write software that uses the system ABI directly. Instead, you write software
against the system API. When the software is compiled, the binary artifact
created by the compiler interfaces with the system through the ABI.
Changes to the system ABI may require you to recompile your source code to
account for the changes in the ABI.'
see_also: ['<a href="/docs/glossary#ABI">ABI</a>',
'<a href="/docs/glossary#storage-capability">Storage capability</a>']
related_guides: ['<a href="/docs/development/tracing/tutorial/registering-a-trace-provider.md">Registering a trace provider</a>',
'<a href="/docs/development/hardware/paving.md">Installing Fuchsia on a device</a>']
area: ['System', 'General']
Once you have created the entry for your glossary entry and submitted the Gerrit change, your glossary term will be visible on the glossary page and usable as a documentation widget.