« Asciidoc Guide Multi-part books »
Elastic Docs ›Docs HOWTO ›Asciidoc Guide

Basic book structure

edit

Basic book structure

edit

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:

= 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 Elasticsearch Guide, require a few additional elements, described on the following pages.

Filenames

edit

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:

[[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 Controlling chunking for more.

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

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

edit

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:

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

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

Words.

  2. You may use the pass block but it isn’t recommended:

    == Intro to XYZ
++++
<titleabbrev>XYZ Intro</titleabbrev>
++++

Words.
« Asciidoc Guide Multi-part books »