« Lists Including files »

› ›

Blocks

edit

Blocks

edit

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

edit

Code blocks are rendered as <pre> blocks, and use syntax highlighting, eg:

Example 14. A code block

.Optional title
[source,js]
----------------------------------
{
    "query": "foo bar"
}
----------------------------------

Optional title.

{
    "query": "foo bar"
}

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.

Callouts

edit

Code blocks can use callouts to add an explanatory footnote to a particular line of code:

Example 15. Code block with callouts

[source,js]
----------------------------------
{
    "query": "foo bar" <1>
}
----------------------------------
<1> Here's the explanation

{
    "query": "foo bar" 
}

Here’s the explanation

Copy as curl/View in Console

edit

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 "Try 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:

Example 16. Code block with "Copy as curl" and "Try in Console" link for Elasticsearch

[source,console]
----------------------------------
GET /_search
{
    "query": "foo bar" <1>
}
----------------------------------
<1> Here's the explanation

Which renders as:

GET /_search
{
    "query": "foo bar" 
}

Here’s the explanation

In older branches you’ll see // CONSOLE after the snippet to trigger this behavior. That is deprecated.

For Kibana do this:

Example 17. Code block with "Copy as curl" link for Kibana

[source,kibana]
----------------------------------
GET /
----------------------------------

Which renders as:

GET /

For Elasticsearch Service do this:

Example 18. Code block with "Copy as curl" link for Elasticsearch Service

[source,ess]
----------------------------------
GET /
----------------------------------

Which renders as:

GET /

For Elastic Cloud Enterprise do this:

Example 19. Code block with "Copy as curl" link for Elastic Cloud Enterprise

[source,ece]
----------------------------------
GET /
----------------------------------

Which renders as:

GET /

Responses

edit

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

edit

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:

This note contains a list:

and some code

{ "query": "foo bar"}

Sidebars

edit

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!
**********************************

Example blocks

edit

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:

Example 20. My first example

Text explaining the first example.

Example 21. My second example

Text explaining the second example.

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.

« Lists Including files »