global-page-attributes.adoc

Global AsciiDoc page attributes

Global page attributes are defined in _config.yml and available to any page. They may be defined with the attributes key under either the asciidoc key or the asciidoctor key. The value of a global attribute defined in the asciidoctor.attributes key overrides the value from the same global attribute defined in the asciidoc.attributes key.

The value of the attributes key can either be an Array containing key-value assignments:

Example using the asciidoc top level key with the attributes as an Array:

asciidoc:
  attributes:
  - idprefix=_
  - source-highlighter=pygments
  - pygments-css=style

or a Hash containing key-value pairs:

Example using the asciidoctor top level key with the attributes as a Hash:

asciidoctor:
  attributes:
    idprefix: _
    source-highlighter: pygments
    pygments-css: style

When using the Hash syntax, you must use an empty string value to set a valueless attribute such as sectanchors:

asciidoctor:
  attributes:
    sectanchors: ''

Global attribute override behavior

By default, an attribute value defined in _config.yml overrides the same attribute set in the front matter or header of a document. For example, if you set page-layout in _config.yml, you won’t be able to set it per page.

asciidoctor:
  attributes:
  - page-layout=false

If you want to allow individual pages to be able to override the attribute, append the character @ to the value in _config.yml:

asciidoctor:
  attributes:
  - page-layout=false@

or

asciidoc:
  attributes:
    page-layout: false@

You may use attribute references in the attribute value to reference any attribute that’s already defined, including implicit attributes. For example, to set the iconsdir attribute based on the imagesdir attribute, use the following:

asciidoctor:
  attributes:
    imagesdir: /images
    iconsdir: '{imagesdir}/icons'

Caution

If the value begins with an attribute reference, and you’re defining the attributes using the Hash syntax, you must enclose the value in quotes. There are additional edge cases when the value must be enclosed in quotes, so it’s generally recommended to use them.

You can remove a previously defined attribute by prefixing the name with a minus sign (without any space between):

asciidoctor:
  attributes:
    -idprefix:

Yaml expressions as global attribute values

Jekyll parses the entire _config.yml file as yaml, so by default any attribute values that happen to be yaml expressions will be converted to objects. The object will be rendered using the Ruby .to_s method. To preserve the original string, quote the value:

asciidoctor:
  attributes:
    page-yaml: {key1: foo, key2: bar} # (1)
    page-yaml-string: '{key1: foo, key2: bar}' #(2)
    page-yaml-multiline: | #(3)
      key1: foo
      key2: bar

1. Unquoted value will render as {"key1"⇒"foo", "key2"⇒"bar"}, the string representation of the Ruby object.

2. Quoted value can be used as a string valued Asciidoc page attribute, rendering as the original string, {key1: foo, key2: bar}. If it is also used in liquid templates, the yaml will be parsed to an object before being made available to the liquid template.

3. Multi-line attributes cannot be defined in an AsciiDoc document, but this shows a way to set a global multi-line valued attribute. This will be rendered as:

key1: foo
key2: bar

Note that all leading spaces are removed.