docs-builder
Loading

Code

Code blocks can be used to display multiple lines of code. They preserve formatting and provide syntax highlighting when possible.

Start and end a code block with a code fence. A code fence is a sequence of at least three consecutive backtick characters ```. You can optionally add a language identifier to enable syntax highlighting.

project:
  title: MyST Markdown
  github: https://github.com/jupyter-book/mystmd
```yaml
project:
  title: MyST Markdown
  github: https://github.com/jupyter-book/mystmd
```

There are two ways to add callouts to a code block. When using callouts, you must use one callout format. You cannot combine explicit and magic callouts.

Add <\d+> to the end of a line to explicitly create a code callout.

An ordered list with the same number of items as callouts must follow the code block. If the number of list items doesn’t match the callouts, docs-builder will throw an error.

project:
  license:
    content: CC-BY-4.0
  1. The license
```yaml
project:
  license:
    content: CC-BY-4.0 <1>
```

1. The license

You can also have one block element in between the code block and the callout list:

var input1 = "World";
var input2 = "Elastic";

function render(input) {
    return `Hello, ${input}!`;
}

render(input1);
render(input2);

Inputs:

  1. World
  2. Elastic

Outputs:

  1. Hello, World!
  2. Hello, Elastic!
```javascript
var input1 = "World"; // <1>
var input2 = "Elastic"; // <2>

function render(input) {
    return `Hello, ${input}!`;
}

render(input1);
render(input2);
```

**Inputs:**

1. `World`
2. `Elastic`

**Outputs**:

1. `Hello, World!`
2. `Hello, Elastic!`

If a code block contains code comments in the form of // or #, callouts will be magically created 🪄.

var apiKey = new ApiKey("<API_KEY>");
var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
  1. Set up the api key
```csharp
var apiKey = new ApiKey("<API_KEY>"); // Set up the api key
var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
```

Code comments must follow code to be hoisted as a callout. For example:

// THIS IS NOT A CALLOUT
var apiKey = new ApiKey("<API_KEY>");
var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
  1. This is a callout
```csharp
// THIS IS NOT A CALLOUT
var apiKey = new ApiKey("<API_KEY>"); // This is a callout
var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
```

You can align callouts with spaces.

foo: 1
barbar: 2
bazbazbaz: 3
  1. Foo
  2. Bar
  3. Baz
```yaml
foo: 1       <1>
barbar: 2    <2>
bazbazbaz: 3 <3>
```

1. Foo
2. Bar
3. Baz

You can disable callouts by adding a code block argument callouts=false.

project:
  license:
    content: CC-BY-4.0 <1>
  1. The license
```yaml callouts=false
project:
  license:
    content: CC-BY-4.0 <1>
```

1. The license
Note

This feature is still being developed.

We document a lot of API endpoints at Elastic. For these endpoints, we support console as a language. The term console relates to the dev console in kibana which users can link to directly from these code snippets.

In a console code block, the first line is highlighted as a dev console string and the remainder as json:

 GET /mydocuments/_search {
    "from": 1,
    "query": {
        "match_all" {}
    }
}
```console
GET /mydocuments/_search
{
    "from": 1,
    "query": {
        "match_all" {}
    }
}
```

You can use substitutions to insert reusable values into your code block examples. Check the code blocks substitutions syntax for more information.

Use backticks to create an inline code span. Inline code spans are useful for short code snippets or variable names.

This code is inline.

This `code` is inline.
## This `code` is in a heading.

Please refer to hljs.ts for a complete list of supported languages.