This documentation build process is provided to the public purely for the purpose of testing documentation changes before submitting pull requests to the appropriate Elasticsearch repository.
The documents produced by this build process may be published only on http://www.elastic.co. They may not be published in any other form or on any other website without explicit permission.
You’ll need bash
and docker
.
Clone the docs
repository with:
git clone [email protected]:elastic/docs.git
You can test that everything is working correctly by building this README as follows:
cd docs/
./build_docs --doc README.asciidoc --open
This should convert README.asciidoc
into HTML and open it
in your browser.
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 path/to/index.asciidoc
Some documentation books require more complex build commands.
doc_build_aliases.sh
provides simplified aliases and the build commands for each book.
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/
Warning
|
The output/dir/ will be deleted and recreated, so don’t
point it at a directory that contains anything you are fond of.
|
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
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
Note
|
The multi-page output always contains tables-of-content where appropriate. |
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 mot 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
Note
|
If you leave out the --chunk flag we’ll use the default chunking.
|
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 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 theelasticsearch
repo, run:./docs/build_docs --all --target_repo [email protected]: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:
./build_docs --all --target_repo [email protected]:elastic/built-docs.git --open
The first time you run a full build is slow as it 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.
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:
@elasticmachine run docs build
or
@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:
@elasticmachine run elasticsearch-ci/docs rebuild
The documentation that appears on the http://www.elastic.co/guide
website is controlled by the
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 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
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.
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 {ref}[Elasticsearch reference docs], however, require a few additional elements, described on the following pages.
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.
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:[id=intro_to_xyz,titleabbrev=" XYZ Intro"] == Intro to XYZ Words.
-
You may use the pass block but it isn’t recommended:
== Intro to XYZ ++++ <titleabbrev>XYZ Intro</titleabbrev> ++++ Words.
Books may also be divided into multiple parts, which are indicated
with level 0
headers:
= 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.
A part
may include text before the first chapter
, but
it must be marked with [partintro]
in order to be valid:
= 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
open block
which starts and ends with two dashes: --
:
= Part two // level 0
[partintro]
.A partintro title
-- <1>
This section may contain multiple paragraphs.
[float]
== A header should use [float]
Everything up to the closing -- marker
will be considered part of the partintro.
-- <1>
== Chapter title // level 2
... etc ...
-
The open block delimiters
Books may include other sections such as a preamble, a preface, a glossary or appendices.
[preface]
= Preface title // level 0
=== Preface header // level 2 (1)
= Part one // level 0
and
[appendix]
= Appendix title // level 0
=== Appendix header // level 2 (1)
-
Any headers in the appendix or in the preface start out-of-sequence at
level 2
, not atlevel 1
.
[glossary]
= Glossary title // level 0
[glossary]
Term one::
Defn for term one
Term two::
Defn for term two
Note
|
The two
|
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 book-multi.txt
.
A paragraph consists of multiple lines of text which start in the left hand column:
This is a paragraph
even though it contains
line breaks.
This is a second paragraph.
Like most elements, a paragraph can have a title:
.Paragraph title
Text of my paragraph
Text of my paragraph
A paragraph which starts with TIP:
, NOTE:
, IMPORTANT:
,
WARNING:
or CAUTION:
is rendered as an admonition paragraph,
eg:
NOTE: Compare admonition paragraphs with <<admon-blocks>>.
This renders as:
Note
|
Compare admonition paragraphs with Admonition blocks. |
Literal paragraphs, which are rendered as <pre>
blocks without any source highlighting, must be
indented:
.Optional title
This para must
be indented
This para must be indented
See also Code blocks for blocks with syntax highlighting.
Inline text can be formatted as follows:
_emphasis_
|
emphasis |
*bold*
|
bold |
`mono'
|
|
^superscript^
|
superscript |
~subscript~
|
subscript |
These formatting characters expect to adjoin whitespace or
common punctuation characters. To combine bold with emphasis,
double up the quotes (ie use __
and **
):
This example co__mb**in**es__ bold and emphasis
This example combines bold and emphasis.
Unwanted quotes can be escaped with a \
character.
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:
[[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:
[[note-id]]
[NOTE]
===============================
This note can be linked to using the ID `note-id`.
===============================
or in one line:
["NOTE",id="note-id"] (1)
===============================
This note can be linked to using the ID `note-id`.
===============================
-
In the one line format, the
NOTE
must be enclosed in double quotes.
Both of the above render as:
Note
|
This note can be linked to using the ID |
The ID
is added to the HTML document as an <a>
anchor
and, as explained in Controlling chunking, the ID
is used as the
filename for sections which are chunked — written to
separate HTML files.
You can link to any ID within a document using double angle brackets:
* <<setup>>
* <<structure>>
* <<note-id>>
It will use the title associated with each ID as the
link text. In the example above, note-id
is not associated
with any title, which is why the text is rendered as "Note"
.
Alternative link text can be provided as a second parameter inside the angle brackets:
See the <<note-id,note about IDs>>.
See the note about IDs.
Links to external websites can just be added as normal inline text, optionally with custom link text in square brackets:
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.
Links to other Elasticsearch docs 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 shared attributes file to resolve links:
= 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]
Here is a link to the {ref}/search.html[search page]
Books that use the attributes file should declare a dependency on it in
conf.yaml
like this:
-
repo: docs
path: shared/versions/stack/{version}.asciidoc
-
repo: docs
path: shared/attributes.asciidoc
or
-
repo: docs
path: shared/versions/stack/current.asciidoc
-
repo: docs
path: shared/attributes.asciidoc
For books that don’t use the shared attributes file, the attributes appear at the beginning of the docs, under the book title:
= My Book Title
Here is a link to the {ref}/search.html[search page]
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 Building all of the Elastic docs.
Bullet point lists are written using asterisks:
.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.
-
Point
-
Point
-
Sub-point
-
Sub-point
-
-
❏ TODO
-
✓ 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 use .
instead of *
, and will alternate
between numbers and letters automatically:
.Optional title
. foo
.. bar
... baz
.... balloo
-
foo
-
bar
-
baz
-
balloo
-
-
-
For more information, see https://asciidoctor.org/docs/user-manual/#ordered-lists
Definition lists are used to define terms. The term must be
followed by a double colon ::
eg:
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
-
Often definition lists are better rendered horizontally, eg:
[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
term one |
Definition for term one |
term two |
Can start on the next line |
term three |
A definition can have multiple paragraphs, but use
|
term five |
A definition can even include lists:
|
Blocks are used for special blocks of content, such as Code blocks, Example blocks, Sidebars and Admonition blocks.
Blocks are delimited with a start and end line which uses
the same characters, like =====
.
Code blocks are rendered as <pre>
blocks, and use
syntax highlighting, eg:
.Optional title
[source,js]
----------------------------------
{
"query": "foo bar"
}
----------------------------------
{
"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.
|
Code blocks can use callouts to add an explanatory footnote to a particular line of code:
[source,js]
----------------------------------
{
"query": "foo bar" <1>
}
----------------------------------
<1> Here's the explanation
{
"query": "foo bar" (1)
}
-
Here’s the explanation
Code blocks can be followed by a "Copy as cURL" link which will convert the snippet into a sequence of calls to the ubiquitous 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 "View 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:
[source,console]
----------------------------------
GET /_search
{
"query": "foo bar" <1>
}
----------------------------------
<1> Here's the explanation
Which renders as:
GET /_search
{
"query": "foo bar" (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:
[source,kibana]
----------------------------------
GET /
----------------------------------
Which renders as:
GET /
For Elasticsearch Service do this:
[source,ess]
----------------------------------
GET /
----------------------------------
Which renders as:
GET /
For Elastic Cloud Enterprise do this:
[source,ece]
----------------------------------
GET /
----------------------------------
Which renders as:
GET /
If Console
requests are followed by a "response" then it should be written
with the language set to console-response
. That will allow
alternative examples to find the responses.
Like this:
[source,console-result]
----------------------------------
{
"hits": {
"total": { "value": 0, "relation": "eq" },
"hits": []
}
}
----------------------------------
Which should render as:
{
"hits": {
"total": { "value": 0, "relation": "eq" },
"hits": []
}
}
Admonition blocks are much the same as Admonition paragraphs, except that they can be longer and contain more than just a paragraph. For instance:
[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:
and some code { "query": "foo bar"} |
Sidebars are used to highlight a block of content that is outside the usual flow of text:
.Optional title
**********************************
So why does the `bulk` API have such a
funny format? Sit down and I'll tell you
all about it!
**********************************
So why does the bulk
API have such a
funny format? Sit down and I’ll tell you
all about it!
Example blocks contain normal text which is used as an example. The title, if any, is labelled as an example and numbered:
.My first example
========================================
Text explaining the first example.
========================================
.My second example
========================================
Text explaining the second example.
========================================
This renders as:
Text explaining the first 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:
[%collapsible]
.An example
====
Lots of text can go in here.
====
Which renders as:
An example
Lots of text can go in here.
For long documentation, you probably want to break up the Asciidoc files into smaller units, and just include them where appropriate:
include::myfolder/mydoc.asciidoc[]
Paths are relative to the file which
contains the include
statement.
If you have to include files in a different repository then use its -root
attribute to locate the files:
include::{elasticsearch-root}/docs/foo.asciidoc[]
Books that reference another repository should register that reference in
conf.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.
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.
Use inline notifications for small changes, such as the addition or deprecation of individual parameters.
[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]
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:
[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`]
foo.bar
|
Does XYZ. added:[0.90.4,Replaces |
foo.bar
|
Does XYZ. coming:[0.90.4,Replaces |
foo.baz
|
Does XYZ. deprecated:[0.90.4,Replaced by |
Note
|
If the details include a comma, you must use quotation marks. For example: deprecated[1.1.0,"Span started automatically by <<apm-start-span,apm.startSpan()>>"] |
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:
==== 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...
Or they can include extra text, including more Asciidoc markup:
[[new-section]]
==== New section
added::[0.90.4,Replaces `foo.bar`. See <<old-section>>]
Text about new functionality...
[[coming-section]]
==== New section not yet released
coming::[0.90.9,Replaces `foo.bar`. See <<old-section>>]
Text about new functionality...
[[old-section]]
==== Old section
deprecated::[0.90.4,Replace by `foo.baz`. See <<new-section>>]
Text about old functionality...
APIs or parameters that are experimental or in beta can be marked as such, using markup similar to that used in Additions and deprecations.
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.
For instance:
[[new-feature]]
=== New experimental feature
experimental::[]
experimental::[https://github.com/elastic/docs/issues/505]
experimental::[{issue}505]
experimental::[Custom text goes here]
experimental::[Custom text goes here,https://github.com/elastic/docs/issues/505]
experimental::[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 experimental parameter:
[horizontal]
`established_param`:: This param has been around for ages and won't change.
`experimental_param`:: experimental:[] This param is experimental and may change in the future.
`experimental_param`:: experimental:[Custom text goes here] This param is experimental and may change in the future.
experimental::[]
experimental::[elastic#505]
experimental::[{issue}505]
experimental::[Custom text goes here]
experimental::[Custom text goes here,elastic#505]
experimental::[Custom text goes here,{issue}505]
Text about new feature…
This feature has been around for a while, but we’re adding a new experimental parameter:
established_param
|
This param has been around for ages and won’t change. |
experimental_param
|
experimental:[] This param is experimental and may change in the future. |
experimental_param
|
experimental:[Custom text goes here] This param is experimental and may change in the future. |
[[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 beta parameter:
[horizontal]
`established_param`:: This param has been around for ages and won't change.
`beta_param`:: beta:[] This param is beta and may change in the future.
`beta_param`:: beta:[Custom text goes here] This param is beta and may change in the future.
beta::[]
beta::[elastic#505]
beta::[{issue}505]
beta::[Custom text goes here]
beta::[Custom text goes here,elastic#505]
beta::[Custom text goes here,{issue}505]
Text about new feature…
This feature has been around for a while, but we’re adding a new beta parameter:
established_param
|
This param has been around for ages and won’t change. |
beta_param
|
beta:[] This param is experimental and may change in the future. |
beta_param
|
beta:[Custom text goes here] This param is beta and may change in the future. |
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.
[[cat]]
.A scaredy cat
image::resources/readme/cat.jpg[Alt text]
A link to <<cat>>
A link to A scaredy cat.
The width
and/or height
of the image can be
specified in pixels or as a percentage:
image::resources/readme/cat.jpg["Alt text",width=50]
image::resources/readme/cat.jpg["Alt text",width="20%"]
Images are left-aligned by default, but they can be centred or right-aligned:
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 get extra margins and a box-shadow:
You can activate it with:
[role="screenshot"]
image::resources/readme/screenshot.png[A screenshot example]
You can add a vimeo hosted video with Asciidoctor’s video tag:
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:
Our CSS for tables isn’t great at the moment so it’s almost always better to use Horizontal definition lists instead, but if you really want to use tables, you can read about them here.
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 AsciiDoc will automatically pick the correct url for files
from the "root" repository. It guesses the wrong url for files from other
repositories so you have to manually set edit_url
at the top of each file.
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.
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 instance, in the ES reference docs, we have:
= Search APIs // part
== Request body search // chapter
=== Query // section level 1
=== From/Size // section level 1
... etc ...
There are too many parameters for "Request body search" to list them all on one page. In this case, it is worth turning on chunking for top level sections.
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 reference
prefix: elasticsearch/reference
repo: elasticsearch
index: docs/reference/index.asciidoc
chunk: 1 (1)
-
Chunking is enabled for this book
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 [float]
marker before a
section header, to tell Asciidoc that what follows isn’t
a "real" header:
[[chapter-one]]
== chapter // new chunk
[[section-one]]
=== Section one // new chunk
[[section-two]]
[float]
=== 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