Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/elastic/docs


https://github.com/elastic/docs

Last synced: 9 months ago
JSON representation

Awesome Lists containing this project

README 

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



All Elastic documentation is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License. http://creativecommons.org/licenses/by-nc-nd/4.0/



[[setup]]

== Getting started



[discrete]

== Requirements



You'll need the following installed:



* Python 3

* Docker



[discrete]

== Cloning the repository



Clone the `docs` repository with:



[source,bash]

----------------------------

git clone git@github.com: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 /full/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 the Elasticsearch Guide, refer to the

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 git@github.com: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 git@github.com: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 Guide],

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 `
`

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__mb**in**es__ bold and emphasis

----------------------------------



This example co__mb**in**es__ 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)

`...`::  ...

`->`::   ->

`<-`::   <-

`=>`::   =>

`<=`::   <=

`(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 `-root`, where `` 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]

----------------------------------

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



[[attribute-scope]]

== Attribute scope



Attributes are in-scope for the entire book unless you explicitly clear them by

setting `:!attributename:`. For example:



.Clearing an attribute

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



[source,asciidoc]

----------------------------------

:myattribute: some value

All the things on the page.

:!myattribute:

----------------------------------

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



To create page-scoped attributes, clear the attribute at the end of the 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 `` 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 <>.

----------------------------------



See the <>.



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



=== 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 `
` 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.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 "Try 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 "Try 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

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

----------------------------------

====



=== 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 Preview (experimental)



APIs or parameters that are in beta, in development, or in technical preview (formerly 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



Experimental language is deprecated.



We decided on the much less raw sounding "technical preview".



See below.



=== Using the technical `preview` admonition



[source,asciidoc]

----

[[new-feature]]

=== New feature in technical preview



preview::[]



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



preview::[{issue}505]



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



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



preview::["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 preview parameter:



`established_param`::

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



`experimental_param`::

preview:[]

This param is in technical preview and may change in the future.



`experimental_param`::

preview:["Custom text goes here."]

This param is in technical preview 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]

----

<>

----



[[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_url`s 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 <>,

pass the `--chunk` parameter:



[source,bash]

----------------------------------

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

----------------------------------



To enable section chunking when building docs <>,

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 Guide

        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`



[[tabbed-widgets]]

== Tabbed widgets



Improve the usability of your docs by adding tabbed widgets.

These handy widgets let you conditionally display content based on the selected tab.

Best of all, tabbed widgets listen to each other – all widgets on the same page and with the same `data-tab-group` will change content when any tab on the page is selected.



How do they work? I'm glad you asked.

Tabbed widgets use https://docs.asciidoctor.org/asciidoc/latest/pass/pass-block/[HTML passthrough blocks] to pass raw HTML into the build.

Because of this hack, you must use `include::` statements to render content within a tabbed widget.



Here's an example:



**`widget.asciidoc`**



[source,asciidoc]

----

++++

 <1>

  


    

            aria-controls="cloud-tab-config-agent" <3>

            id="cloud-config-agent"> <4>

      Tab #1 title

    

     <5>

      Tab #2 title

    

  


  


++++



// You must use a tagged region for Asciidoc content to render. For example:

// include::content.asciidoc[tag=central-config]



++++

  


  


++++



// You must use a tagged region for Asciidoc content to render. For example:

// include::content.asciidoc[tag=reg-config]



++++

  




++++

----

<1> Any tabbed widgets on the same page and with the same name will sync tabs when switched

<2> Only one tab should have aria-selected set to true. This tab will be selected by default

<3> The `button.aria-controls` value must match the `div.id` value of its corresponding content bucket

<4> The `button.id` value must match the `div.aria-labelledby` value of its corresponding content bucket

<5> All unselected tabs must have a `tabindex` of `-1`



**`content.asciidoc`**



[source,asciidoc]

----

// tag::central-config[]

This is where the content for tab #1 goes.

// end::central-config[]



// tag::reg-config[]

This is the content for tab #2 goes.

// end::reg-config[]

----



[[global-banners]]

== Global banners



Add a banner to every page within a book by creating a `page_header.html` file. This file must live in the root of the documentation directory (i.e. the book's `path` in `conf.yaml`) and is picked up by the doc build automatically. This file can include any valid HTML. An example can be seen https://github.com/elastic/apm-server/pull/6833/files[here].