Shared attributes

To facilitate consistency across the documentation, there are shared attributes for common terms and URLs: https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc. There are also attributes related to the versions and branches that are used to build our books (for example: https://github.com/elastic/docs/blob/master/shared/versions/stack/master.asciidoc).

Books that use shared attributes files must declare a dependency on them in conf.yaml like this:

  -
    repo:   docs
    path:   shared/versions/stack/{version}.asciidoc
  -
    repo:   docs
    path:   shared/attributes.asciidoc

or

  -
    repo:   docs
    path:   shared/versions/stack/current.asciidoc
  -
    repo:   docs
    path:   shared/attributes.asciidoc

There is also a special set of attributes that are automatically created by the build process. They are labelled <repo>-root, where <repo> is the name defined at the top of the conf.yaml. For example, there is an elasticsearch-root attribute that resolves to the root path of the Elasticsearch repo. Please use these root attributes or define es-repo-dir, for example, rather than relying on intrinsic attributes like {docdir} and {asciidoc-dir}. The instrinsic attributes are problematic when you re-use files in different source file paths.

If books don’t use shared attributes files, the attributes generally appear at the beginning of the book, under the title. For example:

= My Book Title

:branch: master
:ref:    https://www.elastic.co/guide/en/elasticsearch/reference/{branch}

Here is a link to the {ref}/search.html[search page]