page-attributes.adoc

Page Attributes

Any AsciiDoc attribute defined globally or in the AsciiDoc document header whose name begins with page- (cf this) gets promoted to a {url-jekyll-variables}[page variable]. The part of the name after the page- prefix is lowercased and used as the variable name (e.g., page-LayOut becomes layout). Since such a global attribute set in _config.yml is already parsed as yaml, its value as a page variable is already naturally a Ruby object. For attributes set in the document header, the variable value is the {url-yaml}[YAML] data (single-line form) translation of the attribute string value.

Since the Asciidoc string attribute value is processed into YAML data as a page variable, you can build nested data structure using the inline YAML syntax. For example, here’s how you can assign a value to the page.header.image page variable:

:page-header: { image: logo.png }

For longer expressions that are inconvenient to write on one line, line continuations may be used:

:page-complex-object: { data: \
  { detail: \
    {subdetail: \
      [ item1, \
       item2] \
    } \
  } \
}

Note that this is still in yaml single-line syntax.

Merging attribute values

If an attribute that becomes a page variable is defined both in _config.yml and the page header, one value or the other is used, depending on the override setting on the global value. For values that parse to complex objects it can be useful to merge global and page objects. Specify the names of these attributes under the asciidoctor.merge_attributes key in _config.yml as a yaml array or comma-separated string. The object value of each named attribute will be deep-merged with any value provided in a page header to generate the Jekyll page variable value. The attributes named in the merge_attributes key are not provided to the page. The deep-merge only takes account of hash keys; unlike some deep-merge implementations array values are simply replaced. Also, there is no way to remove a key, although it can be set to nil.

For instance:

asciidoctor:
  attributes:
    page-complex:
      foo1: bar
      foo2:
        bar1:
          - x
          - y
        bar2: baz
  merge_attributes:
    - page-complex

= merge_attributes demo
:page-complex: {foo1: not bar!, \
  foo2: { \
    bar1: [z] \
}}

yields (Ruby object .to_s representation)

{"foo1"=>"not bar!", "foo2"=>{"bar1"=>["z"], "bar2"=>"baz"}}

Tips and tricks

To define a page attribute name that contains multiple words, use either a hyphen or underscore character to connect the words.

:page-short-name: slug

Important

Page attributes must be defined in the document header. That means either putting them directly below the document title (the line beginning with a single equals sign in the sample above) or above all other AsciiDoc content if the document title is not defined in AsciiDoc. The AsciiDoc document header ends at the first blank line. For more details about the document header, see the asciidoc:document:header.adoc documentation. Attributes may be defined elsewhere in the document, and they will be available after the definition, but they will not be available outside the document, for instance for translation to page variables.

Important

You may use include directives in the the document header. Note that the document header will end before any blank line included.

Note	If a page attribute (e.g. page-quality) is defined in the document header and the corresponding page variable (e.g. quality) is defined in the document front matter, the page attribute overides the page variable.

Caution

If a 'page-' attribute defined in the header of an AsciiDoc document is not visible to another plugin or Liquid template, you may have a plugin ordering problem. See the discussion here to learn how to fix it.

Customizing the page- prefix

The prefix identifying the attributes mapped to Jekyll page variables may be set with the asciidoc key page_attribute_prefix in _config.yml. For example,

asciidoc:
  page_attribute_prefix: ji # for "jekyll integration"

Now

= My Fabulous Page
:ji-quality: infinite

Yes, it's fabulous!

will result in the page variable quality with value infinite. A hyphen is automatically added to the value of this configuration setting if the value is non-empty (e.g, jekyll becomes jekyll-).