New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« Building documentation Building all of the Elastic docs »
Elastic Docs ›Docs HOWTO ›Building documentation

For a local repo

edit

For a local repo

edit

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:

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. 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 Elasticsearch section in doc_build_aliases.sh file.

Specifying a different output dir

edit

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

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

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

edit

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

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

Single- or multi-page

edit

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:

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:

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

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

Chunking in the right place

edit

Before Christmas 2019 we built all of the docs using 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 conf.yaml file, but must also be specified on the command line when building a single book:

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

If you leave out the --chunk flag we’ll use the default chunking.

Alternative languages for examples

edit

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:

cd docs/
./build_docs --doc README.asciidoc --open \
    --alternatives console:js:integtest/readme_examples/js \
    --alternatives console:csharp:integtest/readme_examples/csharp
« Building documentation Building all of the Elastic docs »