Attributes

Defining and Using Attributes

Imagine you have released a new version of your software and now need to adapt the manual. Without attributes, you would have to change each instance individually from "Version X" to "Version Y".

With attributes, you define a value once and use it everywhere in the document:

:version: 2.0
:productname: adoc Studio

The current version of {productname} is {version}.

Result: The current version of adoc Studio is 2.0.

The syntax is simple:

  • Definition: :attributename: value

  • Usage: {attributename}

When making changes, you only adjust the definition – all instances in the text are automatically updated.

attributes example

Important Standard Attributes

In addition to custom attributes, AsciiDoc offers many predefined attributes:

Attribute Effect

:toc:

Inserts a table of contents

:icons: font

Displays admonitions as icons instead of text

:sectnums:

Automatically numbers headings

:stem:

Activates mathematical formulas

:imagesdir: images

Sets the default directory for images

For PDF output, these are also relevant:

Attribute Effect

:title-page:

Creates a separate title page

:pagenums:

Displays page numbers

:toc-title: Contents

Changes the heading of the table of contents

Attributes in the Document Header

Many attributes must be placed in the document header – above the title or directly after it. This ensures they are effective throughout the entire document:

= My Document
:toc:
:icons: font
:version: 1.0

Here begins the text...
The adoc Coach helps you with selection. Press ESC in the document header to see all available attributes with explanations.
Attributes can also be defined in the product settings. This is especially useful when different outputs require different values – more on this in the chapter Products.