@alandefreitas/antora-playbook-macros-extension/README.md

Playbook Macros Extension for Antora

This allows you to use macros in your Antora playbook.

Configuration {#_configuration}
=============

npm {#_npm}
---

Install this extension

``` {.bash}
npm i -D @alandefreitas/antora-playbook-macros-extension
```

Playbook {#_playbook}
--------

Append the following in your `playbook.yaml`:

``` {.yaml}
antora:
  extensions:
    - require: '@alandefreitas/antora-playbook-macros-extension' # 
      macros: # 
        key1: value1
        key2: value2
```

-   \<1\> `npm` package name:
    `@alandefreitas/antora-playbook-macros-extension` (required)

-   \<2\> List of default macros and values (optional)

Using macros {#_using_macros}
============

Any value in the playbook can use a macro with the `${key}` syntax. The
value will be replaced by the macro value as defined by one of the
following sources:

1.  Environment variable

2.  Uppercase environment variable

3.  Asciidoc attribute

4.  Default value

5.  Predefined macros

Asciidoc attributes comes from the `asciidoc.attributes` section of the
playbook. They can also be set in the antora command line using the
`--attribute` option.

Default values are defined in the `macros` section of extension
configuration. The provide a way to define default values for macros
that are not set in any other source.

The predefined macros are:

-   `branch`: The current branch name as per
    `git rev-parse --abbrev-ref HEAD`

-   `commit-id`: The current commit hash as per `git rev-parse HEAD`