« Attribute scope Lists »
Elastic Docs ›Docs HOWTO ›Asciidoc Guide

Linking

edit

Linking

edit

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: [[ID]]

[[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"] 
===============================
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:

This note can be linked to using the ID note-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.

Internal links

edit

You can link to any ID within a document using double angle brackets:

Example 6. Links with default link text

* <<setup>>
* <<structure>>

It will use the title associated with each ID as the link text.

Alternative link text can be provided as a second parameter inside the angle brackets:

Example 7. Links with custom link text

See the <<note-id,note about IDs>>.

See the note about IDs.

External links

edit

Links to external websites can just be added as normal inline text, optionally with custom link text in square brackets:

Example 8. External links

See http://github.com/elastic
or  http://github.com/elastic/docs[this repository]

See http://github.com/elastic or this repository

The existence of external links is not confirmed by the build process.

Cross document links

edit

Links to other Elastic books 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:

Example 9. Using shared attributes for cross-document linking

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

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.

« Attribute scope Lists »