Reusable attributes

Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs> v0.0.1, 2024-06-25

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 ›