Reusable attributes
This page explains how to use reusable metadata, or attributes, across multiple AsciiDoc documents in Fedora Documentation.
Why reusable attributes?
Sometimes you may want to use the same data across many AsciiDoc documents. Some examples are below:
-
Version releases (e.g. Fedora
N
) -
URL prefixes or suffixes (e.g.
https://pagure.io/fesco/issues/
) -
Dates and time (e.g. current year, like
2020
)
For these and more use cases, attributes allow you to define some metadata in a single place, and reuse it in multiple places.
Overview
There are two requirements for your Fedora Documentation project to use attributes.
-
Create an attributes file
-
Import attributes in your AsciiDoc file
Create attributes file
First, initialize an attributes.adoc
file for any module.
The example below shows a globally reusable attributes file in the ROOT
module:
.
└── ROOT
├── nav.adoc
├── pages
│ └── index.adoc
└── partials
└── attributes.adoc
This is an example attributes.adoc
from the Fedora DEI Team:
// This is a data store of information about the Fedora DEI team.
// Team name:
:team_name: Fedora Diversity, Equity, & Inclusion (DEI) Team
// Team summary:
:team_summary: The {team_name} encourages, supports, and enables DEI in the Fedora community. We work with the community to create an environment where everyone feels empowered to be a part of and contribute to the Fedora Project.
// Team page URL:
:team_url: https://docs.fedoraproject.org/en-US/dei/
// Team activity status.
// Choose from: Active, Inactive
:team_status: Active
// Preferred asynchronous communication channel
:team_asynch_communication: https://discussion.fedoraproject.org/tag/dei-team
// Preferred synchronous communication channel
:team_synch_communication: https://matrix.to/#/#dei:fedoraproject.org
// Issue tracker
:team_issue_tracker: https://gitlab.com/fedora/dei/home/
// Meetings
:team_meetings: https://apps.fedoraproject.org/calendar/diversity-team/
// Imported from our old attributes file.
:COMMBLOG: https://communityblog.fedoraproject.org
:FISCALYEAR: FY23
:FWIKI: https://fedoraproject.org/wiki
:YEAR: 2023
:MAJOROSVER: 39
Import attributes
Next, import the attributes file into your AsciiDoc document. Placing this macro on the top line will do the rest:
include::ROOT:partial$attributes.adoc[]
Use attributes in documentation
After creating an attributes file AND import attributes, reference the attributes in AsciiDoc documents with the following syntax:
{ATTRIBUTE}
See this example from the Fedora DEI Team:
*Full consensus* is required to approve new processes, make changes to
existing team policies, and tickets requiring
https://budget.fedoraproject.org/budget/{FISCALYEAR}/d-i.html[D&I budget].
Want to help? Learn how to contribute to Fedora Docs ›