« Edit links Tabbed widgets »
Elastic Docs ›Docs HOWTO ›Asciidoc Guide

Controlling chunking

edit

Controlling chunking

edit

In Basic book structure, 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 sections to also generate new chunks.

For example:

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

TOC screenshot

Enabling section chunking

edit

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

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

To enable section chunking when building docs for the website, add chunk: 1 to the conf.yaml file in the docs repo.

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

Chunking is enabled for this book

Chunking selected sections

edit

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:

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

« Edit links Tabbed widgets »