{"id":15044312,"url":"https://github.com/elastic/docs","last_synced_at":"2025-04-14T09:00:03.175Z","repository":{"id":27833187,"uuid":"31323121","full_name":"elastic/docs","owner":"elastic","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-07T01:19:40.000Z","size":55179,"stargazers_count":254,"open_issues_count":128,"forks_count":340,"subscribers_count":389,"default_branch":"master","last_synced_at":"2025-04-07T02:11:11.424Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elastic.png","metadata":{"files":{"readme":"README.asciidoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-25T16:26:02.000Z","updated_at":"2025-04-02T16:28:32.000Z","dependencies_parsed_at":"2024-08-27T22:31:28.003Z","dependency_job_id":"8ba69d30-a328-4767-9af0-4f141d8bd283","html_url":"https://github.com/elastic/docs","commit_stats":{"total_commits":2687,"total_committers":162,"mean_commits":16.58641975308642,"dds":0.7368812802381839,"last_synced_commit":"6845db6c5ed38b0a674811f8264a2ba863fde8e5"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elastic","download_url":"https://codeload.github.com/elastic/docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852131,"owners_count":21171840,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T20:50:25.910Z","updated_at":"2025-04-14T08:59:58.153Z","avatar_url":"https://github.com/elastic.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Docs HOWTO\n\ninclude::{docs-root}/shared/versions/stack/current.asciidoc[]\ninclude::{docs-root}/shared/attributes.asciidoc[]\n\n== Conditions of use\n\nThis documentation build process is provided to the public purely for the\npurpose of testing documentation changes before submitting pull requests to\nthe appropriate Elastic repository.\n\nAll Elastic documentation is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License. http://creativecommons.org/licenses/by-nc-nd/4.0/\n\n[[setup]]\n== Getting started\n\n[discrete]\n== Requirements\n\nYou'll need the following installed:\n\n* Python 3\n* Docker\n\n[discrete]\n== Cloning the repository\n\nClone the `docs` repository with:\n\n[source,bash]\n----------------------------\ngit clone git@github.com:elastic/docs.git\n----------------------------\n\n[discrete]\n== Building this README\n\nYou can test that everything is working correctly by building\nthis README as follows:\n\n[source,bash]\n----------------------------\ncd docs/\n./build_docs --doc README.asciidoc --open\n----------------------------\n\nThis should convert `README.asciidoc` into HTML and open it\nin your browser.\n\n[[build]]\n= Building documentation\n\n[partintro]\n--\nThe `build_docs` executable can be used to build the documentation\nfrom a locally checked out repository, or to build all the\ndocumentation that will be uploaded to the website.\n--\n\n[[local]]\n== For a local repo\n\nWhen you are making changes to documentation in a locally checked\nout repository, and you want to check that they are building\ncorrectly, use `build_docs` with the `--doc` parameter to\ngenerate the HTML version of the docs:\n\n[source,bash]\n----------------------------\ncd path/to/your/repo\n~/path/to/docs/repo/build_docs --doc /full/path/to/index.asciidoc\n----------------------------\n\nEach Elastic project may need its own documentation book build command.\nhttps://github.com/elastic/docs/blob/master/doc_build_aliases.sh[`doc_build_aliases.sh`] provides simplified aliases and the build commands for each book.\nFor example, if you want to build the Elasticsearch Guide, refer to the\nhttps://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.\n\n=== Specifying a different output dir\n\nBy default, the HTML docs are generated in `./html_docs`. You can\nchange the output directory with the `--out` parameter:\n\n[source,bash]\n----------------------------\nbuild_docs --doc path/to/index.asciidoc --out output/dir/\n----------------------------\n\nWARNING: The `output/dir/` will be deleted and recreated, so don't\npoint it at a directory that contains anything you are fond of.\n\n=== Viewing the docs\n\nTo view the generated docs in your web browser immediately after\nthe build has finished, use the `--open` parameter:\n\n[source,bash]\n----------------------------\nbuild_docs --doc path/to/index.asciidoc --open\n----------------------------\n\n=== Single- or multi-page\n\nBy default, the build process generates an HTML file per\npart/chapter/section.  To generate all of the docs in a single\nfile instead, use the `--single` parameter:\n\n[source,bash]\n----------------------------\nbuild_docs --doc path/to/index.asciidoc --single\n----------------------------\n\nAnd if you want a table of contents added at the beginning\nof the single page output, add the `--toc` parameter:\n\n[source,bash]\n----------------------------\nbuild_docs --doc path/to/index.asciidoc --single --toc\n----------------------------\n\nNOTE: The multi-page output always contains tables-of-content\nwhere appropriate.\n\n=== Chunking in the right place\n\nBefore Christmas 2019 we built all of the docs using\nhttps://tdg.docbook.org/tdg/4.5/[docbook] which is designed to generate\nHTML, PDFs, and physical books. In the past this *was* useful because the\nDefinitive Guide is both HTML and a physical book. But now we only really\nmake HTML. And docbook is very slow and difficult to customize. So we\nremoved it from our build process and instead generate HTML directly from\nthe Asciidoc files.\n\nBut we still have some docbook concepts hanging around because we have tons\nof Asciidoc files written with docbook in mind. Thus we still use docbook's\nconcept of \"chunking\".\n\nBy default, each _part_ (`= Part Title`) and _chapter_ (`== Chapter Title`) is\n\"chunked\" into a separate HTML file. However, for most of our books, this\nresults in enormous pages. So we mostly chunk at the first _section_ level\n(`=== Section One Title`). This behaviour is specified in the\nhttps://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`]\nfile, but must also be specified on the command line when building a single\nbook:\n\n[source,bash]\n----------------------------\nbuild_docs --doc path/to/index.asciidoc --chunk 1\n----------------------------\n\nNOTE: If you leave out the `--chunk` flag we'll use the default chunking.\n\n[[alternative_languages]]\n=== Alternative languages for examples\n\nThe build supports finding \"alternative languages\" for examples that allows\nusers to specify their preferred language or client. You can do this by passing\n`--alternatives` to the build like:\n\n[source,bash]\n----------------------------\ncd docs/\n./build_docs --doc README.asciidoc --open \\\n    --alternatives console:js:integtest/readme_examples/js \\\n    --alternatives console:csharp:integtest/readme_examples/csharp\n----------------------------\n\n[[website]]\n== Building all of the Elastic docs\n\nBuilding all of the docs runs a link checker to validate cross-document links.\nWhile it isn't generally necessary, if you know the book you are working on\nhas links to/from other books, you can build with `--all` to validate\nthe links.\n\nNOTE: To build everything, you must have access to all of the repositories\nreferenced in `conf.yaml`. If you don't have the required access privileges,\nan error will occur during the cloning phase.\n\nTo check links before you merge your changes:\n\n. Make sure you have the branch with your changes checked out.\n. Specify the branch you are targeting and the directory that contains your local clone\n  with the `--sub_dir` option. For example, if you are working on changes that will be merged\n  into the master branch of the `elasticsearch` repo, run:\n+\n[source,bash]\n----------------------------\n./docs/build_docs --all --target_repo git@github.com:elastic/built-docs.git \\\n                  --open --keep_hash --sub_dir elasticsearch:master:./elasticsearch\n----------------------------\n\nNOTE: If there are no outstanding changes in the `elasticsearch` directory\n      then this will build against the result of merging the last successful\n      docs build and the contents of `elasticsearch`. If there *are*\n      outstanding changes then it'll just build against the contents of\n      `elasticsearch`.\n\nTo run a full build to mimic the website build, omit the `--sub_dir` and\n`--keep_hash` options:\n\n[source,bash]\n----------------------------\n./build_docs --all --target_repo git@github.com:elastic/built-docs.git --open\n----------------------------\n\nRunning a full build for the first time can be slow (60 mins+) as the build needs to:\n\n* clone each repository\n* build the docs for each branch\n\nSubsequent runs will pull any changes to the repos and only build the\nbranches that have changed.\n\n[[pr-checks]]\n== Previewing the Elastic docs in pull requests\n\nIn 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.\n\nIf you need to re-run the check, add a comment like this:\n\n[source,bash]\n----------------------------\n@elasticmachine run docs build\n----------------------------\n\nor\n\n[source,bash]\n----------------------------\n@elasticmachine, run elasticsearch-ci/docs\n----------------------------\n\nTo force *all* versions of the documentation to be rebuilt (not just the calculated subset), add a comment like this:\n\n[source,bash]\n----------------------------\n@elasticmachine, run elasticsearch-ci/docs rebuild\n----------------------------\n\n\n\n[[config]]\n== Adding new docs or new branches\n\nThe documentation that appears on the http://www.elastic.co/guide\nwebsite is controlled by the\nhttps://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`] file in the `docs` repo.\n\nYou can add a new repository under the `repos` section, if it\ndoesn't already exist, and you can add a new \"book\" under the\n`contents` section.\n\nEach book contains a list of `branches` and we build a separate copy of each\nbook for each of those `branches`. There is also a `current` branch which gets\nspecial treatment. When we fork a branch like 7.x or 7.9 we typically add\nit to the list of `branches` so we immediately start building docs for it while\nwe're actively developing against it. When we release a new minor or major\nversion we update the `current` branch to point to that branch.\n\nNOTE: At this point changing `current` requires a full \"rebuild\" which we do\nby logging into the docs\nhttps://elasticsearch-ci.elastic.co/view/Docs/job/elastic+docs+master+build/[build]\nclicking the \"Build with Parameters\" link, checking the \"rebuild\" option, and\nthen starting the build.\n\nEach book may optionally contain a list of `live` branches. If the list is\nspecified only branches that are in it are considered \"living\" and books that\nare not in the list will get a message at the top of each page saying that we\ndon't plan to release any more bug fixes or actively maintain the docs for that\nbranch.\n\nIf you want a branch to have a different \"version\" name (for instance, if you\nwant to build a version called \"4.2\" but have it build out of a branch called\n\"branch-for-4.2\"), you can put `{branch-for-4.2: 4.2}` as an entry in the\n`branches` list. Everywhere else in `conf.yaml`, continue to use\n`branch-for-4.2`.\n\n[[asciidoc-guide]]\n= Asciidoc Guide\n\n[partintro]\n--\nAsciidoc is a powerful markup language that is easy to read as\nplain text.\n\nBelow I include most of the Asciidoc syntax that you will\nneed.  For more, you can take a look at the\nhttps://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual], or the\nhttp://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoc Syntax Quick Reference].\n--\n\n[[structure]]\n== Basic book structure\n\nAsciidocs can be built as a `book`, `article`, `manpage` etc.\nAll our docs are built as a `book`, and thus follow the\nlayout for books.  The most basic structure is as follows:\n\n[source,asciidoc]\n----------------------------------\n= Book title                // level 0\n\n== Chapter title            // level 1\n\n=== Section title           // level 2\n\n==== Section title          // level 3\n\n===== Section title         // level 4\n----------------------------------\n\nUsually this structure will be sufficient for most of your\ndocumentation needs. More complicated \"books\", such\nas the {ref}[Elasticsearch Guide],\nrequire a few additional elements, described on the\nfollowing pages.\n\n=== Filenames\n\nBy default, each chapter will generate a new _chunk_\nor HTML file.  You can control the name of the file\nby giving the header an ID, as follows:\n\n[source,asciidoc]\n----------------------------------\n[[intro-to-xyz]]\n== Intro to XYZ\n----------------------------------\n\nThis chapter would then be written to a file called\n`intro-to-xyz.html`.  If no ID is provided, then a\nfilename will be auto-generated.  See \u003c\u003cchunking\u003e\u003e\nfor more.\n\nThese IDs are also used to link to sections within each\nbook.  See \u003c\u003clinking\u003e\u003e.\n\nTIP: For search engine optimization (SEO), make sure the keywords you use in the\nID match keywords used in the topic title. For example, if the topic is called\n\"Install XYZ\", use `+[[install-xyz]]+` for the topic ID.\n\n=== TOC titles\n\nBy default, the link text used in the generated TOC is\nbased on the title of each file. You can provide an\nabbreviated title using a `titleabbrev` in\none of two ways:\n\n. You *should* add a `titleabbrev` attribute to the section:\n+\n--\n[source,asciidoc]\n----\n[id=intro_to_xyz,titleabbrev=\" XYZ Intro\"]\n== Intro to XYZ\n\nWords.\n----\n--\n\n. You *may* use the pass block but it isn't recommended:\n+\n--\n[source,asciidoc]\n----\n== Intro to XYZ\n++++\n\u003ctitleabbrev\u003eXYZ Intro\u003c/titleabbrev\u003e\n++++\n\nWords.\n----\n--\n\n[[multi-part]]\n== Multi-part books\n\nBooks may also be divided into multiple parts, which are indicated\nwith `level 0` headers:\n\n[source,asciidoc]\n----------------------------------\n= Book title                // level 0\n\n= Part title                // level 0\n\n== Chapter title            // level 1\n\n=== Section title           // level 2\n\n... etc ...\n----------------------------------\n\nEach `part` also creates a new _chunk_ or HTML file.\n\n=== Part intro\n\nA `part` may include text before the first `chapter`, but\nit must be marked with `[partintro]` in order to be valid:\n\n[source,asciidoc]\n----------------------------------\n= Book title                // level 0\n\n= Part one                  // level 0\n\n[partintro]\nA paragraph introducing this Part\n\n== Chapter title            // level 1\n\n... etc ...\n----------------------------------\n\nLonger `partintro` blocks should be wrapped in an\nhttps://asciidoctor.org/docs/user-manual/#open-blocks[_open block_]\nwhich starts and ends with two dashes: `--`:\n\n[\"source\",\"asciidoc\",subs=\"attributes,callouts,macros\"]\n----------------------------------\n= Part two                  // level 0\n\n[partintro]\n.A partintro title\npass:[--] \u003c1\u003e\nThis section may contain multiple paragraphs.\n\n[discrete]\n== A header should use [discrete]\n\nEverything up to the closing -- marker\nwill be considered part of the partintro.\npass:[--] \u003c1\u003e\n\n== Chapter title           // level 2\n\n... etc ...\n----------------------------------\n\n\u003c1\u003e The _open block_ delimiters\n\n[[optional-sections]]\n== Optional sections\n\nBooks may include other sections such as a _preamble_, a _preface_,\na _glossary_ or _appendices_.\n\n=== Preamble\n\n[source,asciidoc]\n----------------------------------\n= Book title                // level 0\n\n.Optional preamble title\nPreamble text...\n\n----------------------------------\n\n=== Preface and Appendix\n\n[source,asciidoc]\n----------------------------------\n[preface]\n= Preface title             // level 0\n\n=== Preface header          // level 2 \u003c1\u003e\n\n= Part one                  // level 0\n----------------------------------\n\nand\n\n[source,asciidoc]\n----------------------------------\n[appendix]\n= Appendix title            // level 0\n\n=== Appendix header         // level 2 \u003c1\u003e\n----------------------------------\n\n\u003c1\u003e Any headers in the appendix or in the preface start\n    out-of-sequence at `level 2`, not at `level 1`.\n\n[[section]]\n=== Glossary\n\n[source,asciidoc]\n----------------------------------\n[glossary]\n= Glossary title            // level 0\n\n[glossary]\nTerm one::\n    Defn for term one\n\nTerm two::\n    Defn for term two\n----------------------------------\n\n[NOTE]\n==================================\nThe two `[glossary]` elements above have different purposes:\n\n * The first marks this section of the document as a glossary, to be included in the table of contents\n * The second marks the definitions list as type `glossary`\n==================================\n\n\n=== Also see\n\nIf you need to use some of these more advanced structural\nelements, have a look at the example of a multi-part book\nincluded in this repo in https://github.com/asciidoc/asciidoc/blob/master/doc/book-multi.txt[`book-multi.txt`].\n\n[[paragraphs]]\n== Paragraphs\n\nA paragraph consists of multiple lines of text which start\nin the left hand column:\n\n[source,asciidoc]\n----------------------------------\nThis is a paragraph\neven though it contains\nline breaks.\n\nThis is a second paragraph.\n----------------------------------\n\n=== Paragraph titles\n\nLike most elements, a paragraph can have a title:\n\n.Paragraph with a title\n==================================\n[source,asciidoc]\n----------------------------------\n.Paragraph title\nText of my paragraph\n----------------------------------\n\n.Paragraph title\nText of my paragraph\n==================================\n\n[[admon-paras]]\n=== Admonition paragraphs\n\nA paragraph which starts with `TIP:`, `NOTE:`, `IMPORTANT:`,\n`WARNING:` or `CAUTION:` is rendered as an _admonition_ paragraph,\neg:\n\n[source,asciidoc]\n----------------------------------\nNOTE: Compare admonition paragraphs with \u003c\u003cadmon-blocks\u003e\u003e.\n----------------------------------\n\nThis renders as:\n\nNOTE: Compare admonition paragraphs\nwith \u003c\u003cadmon-blocks\u003e\u003e.\n\n=== Literal paragraphs\n\nLiteral paragraphs, which are rendered as `\u003cpre\u003e`\nblocks without any source highlighting, must be\nindented:\n\n.A literal paragraph\n==================================\n[source,asciidoc]\n----------------------------------\n.Optional title\n\n    This para must\n    be indented\n----------------------------------\n\n.Optional title\n    This para must\n    be indented\n==================================\n\nSee also \u003c\u003ccode-blocks\u003e\u003e for blocks with\nsyntax highlighting.\n\n[[text]]\n== Inline text\n\nInline text can be formatted as follows:\n\n[horizontal]\nifdef::env-github[]\n`\u0026#x5f;emphasis_`::         _emphasis_\n`\u0026#x2a;bold*`::             *bold*\n`\u0026#x60;mono'`::             `mono`\n`\u0026#x5e;superscript^`::      ^superscript^\n`\u0026#x7e;subscript~`::        ~subscript~\nendif::[]\nifndef::env-github[]\n+\u0026#x5f;emphasis_+::         _emphasis_\n+\u0026#x2a;bold*+::             *bold*\n+\u0026#x60;mono'+::             `mono`\n+\u0026#x5e;superscript^+::      ^superscript^\n+\u0026#x7e;subscript~+::        ~subscript~\nendif::[]\n\nThese formatting characters expect to adjoin whitespace or\ncommon punctuation characters.  To combine *bold* with emphasis,\ndouble up the quotes (ie use `__` and `**`):\n\n.Combining bold and emphasis\n==================================\n[source,asciidoc]\n----------------------------------\nThis example co__mb**in**es__ bold and emphasis\n----------------------------------\n\nThis example co__mb**in**es__ bold and emphasis.\n==================================\n\nUnwanted quotes can be escaped with a `\\` character.\n\n=== Replacement characters\n\nCertain runs of ASCII characters are replaced as follows:\n\n[horizontal]\nifdef::env-github[]\n`--`::        -- (em dash)\n`\u0026#x2e;..`::  ...\n`\u0026#x2d;\u003e`::   -\u003e\n`\u003c\u0026#x2d;`::   \u003c-\n`\u0026#x3d;\u003e`::   =\u003e\n`\u003c\u0026#x3d;`::   \u003c=\n`\u0026#x28;C)`::  (C)\n`\u0026#x28;TM)`:: (TM)\n`\u0026#x28;R)`::  (R)\nendif::[]\nifndef::env-github[]\n+--+::        -- (em dash)\n+\u0026#x2e;..+::  ...\n+\u0026#x2d;\u003e+::   -\u003e\n+\u003c\u0026#x2d;+::   \u003c-\n+\u0026#x3d;\u003e+::   =\u003e\n+\u003c\u0026#x3d;+::   \u003c=\n+\u0026#x28;C)+::  (C)\n+\u0026#x28;TM)+:: (TM)\n+\u0026#x28;R)+::  (R)\nendif::[]\n\n[[shared-attributes]]\n== Shared attributes\n\nTo facilitate consistency across the documentation, there are shared attributes\nfor common terms and URLs: https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc.\nThere are also attributes related to the versions and branches that are used to\nbuild our books\n(for example: https://github.com/elastic/docs/blob/master/shared/versions/stack/master.asciidoc).\n\nBooks that use shared attributes files must declare a dependency on them in\nhttps://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`] like this:\n\n[source,yaml]\n----\n  -\n    repo:   docs\n    path:   shared/versions/stack/{version}.asciidoc\n  -\n    repo:   docs\n    path:   shared/attributes.asciidoc\n----\n\nor\n\n[source,yaml]\n----\n  -\n    repo:   docs\n    path:   shared/versions/stack/current.asciidoc\n  -\n    repo:   docs\n    path:   shared/attributes.asciidoc\n----\n\nThere is also a special set of attributes that are automatically created by the\nbuild process. They are labelled `\u003crepo\u003e-root`, where `\u003crepo\u003e` is the name\ndefined at the top of the\nhttps://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`]. For example,\nthere is an `elasticsearch-root` attribute that resolves to the root path of the\nElasticsearch repo. Please use these root attributes or define `es-repo-dir`,\nfor example, rather than relying on intrinsic attributes like `{docdir}` and\n`{asciidoc-dir}`. The instrinsic attributes are problematic when you re-use\nfiles in different source file paths.\n\nIf books don't use shared attributes files, the attributes generally appear at\nthe beginning of the book, under the title. For example:\n\n.Using book-scoped attributes for cross-document linking\n==================================\n\n[source,asciidoc]\n----------------------------------\n= My Book Title\n\n:branch: master\n:ref:    https://www.elastic.co/guide/en/elasticsearch/reference/{branch}\n\nHere is a link to the {ref}/search.html[search page]\n----------------------------------\n==================================\n\n[[attribute-scope]]\n== Attribute scope\n\nAttributes are in-scope for the entire book unless you explicitly clear them by\nsetting `:!attributename:`. For example:\n\n.Clearing an attribute\n==================================\n\n[source,asciidoc]\n----------------------------------\n:myattribute: some value\nAll the things on the page.\n:!myattribute:\n----------------------------------\n==================================\n\nTo create page-scoped attributes, clear the attribute at the end of the page.\n\n[[linking]]\n== Linking\n\nYou can link to any block in the document that has an ID -- an\nidentifier before the block which is wrapped in double\nsquare brackets: `[[ID]]`\n\n[source,asciidoc]\n----------------------------------\n[[para-id]]\nThis paragraph can be linked to using the ID `para-id`.\n----------------------------------\n\nWhen you need to combine an ID with a _style_, you can\neither specify each on a separate line:\n\n[source,asciidoc]\n----------------------------------\n[[note-id]]\n[NOTE]\n===============================\nThis note can be linked to using the ID `note-id`.\n===============================\n----------------------------------\n\nor in one line:\n\n[source,asciidoc]\n----------------------------------\n[\"NOTE\",id=\"note-id\"] \u003c1\u003e\n===============================\nThis note can be linked to using the ID `note-id`.\n===============================\n----------------------------------\n\n\u003c1\u003e In the one line format, the `NOTE` must be enclosed\n    in double quotes.\n\nBoth of the above render as:\n\n[\"NOTE\",id=\"note-id\"]\n===============================\nThis note can be linked to using the ID `note-id`.\n===============================\n\nThe `ID` is added to the HTML document as an `\u003ca\u003e` anchor\nand, as explained in \u003c\u003cchunking\u003e\u003e, the `ID` is used as the\nfilename for sections which are chunked -- written to\nseparate HTML files.\n\n=== Internal links\n\nYou can link to any ID within a document using double\nangle brackets:\n\n.Links with default link text\n==================================\n[source,asciidoc]\n----------------------------------\n* \u003c\u003csetup\u003e\u003e\n* \u003c\u003cstructure\u003e\u003e\n----------------------------------\n\n* \u003c\u003csetup\u003e\u003e\n* \u003c\u003cstructure\u003e\u003e\n==================================\n\nIt will use the title associated with each ID as the\nlink text.\n\nAlternative link text can be provided as a second parameter\ninside the angle brackets:\n\n.Links with custom link text\n==================================\n\n[source,asciidoc]\n----------------------------------\nSee the \u003c\u003cnote-id,note about IDs\u003e\u003e.\n----------------------------------\n\nSee the \u003c\u003cnote-id,note about IDs\u003e\u003e.\n\n==================================\n\n=== External links\n\nLinks to external websites can just be added as normal\ninline text, optionally with custom link text in\nsquare brackets:\n\n.External links\n==================================\n\n[source,asciidoc]\n----------------------------------\nSee http://github.com/elastic\nor  http://github.com/elastic/docs[this repository]\n----------------------------------\n\nSee http://github.com/elastic\nor  http://github.com/elastic/docs[this repository]\n\n==================================\n\nThe existence of external links is not confirmed by\nthe build process.\n\n=== Cross document links\n\nLinks to other Elastic books are essentially the\nsame as external links. However, for conciseness and\nmaintainability, you should use an _attribute_ to\nrepresent the absolute URL of the docs.\n\nIf possible, use attributes defined in the\nhttps://github.com/elastic/docs/blob/master/shared/attributes.asciidoc[shared\nattributes file] to resolve links:\n\n.Using shared attributes for cross-document linking\n==================================\n\n[source,asciidoc]\n----------------------------------\n= My Book Title\n\n# Use this if your repo is versioned with the Elastic stack:\n\\include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]\n# Or use this to alway point to the most recent version of the stack\n\\include::{docs-root}/shared/versions/stack/current.asciidoc[]\n# Either way, you'll want to include a reference to the attributes file\n# which builds the links from the versions.\n\\include::{docs-root}/shared/attributes.asciidoc[]\n\nHere is a link to the {ref}/search.html[search page]\n----------------------------------\n==================================\n\nThe main benefit of using attributes for cross document links is\nthat, when the docs for an old version contain links that\nno longer exist in the `current` branch, you can update\nall the links in the document to point to the older version,\nby just updating a single attribute.\n\nCross document links are checked when `build_docs` is\nrun with the `--all` parameter.  See \u003c\u003cwebsite\u003e\u003e.\n\n[[lists]]\n== Lists\n\n=== Bullet points\n\nBullet point lists are written using asterisks:\n\n.Bullet points\n==================================\n[source,asciidoc]\n----------------------------------\n.Optional title\n* Point\n* Point\n** Sub-point\n*** Sub-sub-point\n* [ ] TODO\n* [x] Done\n* A point can have multiple paragraphs\n+\nBut use a `+` instead of an empty line between paras.\n\nAn empty line signifies the end of the list.\n----------------------------------\n\n.Optional title\n* Point\n* Point\n** Sub-point\n*** Sub-sub-point\n* [ ] TODO\n* [x] Done\n* A point can have multiple paragraphs\n+\nBut use a `+` instead of an empty line between paras\n\nAn empty line signifies the end of the list.\n==================================\n\nFor more information, see https://asciidoctor.org/docs/user-manual/#unordered-lists\n\n=== Ordered lists\n\nOrdered lists use `.` instead of `*`, and will alternate\nbetween numbers and letters automatically:\n\n.An ordered list\n==================================\n[source,asciidoc]\n----------------------------------\n.Optional title\n. foo\n.. bar\n... baz\n.... balloo\n----------------------------------\n\n.Optional title\n. foo\n.. bar\n... baz\n.... balloo\n==================================\n\nFor more information, see https://asciidoctor.org/docs/user-manual/#ordered-lists\n\n=== Definition lists\n\nDefinition lists are used to define terms. The term must be\nfollowed by a double colon `::` eg:\n\n.A vertical definition list\n==================================\n[source,asciidoc]\n----------------------------------\nterm one::      Definition for term one\nterm two::\n                Can start on the next line\nterm three::    A definition can have multiple\n+\nparagraphs, but use `+` to separate them\n\nterm four:::    Definitions can be nested\n                by adding more colons\nterm five::     A definition can even include\n                lists:\n                * point one\n                * point two\n----------------------------------\n\nterm one::      Definition for term one\nterm two::\n                Can start on the next line\nterm three::    A definition can have multiple\n+\nparagraphs, but use `+` to separate them\n\nterm four:::    Definitions can be nested\n                by adding more colons\nterm five::     A definition can even include\n                lists:\n                * point one\n                * point two\n==================================\n\n[[horizonta-defn-list]]\n=== Horizontal definition lists\n\nOften definition lists are better rendered\nhorizontally, eg:\n\n.A horizontal definition list\n==================================\n[source,asciidoc]\n----------------------------------\n[horizontal]\nterm one::      Definition for term one\nterm two::\n                Can start on the next line\nterm three::    A definition can have multiple\n+\nparagraphs, but use `+` to separate them\n\nterm four:::    Definitions can be nested\n                by adding more colons\nterm five::     A definition can even include\n                lists:\n                * point one\n                * point two\n----------------------------------\n\n[horizontal]\nterm one::      Definition for term one\nterm two::\n                Can start on the next line\nterm three::    A definition can have multiple\n+\nparagraphs, but use `+` to separate them\n\nterm four:::    Definitions can be nested\n                by adding more colons\nterm five::     A definition can even include\n                lists:\n                * point one\n                * point two\n==================================\n\n[[blocks]]\n== Blocks\n\nBlocks are used for special blocks of content, such as\n\u003c\u003ccode-blocks\u003e\u003e, \u003c\u003cexamples\u003e\u003e, \u003c\u003csidebars\u003e\u003e and\n\u003c\u003cadmon-blocks\u003e\u003e.\n\nBlocks are delimited with a start and end line which uses\nthe same characters, like `=====`.\n\n[[code-blocks]]\n=== Code blocks\n\nCode blocks are rendered as `\u003cpre\u003e` blocks, and use\nsyntax highlighting, eg:\n\n.A code block\n==================================\n[source,asciidoc]\n--\n.Optional title\n[source,js]\n----------------------------------\n{\n    \"query\": \"foo bar\"\n}\n----------------------------------\n--\n\n.Optional title\n[source,js]\n----------------------------------\n{\n    \"query\": \"foo bar\"\n}\n----------------------------------\n==================================\n\nIMPORTANT: If you don't specify the source language then the generated\nHTML is *quite* different so, in general, you should specify a language.\nWe use the language as a hint for the syntax highlighter. See files in\nthis repository names `lang-*.js` for information.\n\n=== Callouts\n\nCode blocks can use _callouts_ to add an explanatory\nfootnote to a particular line of code:\n\n.Code block with callouts\n==================================\n[source,asciidoc]\n--\n[source,js]\n----------------------------------\n{\n    \"query\": \"foo bar\" \\\u003c1\u003e\n}\n----------------------------------\n\u003c1\u003e Here's the explanation\n--\n\n[source,js]\n----------------------------------\n{\n    \"query\": \"foo bar\" \u003c1\u003e\n}\n----------------------------------\n\n\u003c1\u003e Here's the explanation\n==================================\n\n[[copy-as-curl]]\n=== Copy as curl/View in Console\n\nCode blocks can be followed by a \"Copy as curl\" link which will convert the\nsnippet into a sequence of calls to the ubiquitous\nhttps://curl.se/[curl] tool that work in the bash shell and copy it to\nthe clipboard. Similarly, if the target of the snippet is Elasticsearch we also\nadd a \"Try in Console\" link will open the code snippet in Console.\n\nYou enable it by setting the \"language\" of the snippet to a supported\nlanguage. The options are \"console\" for Elasticsearch, \"kibana\" for Kibana,\n\"ess\" for Elasticsearch Service (Elastic's official SaaS offering), and \"ece\"\nfor Elastic Cloud Enterprise.\n\nFor Elasticsearch do this:\n\n.Code block with \"Copy as curl\" and \"Try in Console\" link for Elasticsearch\n==================================\n[source,asciidoc]\n--\n[source,console]\n----------------------------------\nGET /_search\n{\n    \"query\": \"foo bar\" \\\u003c1\u003e\n}\n----------------------------------\n\u003c1\u003e Here's the explanation\n--\n==================================\n\nWhich renders as:\n\n[source,console]\n----------------------------------\nGET /_search\n{\n    \"query\": \"foo bar\" \u003c1\u003e\n}\n----------------------------------\n\u003c1\u003e Here's the explanation\n\nNOTE: In older branches you'll see `// CONSOLE` after the snippet to trigger\n      this behavior. That is deprecated.\n\nFor Kibana do this:\n\n.Code block with \"Copy as curl\" link for Kibana\n==================================\n[source,asciidoc]\n--\n[source,kibana]\n----------------------------------\nGET /\n----------------------------------\n--\n==================================\n\nWhich renders as:\n\n[source,kibana]\n----------------------------------\nGET /\n----------------------------------\n\nFor Elasticsearch Service do this:\n\n.Code block with \"Copy as curl\" link for Elasticsearch Service\n==================================\n[source,asciidoc]\n--\n[source,ess]\n----------------------------------\nGET /\n----------------------------------\n--\n==================================\n\nWhich renders as:\n\n[source,ess]\n----------------------------------\nGET /\n----------------------------------\n\nFor Elastic Cloud Enterprise do this:\n\n.Code block with \"Copy as curl\" link for Elastic Cloud Enterprise\n==================================\n[source,asciidoc]\n--\n[source,ece]\n----------------------------------\nGET /\n----------------------------------\n--\n==================================\n\nWhich renders as:\n\n[source,ece]\n----------------------------------\nGET /\n----------------------------------\n\n==== Responses\n\nIf `Console` requests are followed by a \"response\" then it should be written\nwith the language set to `console-response`. That will allow\n\u003c\u003calternative_languages, alternative examples\u003e\u003e to find the responses.\nLike this:\n\n[source,asciidoc]\n--\n[source,console-result]\n----------------------------------\n{\n    \"hits\": {\n        \"total\": { \"value\": 0, \"relation\": \"eq\" },\n        \"hits\": []\n    }\n}\n----------------------------------\n--\n\nWhich should render as:\n\n[source,console-result]\n----------------------------------\n{\n    \"hits\": {\n        \"total\": { \"value\": 0, \"relation\": \"eq\" },\n        \"hits\": []\n    }\n}\n----------------------------------\n\n\n[[admon-blocks]]\n=== Admonition blocks\n\nAdmonition blocks are much the same as \u003c\u003cadmon-paras\u003e\u003e, except that\nthey can be longer and contain more than just a paragraph.\nFor instance:\n\n\n[source,asciidoc]\n--\n[NOTE]\n=========================\nThis note contains a list:\n\n* foo\n* bar\n* baz\n\nand some code\n\n[source,js]\n----------------------------------\n{ \"query\": \"foo bar\"}\n----------------------------------\n=========================\n--\n\nThis renders as:\n\n[NOTE]\n=========================\nThis note contains a list:\n\n* foo\n* bar\n* baz\n\nand some code\n\n[source,js]\n----------------------------------\n{ \"query\": \"foo bar\"}\n----------------------------------\n=========================\n\n[[sidebars]]\n=== Sidebars\n\nSidebars are used to highlight a block of\ncontent that is outside the usual flow of text:\n\n[source,asciidoc]\n----------------------------------\n.Optional title\n**********************************\nSo why does the `bulk` API have such a\nfunny format?  Sit down and I'll tell you\nall about it!\n**********************************\n----------------------------------\n\n.Optional title\n**********************************\nSo why does the `bulk` API have such a\nfunny format?  Sit down and I'll tell you\nall about it!\n**********************************\n\n\n[[examples]]\n=== Example blocks\n\nExample blocks contain normal text which is used as an\nexample.  The title, if any, is labelled as an example\nand numbered:\n\n[source,asciidoc]\n----------------------------------\n.My first example\n========================================\nText explaining the first example.\n========================================\n\n.My second example\n========================================\nText explaining the second example.\n========================================\n----------------------------------\n\nThis renders as:\n\n.My first example\n========================================\nText explaining the first example.\n========================================\n\n.My second example\n========================================\nText explaining the second example.\n========================================\n\nCAUTION: The `===` and `---` delimiters can\nsometimes be confused with a header, resulting\nin an error.  To resolve this, add newlines\nbetween the delimiter and the content\nbefore and after it.\n\nExamples can be made collapsible:\n\n[source,asciidoc]\n----------------------------------\n[%collapsible]\n.An example\n====\nLots of text can go in here.\n====\n----------------------------------\n\nWhich renders as:\n\n[%collapsible]\n.An example\n====\nLots of text can go in here.\n====\n\n[[includes]]\n== Including files\n\nFor long documentation, you probably want to break up\nthe Asciidoc files into smaller units, and just\ninclude them where appropriate:\n\n[source,asciidoc]\n----------------------------------\n\\include::myfolder/mydoc.asciidoc[]\n----------------------------------\n\nPaths are relative to the file which\ncontains the `include` statement.\n\n[[cross-repo-includes]]\n=== Across repositories\n\nIf you have to include files in a different repository then use its `-root`\nattribute to locate the files:\n\n[source,asciidoc]\n----------------------------------\n\\include::{elasticsearch-root}/docs/foo.asciidoc[]\n----------------------------------\n\nBooks that reference another repository should register that reference in\nhttps://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`].\n\n[source,yaml]\n----\n  -\n    repo:   elasticsearch\n    path:   docs/foo.asciidoc\n----\n\nThe path should be as specific as possible because we skip rebuilding books if\nchanges to the referenced repository don't change the referenced path.\n\n[[changes]]\n== Additions and deprecations\n\nDocumentation is built for various branches, eg `0.90`,\n`1.00`, `master`.  However, we release versions\n`0.90.0`, `0.90.1`, etc, which are all based on the\n`0.90` branch.\n\nWhen adding new functionality to a branch, or deprecating\nexisting functionality, you can mark the change as\n_added_, _coming_ or _deprecated_. Use `coming` when the addition is\nin an as yet unreleased version of the current branch, and `added` when\nthe functionality is already released.\n\nThe `update_versions.pl` script can be used to change `coming` notices\nto `added` notices when doing a new release, and can also be used\nto remove `added`, `coming` and `deprecated` notices completely.\n\n\n=== Inline notifications\n\nUse inline notifications for small changes, such as\nthe addition or deprecation of individual parameters.\n\n[source,asciidoc]\n----------------------------------\n[horizontal]\n`foo.bar`::   Does XYZ. added:[0.90.4]\n`foo.bar`::   Does XYZ. coming:[0.90.4]\n`foo.baz`::   Does XYZ. deprecated:[0.90.4]\n----------------------------------\n\n[horizontal]\n`foo.bar`::   Does XYZ. added:[0.90.4]\n`foo.bar`::   Does XYZ. coming:[0.90.4]\n`foo.baz`::   Does XYZ. deprecated:[0.90.4]\n\nYou can also include details about additional\nnotes in the notifications which show up when the\nuser hovers over it:\n\n[source,asciidoc]\n----------------------------------\n[horizontal]\n`foo.bar`::   Does XYZ. added:[0.90.4,Replaces `foo.baz`]\n`foo.bar`::   Does XYZ. coming:[0.90.4,Replaces `foo.baz`]\n`foo.baz`::   Does XYZ. deprecated:[0.90.4,Replaced by `foo.bar`]\n----------------------------------\n\n[horizontal]\n`foo.bar`::   Does XYZ. added:[0.90.4,Replaces `foo.baz`]\n`foo.bar`::   Does XYZ. coming:[0.90.4,Replaces `foo.baz`]\n`foo.baz`::   Does XYZ. deprecated:[0.90.4,Replaced by `foo.bar`]\n\n[NOTE]\n====\nIf the details include a comma, you must use quotation marks. For example:\n[source,asciidoc]\n----------------------------------\ndeprecated::[1.1.0,\"Span started automatically by \u003c\u003capm-start-span,apm.startSpan()\u003e\u003e\"]\n----------------------------------\n====\n\n=== Section notifications\n\nUse section notifications to mark an entire chapter or\nsection as _added_/_deleted_.  Notifications can just refer\nto the version in which the change was made:\n\n[source,asciidoc]\n----------------------------------\n==== New section\n\nadded::[0.90.4]\n\nText about new functionality...\n\n==== New section not yet released\n\ncoming::[0.90.9]\n\nText about new functionality...\n\n==== Old section\n\ndeprecated::[0.90.4]\n\nText about old functionality...\n----------------------------------\n\n==== New section\n\nadded::[0.90.4]\n\nText about new functionality...\n\n==== New section not yet released\n\ncoming::[0.90.9]\n\nText about new functionality...\n\n==== Old section\n\ndeprecated::[0.90.4]\n\nText about old functionality...\n\n[[with_details]]\n==== With details...\n\nOr they can include extra text, including more\nAsciidoc markup:\n\n[source,asciidoc]\n----------------------------------\n[[new-section]]\n==== New section\n\nadded::[0.90.4,Replaces `foo.bar`. See \u003c\u003cold-section\u003e\u003e]\n\nText about new functionality...\n\n[[coming-section]]\n==== New section not yet released\n\ncoming::[0.90.9,Replaces `foo.bar`. See \u003c\u003cold-section\u003e\u003e]\n\nText about new functionality...\n\n[[old-section]]\n==== Old section\n\ndeprecated::[0.90.4,Replace by `foo.baz`. See \u003c\u003cnew-section\u003e\u003e]\n\nText about old functionality...\n----------------------------------\n\n[[new-section]]\n==== New section\n\nadded::[0.90.4,Replaces `foo.bar`. See \u003c\u003cold-section\u003e\u003e]\n\nText about new functionality...\n\n[[old-section]]\n==== Old section\n\ndeprecated::[0.90.4,Replace by `foo.baz`. See \u003c\u003cnew-section\u003e\u003e]\n\nText about old functionality...\n\n[[experimental]]\n== Beta, Dev, and Preview (experimental)\n\nAPIs or parameters that are in beta, in development, or in technical preview (formerly experimental) can be\nmarked as such, using markup similar to that used in \u003c\u003cchanges\u003e\u003e.\n\nIn the block format, you have the option of adding a related GitHub issue link.\nIf both custom text and a GitHub link are provided, the GitHub link **must** be\nprovided second. If it's supported in your repo, you can use the `{issue}`\nattribute in place of the GitHub issue link.\n\n=== Using the `beta` admonition\n\n[source,asciidoc]\n----\n[[new-beta-feature]]\n=== New beta feature\n\nbeta::[]\n\nbeta::[https://github.com/elastic/docs/issues/505]\n\nbeta::[{issue}505]\n\nbeta::[\"Custom text goes here.\"]\n\nbeta::[\"Custom text goes here.\",https://github.com/elastic/docs/issues/505]\n\nbeta::[\"Custom text goes here.\",{issue}505]\n\nText about new feature...\n\n[[old-beta-feature]]\n=== Established feature\n\nThis feature has been around for a while, but we're adding\na new parameter that's in beta:\n\n`established_param`::\nThis param has been around for ages and won't change.\n\n`beta_param`::\nbeta:[]\nThis param is in beta and may change in the future.\n\n`beta_param`::\nbeta:[\"Custom text goes here.\"]\nThis param is in beta and may change in the future.\n----\n\n=== Using the `dev` admonition\n\n[source,asciidoc]\n----\n[[new-dev-feature]]\n=== New feature in development\n\ndev::[]\n\ndev::[https://github.com/elastic/docs/issues/505]\n\ndev::[{issue}505]\n\ndev::[\"Custom text goes here.\"]\n\ndev::[\"Custom text goes here.\",https://github.com/elastic/docs/issues/505]\n\ndev::[\"Custom text goes here.\",{issue}505]\n\nText about feature in development...\n\n[[old-dev-feature]]\n=== Established feature\n\nThis feature has been around for a while, but we're adding\na new parameter that's in development:\n\n`established_param`::\nThis param has been around for ages and won't change.\n\n`dev_param`::\ndev:[]\nThis param is in development and may change in the future.\n\n`dev_param`::\ndev:[\"Custom text goes here.\"]\nThis param is in development and may change in the future.\n----\n\n=== Using the `experimental` admonition\n\nExperimental language is deprecated.\n\nWe decided on the much less raw sounding \"technical preview\".\n\nSee below.\n\n=== Using the technical `preview` admonition\n\n[source,asciidoc]\n----\n[[new-feature]]\n=== New feature in technical preview\n\npreview::[]\n\npreview::[https://github.com/elastic/docs/issues/505]\n\npreview::[{issue}505]\n\npreview::[\"Custom text goes here.\"]\n\npreview::[\"Custom text goes here.\",https://github.com/elastic/docs/issues/505]\n\npreview::[\"Custom text goes here.\",{issue}505]\n\nText about new feature...\n\n[[old-feature]]\n=== Established feature\n\nThis feature has been around for a while, but we're adding\na new preview parameter:\n\n`established_param`::\nThis param has been around for ages and won't change.\n\n`experimental_param`::\npreview:[]\nThis param is in technical preview and may change in the future.\n\n`experimental_param`::\npreview:[\"Custom text goes here.\"]\nThis param is in technical preview and may change in the future.\n----\n\n[[images]]\n== Images\n\nAny images you want to include should be saved in a folder\nin your repo, and included using a path relative\nto the document where the `image::` statement appears.\n\n[source,asciidoc]\n----------------------------------\n[[cat]]\n.A scaredy cat\nimage::resources/readme/cat.jpg[Alt text]\n\nA link to \u003c\u003ccat\u003e\u003e\n----------------------------------\n\n[[cat]]\n.A scaredy cat\nimage::resources/readme/cat.jpg[Alt text]\n\nA link to \u003c\u003ccat\u003e\u003e.\n\n=== Width and height\n\nThe `width` and/or `height` of the image can be\nspecified in pixels or as a percentage:\n\n[source,asciidoc]\n----------------------------------\nimage::resources/readme/cat.jpg[\"Alt text\",width=50]\nimage::resources/readme/cat.jpg[\"Alt text\",width=\"20%\"]\n----------------------------------\n\nimage::resources/readme/cat.jpg[\"Alt text\",width=50]\nimage::resources/readme/cat.jpg[\"Alt text\",width=\"20%\"]\n\n=== Alignment\n\nImages are left-aligned by default, but they can\nbe centred or right-aligned:\n\n[source,asciidoc]\n----------------------------------\nimage::resources/readme/cat.jpg[\"Alt text\",width=100,align=\"left\"]\nimage::resources/readme/cat.jpg[\"Alt text\",width=100,align=\"right\"]\nimage::resources/readme/cat.jpg[\"Alt text\",width=100,align=\"center\"]\n----------------------------------\n\nimage::resources/readme/cat.jpg[\"Alt text\",width=100,align=\"left\"]\nimage::resources/readme/cat.jpg[\"Alt text\",width=100,align=\"right\"]\nimage::resources/readme/cat.jpg[\"Alt text\",width=100,align=\"center\"]\n\n=== Screenshots\n\nScreenshots get extra margins and a box-shadow:\n\n[role=\"screenshot\"]\nimage::resources/readme/screenshot.png[A screenshot example]\n\nYou can activate it with:\n\n[source,asciidoc]\n----\n[role=\"screenshot\"]\nimage::resources/readme/screenshot.png[A screenshot example]\n----\n\n[[svgs]]\n=== SVGs\n\nSVGs are also supported. Just use them like you would any other image:\n\n[source,asciidoc]\n----\nimage::resources/readme/example.svg[An example svg]\n----\n\nWhich looks like:\n\nimage::resources/readme/example.svg[An example svg]\n\n[[image-links]]\n=== Image links\n\nYou can add relative or absoloute links to your images with the following syntax:\n\n[source,asciidoc]\n----\nimage:./images/dynamic-config.svg[link=configuration.html#configuration-dynamic]\n----\n\nUsing internal link attributes is also supported, but the image must be inside the internal link syntax.\nIt's important to add a space on each side of the image tag. Without spaces, the image will not render.\n\n[source,asciidoc]\n----\n\u003c\u003cconfiguration-dynamic, image:./images/dynamic-config.svg[] \u003e\u003e\n----\n\n[[videos]]\n== Videos\n\nYou can add a vimeo hosted video with Asciidoctor's\nhttps://asciidoctor.org/docs/user-manual/#video[video] tag:\n\n[source,asciidoc]\n----\nvideo::366852847[vimeo,height=480]\n----\n\nNOTE: You *should* set height or else the video will be tiny. You *shouldn't*\n      set width because Vimeo will preserve the aspect ratio for you.\n\nWhich renders like this:\n\nvideo::366852847[vimeo,height=480]\n\n[[tables]]\n== Tables\n\nOur CSS for tables isn't great at the moment so it's almost always better\nto use \u003c\u003chorizonta-defn-list\u003e\u003e instead, but if you really want to use\ntables, you can read about them https://asciidoctor.org/docs/user-manual/#tables[here].\n\n[[edit_me]]\n== Edit links\n\nWe automatically generate `edit` links for most sections to make it easier for\nfolks to contribute simple fixes and to help folks find the asciidoc file that\ngenerated a particular section. It should appear next to every title-like thing.\n\nBooks built with Asciidoctor will automatically pick the correct url for all\nfiles and by default doesn't support overriding `edit_url`. This is mostly a\ngood thing because the overridden `edit_url`s were out of date in many cases.\n\nSome books override `edit_url` because the asciidoc files in them are not\nauthoritative. In that case they set `edit_url` to the \"real\" place to make the\nchange. Sometimes this is another repository and sometimes it is some code that\ngenerates the asciidoc files. These books should add\n`respect_edit_url_overrides` to their config. While it isn't required for\nAsciiDoc it is required for Asciidoctor.\n\n[[chunking]]\n== Controlling chunking\n\nIn \u003c\u003cstructure\u003e\u003e, we said that each `part` or `chapter` generates\na new _chunk_ or HTML file.  For more complex documentation,\nyou may want the first level of ++section++s to also generate\nnew chunks.\n\nFor example:\n\n[source,asciidoc]\n----\n= 1st-level page                    // part\n\n== 2nd-level child page             // chapter\n\n=== 3rd-level child page            // section level 1\n\n=== Another 3rd-level child page    // section level 1\n\n... etc ...\n----\n\nThis renders in the TOC as follows:\n\nimage::resources/readme/chunking-toc.png[TOC screenshot]\n\n=== Enabling section chunking\n\nTo enable section chunking when building docs in a \u003c\u003clocal,local repository\u003e\u003e,\npass the `--chunk` parameter:\n\n[source,bash]\n----------------------------------\nbuild_docs --doc path/to/index.asciidoc --chunk 1\n----------------------------------\n\nTo enable section chunking when building docs \u003c\u003cwebsite,for the website\u003e\u003e,\nadd `chunk: 1` to the\nhttps://github.com/elastic/docs/blob/master/conf.yaml[`conf.yaml`] file in the `docs` repo.\n\n[source,yaml]\n----------------------------------\ncontents:\n    -\n        title:      Elasticsearch Guide\n        prefix:     elasticsearch/reference\n        repo:       elasticsearch\n        index:      docs/reference/index.asciidoc\n        chunk:      1 \u003c1\u003e\n----------------------------------\n\n\u003c1\u003e Chunking is enabled for this book\n\n=== Chunking selected sections\n\nIf you enable session chunking, you will probably find\nthat you have a few short sections which you want to keep on\nthe same page.\n\nTo do this, you can use the `[discrete]` marker before a\nsection header, to indicate that what follows isn't\na \"real\" header:\n\n[source,asciidoc]\n----------------------------------\n[[chapter-one]]\n== chapter              // new chunk\n\n[[section-one]]\n=== Section one         // new chunk\n\n[discrete]\n[[section-two]]\n=== Section two         // same chunk\n\n[[section-three]]\n=== Section three       // new chunk\n----------------------------------\n\nThe above would produce three HTML files,\nnamed for their IDs:\n\n* `chapter-one.html`\n* `section-one.html` which would also contain\n  \"Section two\"\n* `section-three.html`\n\nTo link to \"Section two\" from an external\ndocument, you would use the URL: `section-one.html#section-two`\n\n[[tabbed-widgets]]\n== Tabbed widgets\n\nImprove the usability of your docs by adding tabbed widgets.\nThese handy widgets let you conditionally display content based on the selected tab.\nBest 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.\n\nHow do they work? I'm glad you asked.\nTabbed widgets use https://docs.asciidoctor.org/asciidoc/latest/pass/pass-block/[HTML passthrough blocks] to pass raw HTML into the build.\nBecause of this hack, you must use `include::` statements to render content within a tabbed widget.\n\nHere's an example:\n\n**`widget.asciidoc`**\n\n[source,asciidoc]\n----\n++++\n\u003cdiv class=\"tabs\" data-tab-group=\"custom-tab-group-name\"\u003e \u003c1\u003e\n  \u003cdiv role=\"tablist\" aria-label=\"Human readable name of tab group\"\u003e\n    \u003cbutton role=\"tab\"\n            aria-selected=\"true\" \u003c2\u003e\n            aria-controls=\"cloud-tab-config-agent\" \u003c3\u003e\n            id=\"cloud-config-agent\"\u003e \u003c4\u003e\n      Tab #1 title\n    \u003c/button\u003e\n    \u003cbutton role=\"tab\"\n            aria-selected=\"false\"\n            aria-controls=\"self-managed-tab-config-agent\"\n            id=\"self-managed-config-agent\"\n            tabindex=\"-1\"\u003e \u003c5\u003e\n      Tab #2 title\n    \u003c/button\u003e\n  \u003c/div\u003e\n  \u003cdiv tabindex=\"0\"\n       role=\"tabpanel\"\n       id=\"cloud-tab-config-agent\"\n       aria-labelledby=\"cloud-config-agent\"\u003e\n++++\n\n// You must use a tagged region for Asciidoc content to render. For example:\n// include::content.asciidoc[tag=central-config]\n\n++++\n  \u003c/div\u003e\n  \u003cdiv tabindex=\"0\"\n       role=\"tabpanel\"\n       id=\"self-managed-tab-config-agent\"\n       aria-labelledby=\"self-managed-config-agent\"\n       hidden=\"\"\u003e\n++++\n\n// You must use a tagged region for Asciidoc content to render. For example:\n// include::content.asciidoc[tag=reg-config]\n\n++++\n  \u003c/div\u003e\n\u003c/div\u003e\n++++\n----\n\u003c1\u003e Any tabbed widgets on the same page and with the same name will sync tabs when switched\n\u003c2\u003e Only one tab should have aria-selected set to true. This tab will be selected by default\n\u003c3\u003e The `button.aria-controls` value must match the `div.id` value of its corresponding content bucket\n\u003c4\u003e The `button.id` value must match the `div.aria-labelledby` value of its corresponding content bucket\n\u003c5\u003e All unselected tabs must have a `tabindex` of `-1`\n\n**`content.asciidoc`**\n\n[source,asciidoc]\n----\n// tag::central-config[]\nThis is where the content for tab #1 goes.\n// end::central-config[]\n\n// tag::reg-config[]\nThis is the content for tab #2 goes.\n// end::reg-config[]\n----\n\n[[global-banners]]\n== Global banners\n\nAdd 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].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felastic%2Fdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fdocs/lists"}