--- ---

AsciiDoc Attributes Naming and Usage

DocOps Lab documentation style and usage for AsciiDoc attributes and placeholders.

Consistency of variable/placeholder names throughout and across project documentation is paramount to maintainability.

This document defines the canonical attribute naming conventions for all AsciiDoc files, as well as tag-group names and conditional assignment. This guide is intentionally prescriptive: attributes are small public APIs and must be stable, predictable, and single-sourced when their values are identical across repositories.

Scope

This guidance applies to all DocOps Lab repositories and documentation sources that publish AsciiDoc attributes in README.adoc and repo-level documentation. It covers:

  • attribute key naming (prefixes, suffixes, separators)

  • repository/project/product attribute namespaces

  • tag-group names and nesting logic

  • conditional blocks for common build/render targets and other environment variables

Attribute Naming Principles

  1. Use only lowercase letters, digits and underscore (_) in attribute names. Do not use hyphens (-) in attribute names except:

    • inside the name of a slug or other identifier (xref_blog_true-single-sourcing_link)

    • when a third-party tool or convention requires it (ex: page-* frontmatter attributes for Jekyll)

  2. Prefer semantic prefixes:

    • docopslab_ for org-level

    • this_proj_ for project-level

    • this_prod_ for product-level (only when product identity differs)

    • this_repo_ only when the repo filesystem identity differs and cannot be expressed with this_proj_.

  3. Suffixes carry meaning:

    • _vrsn for to reference a product version (this_prod_vrsn)

    • _version for third-party versions (this_prod_ruby_version)

    • _majmin for major.minor version pair

    • _url for HTTPS addresses

    • _uri for addresses that could be URLs or local paths

    • _git_uri for SSH clone addresses

    • _www_url specifically for HTML web front/home/landing pages, including GitHub project homepages (_src_www_url)

    • _docs_url for documentation site addresses

  4. Universal values that must be identical across repos live in // tag::universal-settings[] and are canonically sourced in DocOps/lab/gems/docopslab-dev/assets/templates/README.asciidoc.

  5. // tag::global-settings[] is the per-repo include that nests universal-settings.

Special patterns

  • Forkable projects may keep the _prime pattern (ex: proj_docs_www_prime) if they provide a documented override mechanism. Treat this as an advanced pattern; document its use in the README.

  • Keep page-* frontmatter (Jekyll) attributes outside of global-settings.

  • Keep pub_type / docterm repository-specific; these are not part of the universal attribute API.

Standard Attribute Names (Canonical List)

  • docopslab_src_www_url: canonical DocOps GitHub org web page (https://github.com/DocOps). This is the primary universal org URL.

  • docopslab_www_url: DocOps public website (https://docopslab.org). Different from the org web page.

  • this_proj_slug: repository slug (machine name), ex: releasehx

  • this_proj_name: human-friendly project short name, ex: ReleaseHx (use this_proj_name, not title)

  • this_prod_vrsn_major: integer major version

  • this_prod_vrsn_minor: integer minor version

  • this_prod_vrsn_majmin: {this_prod_vrsn_major}.{this_prod_vrsn_minor}

  • this_prod_vrsn_patch: patch number

  • this_prod_vrsn: {this_prod_vrsn_majmin}.{this_prod_vrsn_patch}

  • this_prod_vrsn_next: the very next planned release

  • this_prod_vrsn_next_majmin: the next minor or major release planned

  • this_proj_src_www_url: derived: {docopslab_src_www_url}/{this_proj_slug} (recommended composite form)

  • this_proj_src_git_uri: derived or explicit SSH clone URI

  • this_proj_docs_url: documentation site URL (if hosted separately)

Boolean Attributes

Use toggles to set or conditionalize states such as:

intended audience type or role

  • audience-agent

  • audience-beginner

target platform or format

  • env-github

  • site-gen-jekyll

  • backend-pdf

These kinds of attributes are passed depending on how the AsciiDoc is converted. Platform and format indicators tend to get argued by the converter at runtime.

But you can also check for statuses that might be set in previous files depending on the use-case of the output.

Testing for existence of a target platform
ifdef::audience-level-beginner[]
As a beginner, you will see extra content in parts of this guide.

If you are an expert, skip to the <<expert-guide>>.
endif::[]
Testing for non-existence of a target audience type.
ifndef::audience-agent[]
This content is _not_ to appear in docs generated for AI agents.
endif::[]

It is generally advised to create two versions of any such indicator that may need to be resolve a variable placeholder later.

Setting open-ended key and boolean simultaneously
:audience-level: beginner
:audience-level-beginner: true

Later we can reference the {audience-level}, which might be overwritten by an attribute passed at runtime.

Tag Groups and Single-sourcing

Use these tag names for include-able blocks:

  • // tag::global-settings[]: all repository-level settings; this is the block that most documents include to get their configuration.

  • // tag::universal-settings[]: inside global-settings. Contains only values guaranteed to be identical across repos and managed centrally (canonical source: lab/README.adoc).

The universal-settings block contains shared values (ex: docopslab_src_www_url), but they are not immutable. Local overrides should be placed after the universal section.

Universal attributes, resolved
// ALL changes within this block must be made in prime template:
//  DocOps/lab/gems/docopslab-dev/templates/README.asciidoc
:docopslab_src_www_url: https://github.com/DocOps
:docopslab_domain: docopslab.org
:docopslab_www_url: https://docopslab.org
:docopslab_io_www_url: https://docopslab.github.io
:docopslab_ruby_version: 3.2.7
:docopslab_git_src_uri: git@github.com:DocOps
:docopslab_src_raw_url: https://raw.githubusercontent.com/DocOps
:this_proj_src_www_url: https://github.com/DocOps/<slug>
:this_proj_src_raw_url: https://raw.githubusercontent.com/DocOps/<slug>
:this_proj_src_main_raw_url: https://raw.githubusercontent.com/DocOps/lab/main
:this_proj_src_main_files_url: https://github.com/DocOps/<slug>/blob/main
:this_proj_src_git_uri: git@github.com:DocOps/<slug>.git
:this_proj_ruby_version: 3.2.7
:docs_extn:
// Settings likely to be overridden locally
:this_prod_slug: <slug>
:this_prod_name: <Project Name>
:this_prod_src_www_url: https://github.com/DocOps/<slug>