= Docs HOWTO

include::{docs-root}/shared/versions/stack/current.asciidoc[] include::{docs-root}/shared/attributes.asciidoc[]

== Conditions of use

This documentation build process is provided to the public purely for the purpose of testing documentation changes before submitting pull requests to the appropriate Elastic repository.

The documents produced by this build process may be published only on https://www.elastic.co. They may not be published in any other form or on any other website without explicit permission.

[[setup]] == Getting started

[discrete] == Requirements

You'll need the following installed:

• Python (Python 3 preferred, but Python 2 will probably be fine)
• Docker

[discrete] == Cloning the repository

Clone the docs repository with:

[source,bash]

git clone [email protected]:elastic/docs.git

[discrete] == Building this README

You can test that everything is working correctly by building this README as follows:

[source,bash]

cd docs/ ./build_docs --doc README.asciidoc --open

This should convert README.asciidoc into HTML and open it in your browser.

[[build]] = Building documentation

[partintro]

The build_docs executable can be used to build the documentation from a locally checked out repository, or to build all the documentation that will be uploaded to the website.

[[local]] == For a local repo

When you are making changes to documentation in a locally checked out repository, and you want to check that they are building correctly, use build_docs with the --doc parameter to generate the HTML version of the docs:

[source,bash]

cd path/to/your/repo ~/path/to/docs/repo/build_docs --doc path/to/index.asciidoc

Each Elastic project may need its own documentation book build command. https://github.com/elastic/docs/blob/master/doc_build_aliases.sh[`doc_build_aliases.sh`] provides simplified aliases and the build commands for each book. For example, if you want to build Elasticsearch reference document, please refer to https://github.com/elastic/docs/blob/master/doc_build_aliases.sh#L12[Elasticsearch section] in https://github.com/elastic/docs/blob/master/doc_build_aliases.sh[`doc_build_aliases.sh`] file.

=== Specifying a different output dir

By default, the HTML docs are generated in ./html_docs. You can change the output directory with the --out parameter:

[source,bash]

build_docs --doc path/to/index.asciidoc --out output/dir/

WARNING: The output/dir/ will be deleted and recreated, so don't point it at a directory that contains anything you are fond of.

=== Viewing the docs

To view the generated docs in your web browser immediately after the build has finished, use the --open parameter:

[source,bash]

build_docs --doc path/to/index.asciidoc --open

=== Single- or multi-page

By default, the build process generates an HTML file per part/chapter/section. To generate all of the docs in a single file instead, use the --single parameter:

[source,bash]

build_docs --doc path/to/index.asciidoc --single

And if you want a table of contents added at the beginning of the single page output, add the --toc parameter:

[source,bash]

build_docs --doc path/to/index.asciidoc --single --toc

NOTE: The multi-page output always contains tables-of-content where appropriate.

=== Chunking in the right place

Before Christmas 2019 we built all of the docs using https://tdg.docbook.org/tdg/4.5/[docbook] which is designed to generate HTML, PDFs, and physical books. In the past this was useful because the Definitive Guide is both HTML and a physical book. But now we only really make HTML. And docbook is very slow and difficult to customize. So we removed it from our build process and instead generate HTML directly from the Asciidoc files.

But we still have some docbook concepts hanging around because we have tons of Asciidoc files written with docbook in mind. Thus we still use docbook's concept of "chunking".

By default, each part (= Part Title) and chapter (== Chapter Title) is "chunked" into a separate HTML file. However, for most of our books, this results in enormous pages. So we mostly chunk at the first section level (=== Section One Title). This behaviour is specified in the https://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`] file, but must also be specified on the command line when building a single book:

[source,bash]

build_docs --doc path/to/index.asciidoc --chunk 1

NOTE: If you leave out the --chunk flag we'll use the default chunking.

[[alternative_languages]] === Alternative languages for examples

The build supports finding "alternative languages" for examples that allows users to specify their preferred language or client. You can do this by passing --alternatives to the build like:

[source,bash]

cd docs/ ./build_docs --doc README.asciidoc --open
--alternatives console:js:integtest/readme_examples/js
--alternatives console:csharp:integtest/readme_examples/csharp

[[website]] == Building all of the Elastic docs

Building all of the docs runs a link checker to validate cross-document links. While it isn't generally necessary, if you know the book you are working on has links to/from other books, you can build with --all to validate the links.

NOTE: To build everything, you must have access to all of the repositories referenced in conf.yaml. If you don't have the required access privileges, an error will occur during the cloning phase.

To check links before you merge your changes:

. Make sure you have the branch with your changes checked out. . Specify the branch you are targeting and the directory that contains your local clone with the --sub_dir option. For example, if you are working on changes that will be merged into the master branch of the elasticsearch repo, run: + [source,bash]

./docs/build_docs --all --target_repo [email protected]:elastic/built-docs.git
--open --keep_hash --sub_dir elasticsearch:master:./elasticsearch

NOTE: If there are no outstanding changes in the elasticsearch directory then this will build against the result of merging the last successful docs build and the contents of elasticsearch. If there are outstanding changes then it'll just build against the contents of elasticsearch.

To run a full build to mimic the website build, omit the --sub_dir and --keep_hash options:

[source,bash]

./build_docs --all --target_repo [email protected]:elastic/built-docs.git --open

Running a full build for the first time can be slow (60 mins+) as the build needs to:

• clone each repository
• build the docs for each branch

Subsequent runs will pull any changes to the repos and only build the branches that have changed.

[[pr-checks]] == Previewing the Elastic docs in pull requests

In most Elastic repositories, when you open a pull request that affects the documentation, it calculates which books are affected and creates a PR check to build them.

If you need to re-run the check, add a comment like this:

[source,bash]

@elasticmachine run docs build

or

[source,bash]

@elasticmachine, run elasticsearch-ci/docs

To force all versions of the documentation to be rebuilt (not just the calculated subset), add a comment like this:

[source,bash]

@elasticmachine, run elasticsearch-ci/docs rebuild

[[config]] == Adding new docs or new branches

The documentation that appears on the http://www.elastic.co/guide website is controlled by the https://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`] file in the docs repo.

You can add a new repository under the repos section, if it doesn't already exist, and you can add a new "book" under the contents section.

Each book contains a list of branches and we build a separate copy of each book for each of those branches. There is also a current branch which gets special treatment. When we fork a branch like 7.x or 7.9 we typically add it to the list of branches so we immediately start building docs for it while we're actively developing against it. When we release a new minor or major version we update the current branch to point to that branch.

NOTE: At this point changing current requires a full "rebuild" which we do by logging into the docs https://elasticsearch-ci.elastic.co/view/Docs/job/elastic+docs+master+build/[build] clicking the "Build with Parameters" link, checking the "rebuild" option, and then starting the build.

Each book may optionally contain a list of live branches. If the list is specified only branches that are in it are considered "living" and books that are not in the list will get a message at the top of each page saying that we don't plan to release any more bug fixes or actively maintain the docs for that branch.

If you want a branch to have a different "version" name (for instance, if you want to build a version called "4.2" but have it build out of a branch called "branch-for-4.2"), you can put {branch-for-4.2: 4.2} as an entry in the branches list. Everywhere else in conf.yaml, continue to use branch-for-4.2.

[[asciidoc-guide]] = Asciidoc Guide

[partintro]

Asciidoc is a powerful markup language that is easy to read as plain text.

Below I include most of the Asciidoc syntax that you will need. For more, you can take a look at the https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual], or the http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoc Syntax Quick Reference].

[[structure]] == Basic book structure

Asciidocs can be built as a book, article, manpage etc. All our docs are built as a book, and thus follow the layout for books. The most basic structure is as follows:

[source,asciidoc]

= Book title // level 0

== Chapter title // level 1

=== Section title // level 2

==== Section title // level 3

===== Section title // level 4

Usually this structure will be sufficient for most of your documentation needs. More complicated "books", such as the {ref}[Elasticsearch reference docs], however, require a few additional elements, described on the following pages.

=== Filenames

By default, each chapter will generate a new chunk or HTML file. You can control the name of the file by giving the header an ID, as follows:

[source,asciidoc]

[[intro-to-xyz]] == Intro to XYZ

This chapter would then be written to a file called intro-to-xyz.html. If no ID is provided, then a filename will be auto-generated. See <> for more.

These IDs are also used to link to sections within each book. See <>.

TIP: For search engine optimization (SEO), make sure the keywords you use in the ID match keywords used in the topic title. For example, if the topic is called "Install XYZ", use +[[install-xyz]]+ for the topic ID.

=== TOC titles

By default, the link text used in the generated TOC is based on the title of each file. You can provide an abbreviated title using a titleabbrev in one of two ways:

. You should add a titleabbrev attribute to the section: +

[source,asciidoc]

[id=intro_to_xyz,titleabbrev=" XYZ Intro"] == Intro to XYZ

Words.

--

. You may use the pass block but it isn't recommended: +

[source,asciidoc]

== Intro to XYZ ++++ XYZ Intro ++++

Words.

--

[[multi-part]] == Multi-part books

Books may also be divided into multiple parts, which are indicated with level 0 headers:

[source,asciidoc]

= Book title // level 0

= Part title // level 0

== Chapter title // level 1

=== Section title // level 2

... etc ...

Each part also creates a new chunk or HTML file.

=== Part intro

A part may include text before the first chapter, but it must be marked with [partintro] in order to be valid:

[source,asciidoc]

= Book title // level 0

= Part one // level 0

[partintro] A paragraph introducing this Part

== Chapter title // level 1

... etc ...

Longer partintro blocks should be wrapped in an https://asciidoctor.org/docs/user-manual/#open-blocks[_open block_] which starts and ends with two dashes: --:

["source","asciidoc",subs="attributes,callouts,macros"]

= Part two // level 0

[partintro] .A partintro title pass:[--] <1> This section may contain multiple paragraphs.

[discrete] == A header should use [discrete]

Everything up to the closing -- marker will be considered part of the partintro. pass:[--] <1>

== Chapter title // level 2

... etc ...

<1> The open block delimiters

[[optional-sections]] == Optional sections

Books may include other sections such as a preamble, a preface, a glossary or appendices.

=== Preamble

[source,asciidoc]

= Book title // level 0

.Optional preamble title Preamble text...

---

=== Preface and Appendix

[source,asciidoc]

[preface] = Preface title // level 0

=== Preface header // level 2 <1>

= Part one // level 0

and

[source,asciidoc]

[appendix] = Appendix title // level 0

=== Appendix header // level 2 <1>

<1> Any headers in the appendix or in the preface start out-of-sequence at level 2, not at level 1.

[[section]] === Glossary

[source,asciidoc]

[glossary] = Glossary title // level 0

[glossary] Term one:: Defn for term one

Term two:: Defn for term two

[NOTE]

The two [glossary] elements above have different purposes:

• The first marks this section of the document as a glossary, to be included in the table of contents
• The second marks the definitions list as type glossary ==================================

=== Also see

If you need to use some of these more advanced structural elements, have a look at the example of a multi-part book included in this repo in https://github.com/asciidoc/asciidoc/blob/master/doc/book-multi.txt[`book-multi.txt`].

[[paragraphs]] == Paragraphs

A paragraph consists of multiple lines of text which start in the left hand column:

[source,asciidoc]

This is a paragraph even though it contains line breaks.

This is a second paragraph.

=== Paragraph titles

Like most elements, a paragraph can have a title:

.Paragraph with a title

[source,asciidoc]

.Paragraph title Text of my paragraph

.Paragraph title Text of my paragraph

[[admon-paras]] === Admonition paragraphs

A paragraph which starts with TIP:, NOTE:, IMPORTANT:, WARNING: or CAUTION: is rendered as an admonition paragraph, eg:

[source,asciidoc]

NOTE: Compare admonition paragraphs with <>.

This renders as:

NOTE: Compare admonition paragraphs with <>.

=== Literal paragraphs

Literal paragraphs, which are rendered as <pre> blocks without any source highlighting, must be indented:

.A literal paragraph

[source,asciidoc]

.Optional title

This para must
be indented

---

.Optional title This para must be indented

See also <> for blocks with syntax highlighting.

[[text]] == Inline text

Inline text can be formatted as follows:

[horizontal] ifdef::env-github[] _emphasis_:: emphasis *bold*:: bold `mono':: mono ^superscript^:: ^superscript^ ~subscript~:: subscript endif::[] ifndef::env-github[] +_emphasis_+:: emphasis +*bold*+:: bold +`mono'+:: mono +^superscript^+:: ^superscript^ +~subscript~+:: subscript endif::[]

These formatting characters expect to adjoin whitespace or common punctuation characters. To combine bold with emphasis, double up the quotes (ie use __ and **):

.Combining bold and emphasis

[source,asciidoc]

This example co__mbines__ bold and emphasis

This example co__mbines__ bold and emphasis.

Unwanted quotes can be escaped with a \ character.

=== Replacement characters

Certain runs of ASCII characters are replaced as follows:

[horizontal] ifdef::env-github[] --:: -- (em dash) ...:: ... ->:: -> <&#x2d;:: <- =>:: => <&#x3d;:: <= (C):: (C) (TM):: (TM) (R):: (R) endif::[] ifndef::env-github[] +--+:: -- (em dash) +...+:: ... +->+:: -> +<-+:: <- +=>+:: => +<=+:: <= +(C)+:: (C) +(TM)+:: (TM) +(R)+:: (R) endif::[]

[[shared-attributes]] == 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 https://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`] like this:

[source,yaml]

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

---

or

[source,yaml]

• 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 https://github.com/elastic/docs/blob/master/conf.yaml[`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:

.Using book-scoped attributes for cross-document linking

[source,asciidoc]

= 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]

==================================

[[linking]] == Linking

You can link to any block in the document that has an ID -- an identifier before the block which is wrapped in double square brackets: [[ID]]

[source,asciidoc]

[[para-id]] This paragraph can be linked to using the ID para-id.

When you need to combine an ID with a style, you can either specify each on a separate line:

[source,asciidoc]

[[note-id]] [NOTE]

This note can be linked to using the ID note-id.

---

or in one line:

[source,asciidoc]

["NOTE",id="note-id"] <1>

This note can be linked to using the ID note-id.

---

<1> In the one line format, the NOTE must be enclosed in double quotes.

Both of the above render as:

["NOTE",id="note-id"]

This note can be linked to using the ID note-id.

The ID is added to the HTML document as an <a> anchor and, as explained in <>, the ID is used as the filename for sections which are chunked -- written to separate HTML files.

=== Internal links

You can link to any ID within a document using double angle brackets:

.Links with default link text

[source,asciidoc]

• <>
• <>

---

• <>
• <> ==================================

It will use the title associated with each ID as the link text.

Alternative link text can be provided as a second parameter inside the angle brackets:

.Links with custom link text

[source,asciidoc]

See the <<note-id,note about IDs>>.

See the <<note-id,note about IDs>>.

==================================

=== External links

Links to external websites can just be added as normal inline text, optionally with custom link text in square brackets:

.External links

[source,asciidoc]

See http://github.com/elastic or http://github.com/elastic/docs[this repository]

See http://github.com/elastic or http://github.com/elastic/docs[this repository]

==================================

The existence of external links is not confirmed by the build process.

=== Cross document links

Links to other Elastic books are essentially the same as external links. However, for conciseness and maintainability, you should use an attribute to represent the absolute URL of the docs.

If possible, use attributes defined in the https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc[shared attributes file] to resolve links:

.Using shared attributes for cross-document linking

[source,asciidoc]

= My Book Title

Use this if your repo is versioned with the Elastic stack:

\include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]

Or use this to alway point to the most recent version of the stack

\include::{docs-root}/shared/versions/stack/current.asciidoc[]

Either way, you'll want to include a reference to the attributes file

which builds the links from the versions.

\include::{docs-root}/shared/attributes.asciidoc[]

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

==================================

The main benefit of using attributes for cross document links is that, when the docs for an old version contain links that no longer exist in the current branch, you can update all the links in the document to point to the older version, by just updating a single attribute.

Cross document links are checked when build_docs is run with the --all parameter. See <>.

[[lists]] == Lists

=== Bullet points

Bullet point lists are written using asterisks:

.Bullet points

[source,asciidoc]

.Optional title

• Point
• Point ** Sub-point *** Sub-sub-point
• [ ] TODO
• [x] Done
• A point can have multiple paragraphs

But use a + instead of an empty line between paras.

An empty line signifies the end of the list.

.Optional title

• Point
• Point ** Sub-point *** Sub-sub-point
• [ ] TODO
• [x] Done
• A point can have multiple paragraphs

But use a + instead of an empty line between paras

An empty line signifies the end of the list.

For more information, see https://asciidoctor.org/docs/user-manual/#unordered-lists

=== Ordered lists

Ordered lists use . instead of *, and will alternate between numbers and letters automatically:

.An ordered list

[source,asciidoc]

.Optional title . foo .. bar ... baz .... balloo

.Optional title . foo .. bar ... baz .... balloo

For more information, see https://asciidoctor.org/docs/user-manual/#ordered-lists

=== Definition lists

Definition lists are used to define terms. The term must be followed by a double colon :: eg:

.A vertical definition list

[source,asciidoc]

term one:: Definition for term one term two:: Can start on the next line term three:: A definition can have multiple + paragraphs, but use + to separate them

term four::: Definitions can be nested by adding more colons term five:: A definition can even include lists: * point one * point two

term one:: Definition for term one term two:: Can start on the next line term three:: A definition can have multiple + paragraphs, but use + to separate them

term four::: Definitions can be nested by adding more colons term five:: A definition can even include lists: * point one * point two

[[horizonta-defn-list]] === Horizontal definition lists

Often definition lists are better rendered horizontally, eg:

.A horizontal definition list

[source,asciidoc]

[horizontal] term one:: Definition for term one term two:: Can start on the next line term three:: A definition can have multiple + paragraphs, but use + to separate them

term four::: Definitions can be nested by adding more colons term five:: A definition can even include lists: * point one * point two

[horizontal] term one:: Definition for term one term two:: Can start on the next line term three:: A definition can have multiple + paragraphs, but use + to separate them

term four::: Definitions can be nested by adding more colons term five:: A definition can even include lists: * point one * point two

[[blocks]] == Blocks

Blocks are used for special blocks of content, such as <>, <>, <> and <>.

Blocks are delimited with a start and end line which uses the same characters, like =====.

[[code-blocks]] === Code blocks

Code blocks are rendered as <pre> blocks, and use syntax highlighting, eg:

.A code block

[source,asciidoc]

.Optional title [source,js]

{ "query": "foo bar" }

--

.Optional title [source,js]

{ "query": "foo bar" }

==================================

IMPORTANT: If you don't specify the source language then the generated HTML is quite different so, in general, you should specify a language. We use the language as a hint for the syntax highlighter. See files in this repository names lang-*.js for information.

=== Callouts

Code blocks can use callouts to add an explanatory footnote to a particular line of code:

.Code block with callouts

[source,asciidoc]

[source,js]

{ "query": "foo bar" <1> }

<1> Here's the explanation

[source,js]

{ "query": "foo bar" <1> }

<1> Here's the explanation

[[copy-as-curl]] === Copy as cURL/View in Console

Code blocks can be followed by a "Copy as cURL" link which will convert the snippet into a sequence of calls to the ubiquitous https://curl.haxx.se/[cURL] tool that work in the bash shell and copy it to the clipboard. Similarly, if the target of the snippet is Elasticsearch we also add a "View in Console" link will open the code snippet in Console.

You enable it by setting the "language" of the snippet to a supported language. The options are "console" for Elasticsearch, "kibana" for Kibana, "ess" for Elasticsearch Service (Elastic's official SaaS offering), and "ece" for Elastic Cloud Enterprise.

For Elasticsearch do this:

.Code block with "Copy as cURL" and "View in Console" link for Elasticsearch

[source,asciidoc]

[source,console]

GET /_search { "query": "foo bar" <1> }

<1> Here's the explanation

==================================

Which renders as:

[source,console]

GET /_search { "query": "foo bar" <1> }

<1> Here's the explanation

NOTE: In older branches you'll see // CONSOLE after the snippet to trigger this behavior. That is deprecated.

For Kibana do this:

.Code block with "Copy as cURL" link for Kibana

[source,asciidoc]

[source,kibana]

GET /

--

Which renders as:

[source,kibana]

GET /

For Elasticsearch Service do this:

.Code block with "Copy as cURL" link for Elasticsearch Service

[source,asciidoc]

[source,ess]

GET /

--

Which renders as:

[source,ess]

GET /

For Elastic Cloud Enterprise do this:

.Code block with "Copy as cURL" link for Elastic Cloud Enterprise

[source,asciidoc]

[source,ece]

GET /

--

Which renders as:

[source,ece]

GET /

==== Responses

If Console requests are followed by a "response" then it should be written with the language set to console-response. That will allow <<alternative_languages, alternative examples>> to find the responses. Like this:

[source,asciidoc]

[source,console-result]

{ "hits": { "total": { "value": 0, "relation": "eq" }, "hits": [] } }

--

Which should render as:

[source,console-result]

{ "hits": { "total": { "value": 0, "relation": "eq" }, "hits": [] } }

[[admon-blocks]] === Admonition blocks

Admonition blocks are much the same as <>, except that they can be longer and contain more than just a paragraph. For instance:

[source,asciidoc]

[NOTE]

This note contains a list:

• foo
• bar
• baz

and some code

[source,js]

{ "query": "foo bar"}

=========================

This renders as:

[NOTE]

This note contains a list:

• foo
• bar
• baz

and some code

[source,js]

{ "query": "foo bar"}

=========================

[[sidebars]] === Sidebars

Sidebars are used to highlight a block of content that is outside the usual flow of text:

[source,asciidoc]

.Optional title

---

So why does the bulk API have such a funny format? Sit down and I'll tell you all about it!

---

---

.Optional title

---

So why does the bulk API have such a funny format? Sit down and I'll tell you all about it!

---

[[examples]] === Example blocks

Example blocks contain normal text which is used as an example. The title, if any, is labelled as an example and numbered:

[source,asciidoc]

.My first example

Text explaining the first example.

.My second example

Text explaining the second example.

---

This renders as:

.My first example

Text explaining the first example.

.My second example

Text explaining the second example.

CAUTION: The === and --- delimiters can sometimes be confused with a header, resulting in an error. To resolve this, add newlines between the delimiter and the content before and after it.

Examples can be made collapsible:

[source,asciidoc]

[%collapsible] .An example

Lots of text can go in here.

---

Which renders as:

[%collapsible] .An example

Lots of text can go in here.

[[includes]] == Including files

For long documentation, you probably want to break up the Asciidoc files into smaller units, and just include them where appropriate:

[source,asciidoc]

\include::myfolder/mydoc.asciidoc[]

Paths are relative to the file which contains the include statement.

[[cross-repo-includes]] === Across repositories

If you have to include files in a different repository then use its -root attribute to locate the files:

[source,asciidoc]

\include::{elasticsearch-root}/docs/foo.asciidoc[]

Books that reference another repository should register that reference in https://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`].

[source,yaml]

• repo: elasticsearch path: docs/foo.asciidoc

---

The path should be as specific as possible because we skip rebuilding books if changes to the referenced repository don't change the referenced path.

[[changes]] == Additions and deprecations

Documentation is built for various branches, eg 0.90, 1.00, master. However, we release versions 0.90.0, 0.90.1, etc, which are all based on the 0.90 branch.

When adding new functionality to a branch, or deprecating existing functionality, you can mark the change as added, coming or deprecated. Use coming when the addition is in an as yet unreleased version of the current branch, and added when the functionality is already released.

The update_versions.pl script can be used to change coming notices to added notices when doing a new release, and can also be used to remove added, coming and deprecated notices completely.

=== Inline notifications

Use inline notifications for small changes, such as the addition or deprecation of individual parameters.

[source,asciidoc]

[horizontal] foo.bar:: Does XYZ. added:[0.90.4] foo.bar:: Does XYZ. coming:[0.90.4] foo.baz:: Does XYZ. deprecated:[0.90.4]

[horizontal] foo.bar:: Does XYZ. added:[0.90.4] foo.bar:: Does XYZ. coming:[0.90.4] foo.baz:: Does XYZ. deprecated:[0.90.4]

You can also include details about additional notes in the notifications which show up when the user hovers over it:

[source,asciidoc]

[horizontal] foo.bar:: Does XYZ. added:[0.90.4,Replaces foo.baz] foo.bar:: Does XYZ. coming:[0.90.4,Replaces foo.baz] foo.baz:: Does XYZ. deprecated:[0.90.4,Replaced by foo.bar]

[horizontal] foo.bar:: Does XYZ. added:[0.90.4,Replaces foo.baz] foo.bar:: Does XYZ. coming:[0.90.4,Replaces foo.baz] foo.baz:: Does XYZ. deprecated:[0.90.4,Replaced by foo.bar]

[NOTE]

If the details include a comma, you must use quotation marks. For example: [source,asciidoc]

deprecated::[1.1.0,"Span started automatically by <<apm-start-span,apm.startSpan()>>"]

====

=== Section notifications

Use section notifications to mark an entire chapter or section as added/deleted. Notifications can just refer to the version in which the change was made:

[source,asciidoc]

==== New section

added::[0.90.4]

Text about new functionality...

==== New section not yet released

coming::[0.90.9]

Text about new functionality...

==== Old section

deprecated::[0.90.4]

Text about old functionality...

==== New section

added::[0.90.4]

Text about new functionality...

==== New section not yet released

coming::[0.90.9]

Text about new functionality...

==== Old section

deprecated::[0.90.4]

Text about old functionality...

[[with_details]] ==== With details...

Or they can include extra text, including more Asciidoc markup:

[source,asciidoc]

[[new-section]] ==== New section

added::[0.90.4,Replaces foo.bar. See <>]

Text about new functionality...

[[coming-section]] ==== New section not yet released

coming::[0.90.9,Replaces foo.bar. See <>]

Text about new functionality...

[[old-section]] ==== Old section

deprecated::[0.90.4,Replace by foo.baz. See <>]

Text about old functionality...

[[new-section]] ==== New section

added::[0.90.4,Replaces foo.bar. See <>]

Text about new functionality...

[[old-section]] ==== Old section

deprecated::[0.90.4,Replace by foo.baz. See <>]

Text about old functionality...

[[experimental]] == Beta, Dev, and Experimental

APIs or parameters that are in beta, in development, or experimental can be marked as such, using markup similar to that used in <>.

In the block format, you have the option of adding a related GitHub issue link. If both custom text and a GitHub link are provided, the GitHub link must be provided second. If it's supported in your repo, you can use the {issue} attribute in place of the GitHub issue link.

=== Using the beta admonition

[source,asciidoc]

[[new-beta-feature]] === New beta feature

beta::[]

beta::[https://github.com/elastic/docs/issues/505]

beta::[{issue}505]

beta::["Custom text goes here."]

beta::["Custom text goes here.",https://github.com/elastic/docs/issues/505]

beta::["Custom text goes here.",{issue}505]

Text about new feature...

[[old-beta-feature]] === Established feature

This feature has been around for a while, but we're adding a new parameter that's in beta:

established_param:: This param has been around for ages and won't change.

beta_param:: beta:[] This param is in beta and may change in the future.

beta_param:: beta:["Custom text goes here."] This param is in beta and may change in the future.

=== Using the dev admonition

[source,asciidoc]

[[new-dev-feature]] === New feature in development

dev::[]

dev::[https://github.com/elastic/docs/issues/505]

dev::[{issue}505]

dev::["Custom text goes here."]

dev::["Custom text goes here.",https://github.com/elastic/docs/issues/505]

dev::["Custom text goes here.",{issue}505]

Text about feature in development...

[[old-dev-feature]] === Established feature

This feature has been around for a while, but we're adding a new parameter that's in development:

established_param:: This param has been around for ages and won't change.

dev_param:: dev:[] This param is in development and may change in the future.

dev_param:: dev:["Custom text goes here."] This param is in development and may change in the future.

=== Using the experimental admonition

[source,asciidoc]

[[new-feature]] === New experimental feature

experimental::[]

experimental::[https://github.com/elastic/docs/issues/505]

experimental::[{issue}505]

experimental::["Custom text goes here."]

experimental::["Custom text goes here.",https://github.com/elastic/docs/issues/505]

experimental::["Custom text goes here.",{issue}505]

Text about new feature...

[[old-feature]] === Established feature

This feature has been around for a while, but we're adding a new experimental parameter:

established_param:: This param has been around for ages and won't change.

experimental_param:: experimental:[] This param is experimental and may change in the future.

experimental_param:: experimental:["Custom text goes here."] This param is experimental and may change in the future.

[[images]] == Images

Any images you want to include should be saved in a folder in your repo, and included using a path relative to the document where the image:: statement appears.

[source,asciidoc]

[[cat]] .A scaredy cat image::resources/readme/cat.jpg[Alt text]

A link to <>

[[cat]] .A scaredy cat image::resources/readme/cat.jpg[Alt text]

A link to <>.

=== Width and height

The width and/or height of the image can be specified in pixels or as a percentage:

[source,asciidoc]

image::resources/readme/cat.jpg["Alt text",width=50] image::resources/readme/cat.jpg["Alt text",width="20%"]

image::resources/readme/cat.jpg["Alt text",width=50] image::resources/readme/cat.jpg["Alt text",width="20%"]

=== Alignment

Images are left-aligned by default, but they can be centred or right-aligned:

[source,asciidoc]

image::resources/readme/cat.jpg["Alt text",width=100,align="left"] image::resources/readme/cat.jpg["Alt text",width=100,align="right"] image::resources/readme/cat.jpg["Alt text",width=100,align="center"]

image::resources/readme/cat.jpg["Alt text",width=100,align="left"] image::resources/readme/cat.jpg["Alt text",width=100,align="right"] image::resources/readme/cat.jpg["Alt text",width=100,align="center"]

=== Screenshots

Screenshots get extra margins and a box-shadow:

[role="screenshot"] image::resources/readme/screenshot.png[A screenshot example]

You can activate it with:

[source,asciidoc]

[role="screenshot"] image::resources/readme/screenshot.png[A screenshot example]

[[svgs]] === SVGs

SVGs are also supported. Just use them like you would any other image:

[source,asciidoc]

image::resources/readme/example.svg[An example svg]

Which looks like:

image::resources/readme/example.svg[An example svg]

[[image-links]] === Image links

You can add relative or absoloute links to your images with the following syntax:

[source,asciidoc]

image:./images/dynamic-config.svg[link=configuration.html#configuration-dynamic]

Using internal link attributes is also supported, but the image must be inside the internal link syntax. It's important to add a space on each side of the image tag. Without spaces, the image will not render.

[source,asciidoc]

<<configuration-dynamic, image:./images/dynamic-config.svg[] >>

[[videos]] == Videos

You can add a vimeo hosted video with Asciidoctor's https://asciidoctor.org/docs/user-manual/#video[video] tag:

[source,asciidoc]

video::366852847[vimeo,height=480]

NOTE: You should set height or else the video will be tiny. You shouldn't set width because Vimeo will preserve the aspect ratio for you.

Which renders like this:

video::366852847[vimeo,height=480]

[[tables]] == Tables

Our CSS for tables isn't great at the moment so it's almost always better to use <> instead, but if you really want to use tables, you can read about them https://asciidoctor.org/docs/user-manual/#tables[here].

[[edit_me]] == Edit links

We automatically generate edit links for most sections to make it easier for folks to contribute simple fixes and to help folks find the asciidoc file that generated a particular section. It should appear next to every title-like thing.

Books built with Asciidoctor will automatically pick the correct url for all files and by default doesn't support overriding edit_url. This is mostly a good thing because the overridden edit_urls were out of date in many cases.

Some books override edit_url because the asciidoc files in them are not authoritative. In that case they set edit_url to the "real" place to make the change. Sometimes this is another repository and sometimes it is some code that generates the asciidoc files. These books should add respect_edit_url_overrides to their config. While it isn't required for AsciiDoc it is required for Asciidoctor.

[[chunking]] == Controlling chunking

In <>, we said that each part or chapter generates a new chunk or HTML file. For more complex documentation, you may want the first level of ++section++s to also generate new chunks.

For example:

[source,asciidoc]

= 1st-level page // part

== 2nd-level child page // chapter

=== 3rd-level child page // section level 1

=== Another 3rd-level child page // section level 1

... etc ...

This renders in the TOC as follows:

image::resources/readme/chunking-toc.png[TOC screenshot]

=== Enabling section chunking

To enable section chunking when building docs in a <<local,local repository>>, pass the --chunk parameter:

[source,bash]

build_docs --doc path/to/index.asciidoc --chunk 1

To enable section chunking when building docs <<website,for the website>>, add chunk: 1 to the https://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`] file in the docs repo.

[source,yaml]

contents: - title: Elasticsearch reference prefix: elasticsearch/reference repo: elasticsearch index: docs/reference/index.asciidoc chunk: 1 <1>

<1> Chunking is enabled for this book

=== Chunking selected sections

If you enable session chunking, you will probably find that you have a few short sections which you want to keep on the same page.

To do this, you can use the [discrete] marker before a section header, to indicate that what follows isn't a "real" header:

[source,asciidoc]

[[chapter-one]] == chapter // new chunk

[[section-one]] === Section one // new chunk

[discrete] [[section-two]] === Section two // same chunk

[[section-three]] === Section three // new chunk

The above would produce three HTML files, named for their IDs:

• chapter-one.html
• section-one.html which would also contain "Section two"
• section-three.html

To link to "Section two" from an external document, you would use the URL: section-one.html#section-two