* [Lists with code snippets or images](#lists-with-code-snippets-or-images)
* [Math](#math)
* [Tables](#tables)
* [Text style](#text-style)
* [Variables in curly braces](#variables-in-curly-braces)
* [Videos](#videos)
* * *
## Adding pages or sections
When adding a page or a section, make the `nav_order` of the child pages multiples of 10. For example, if you have a parent page `Clients`, make child pages `Java`, `Python`, and `JavaScript` have a `nav_order` of 10, 20, and 30, respectively. Doing so makes inserting additional child pages easier because it does not require you to renumber existing pages.
## Buttons
You can use either `copy` or `copy-curl` includes for code snippets. The `copy` include places a **Copy** button on the code snippet, while the `copy-curl` include places both **Copy** and **Copy as cURL** buttons. Use the `copy-curl` include for API requests. If an API request is already in the cURL format, use the `copy` include.
Use one dash for hyphens, two for en dashes, and three for em dashes:
```
upper-right
10--12 nodes per cluster
There is one candidate generator available---`direct_generator`.
```
## Horizontal rule
A horizontal rule is used to separate text sections. Use three asterisks separated by spaces for a horizontal rule:
```
## Why use OpenSearch?
* * *
```
## Images
Place images in the `images` directory of the documentation website. To refer to images, use relative links (see [Internal links](#internal-links) for more information).
Markdown images are responsive by default. To insert a Markdown image, use the `` syntax:
To stretch the image to fit the width of the main body panel, use width=“100%”.
To take high-resolution screenshots, in Firefox, right-click on the page and choose “Take Screenshot”.
Image borders are automatic; do not manually add a border to an image.
Always **separate an image from the text with a blank line**:
```
To send a query to OpenSearch, select the query by placing the cursor anywhere in the query text. Then choose the triangle on the top right of the request or press `Ctrl/Cmd+Enter`:
Do not place an image next to text or insert artificial line breaks using `<br>`. Otherwise, the text might render as aligned to the bottom of the image, with the image on the right.
If the image is under a list item, place it on a new line with a tab. For more examples, see [Lists with code snippets or images](#lists-with-code-snippets-or-images).
When describing an icon, use the icon's name followed by an inline image in parentheses. Insert the image in line with text using the `nomarkdown` extension and an HTML image:
```
Choose the play icon ({::nomarkdown}<imgsrc="{{site.url}}{{site.baseurl}}/images/dev-tools/play-icon.png"class="inline-icon"alt="play icon"/>{:/}) on the top right of the request.
Use a purple label to specify the version in which an API was introduced:
```
# Alias
Introduced 1.0
{: .label .label-purple }
```
If we introduce a breaking change to an operation, add an additional label with a link to the release note for that breaking change:
```
## Get roles
Introduced 1.0
{: .label .label-purple }
[Last breaking change 2.0](https://example.com)
{: .label .label-red }
```
## Links
To add a link to a document, section, or image, use the `[name](link)` syntax, for example:
```
## Looking for the Javadoc?
See [opensearch.org/javadocs/](https://opensearch.org/javadocs/).
```
### Section links
**Section links** are links to headings in your document. Markdown lowercases the headings for links, drops back ticks, and replaces spaces with hyphens:
```
## The `minimum_should_match` parameter
For more information, see [the `minimum_should_match` parameter](#the-minimum_should_match-parameter).
```
### Internal links
**Internal links** are links to another document or image within the documentation website. Because the documentation website is versioned, do not hard code the version number in the link. Use the relative path, where `{{site.url}}{{site.baseurl}}` refers to the main directory, instead:
```
If you need to use a field for exact-value search, map it as a [`keyword`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/keyword/).
```
### GitHub links
When linking to a GitHub issue or PR, refer to the issue or PR number in the following format:
```
For more details, see issue [#1940](https://github.com/opensearch-project/opensearch/issues/1940).
```
## Lists
Markdown supports unordered and ordered lists, nested lists, and lists with code snippets or images.
### Unordered lists
Use asterisks or dashes for unordered lists:
```
* One
* Two
```
or
```
- One
- Two
```
Lists with dashes render the list items closer to each other vertically, while lists with asterisks have more space between the lines.
Don’t mix and match asterisks and dashes.
### Ordered lists
Use all 1s for ordered lists:
```
1. One
1. Two
```
Jekyll will automatically correctly number the items, and it will be much easier for you to insert and delete items without renumbering.
If there is a paragraph in the middle of a list, the list will restart with 1 after the paragraph. If you want to continue the list after the paragraph, use `counter-reset: none`:
```
1. One
Paragraph that breaks the numbering
{:style="counter-reset: none"}
1. Two
```
### Nested lists
Use tabs to nest lists:
```
1. Parent 1
- Child 1
- Child 2
- Grandchild 1
```
Markdown automatically adjusts numbered lists so that they use numbers and letters, so always use 1s for nested numbered lists.
### Lists with code snippets or images
If you need to position an image or a code snippet within a list, use tabs to signal to Markdown that the image or code snippet is part of the list item.
**Example with code snippets**
```
1. Run the demo batch script.
There are two ways of running the batch script:
1. Run the batch script using the Windows UI:
1. Navigate to the top directory of your OpenSearch installation and open the `opensearch-{{site.opensearch_version}}` folder.
1. Run the batch script by double-clicking the `opensearch-windows-install.bat` file. This opens a command prompt with an OpenSearch instance running.
1. Run the batch script from Command prompt or Powershell:
1. Open Command Prompt by entering `cmd`, or Powershell by entering `powershell`, in the search box next to ****Start**** on the taskbar.
1. Change to the top directory of your OpenSearch installation.
```bat
cd \path\to\opensearch-{{site.opensearch_version}}
1. Select the **Duplicate** button in the upper-right corner of the pane. The **Duplicate rule** window opens in Visual Editor view, and all of the fields are automatically populated with the rule's details. Details are also populated in YAML Editor view, as shown in the following image.
<imgsrc="{{site.url}}{{site.baseurl}}/images/Security/dupe-rule.png"alt="Selecting the duplicate button opens the Duplicate rule window"width="50%">
```
## Math
To add mathematical expressions to a page, add `has_math: true` to the page’s front matter. Then insert LaTeX math into HTML tags with the rest of your Markdown content, as shown in the following example:
```
## Math
Some Markdown paragraph. Here's a formula:
<p>
When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
\[x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\]
</p>
And back to Markdown.
```
## Tables
Markdown table columns are automatically sized, and there is no need to specify a different number of dashes in the formatting.
**Example**
```
Header 1 | Header 2
:--- | :---
Body 1 | Body 2, which is extremely lengthy, but there is no need to specify its width.
```
To insert line breaks within tables, use `<br>`:
```
Header 1 | Header 2
:--- | :---
Body 1 | Body paragraph 1 <br> Body paragraph 2
```
To use lists within a table, use `<br>` and `-` :
```
Header 1 | Header 2
:--- | :---
Body 1 | List:<br>- One<br>- Two
```
You can also use ` ` to insert one space, ` ` to insert two spaces, and ` ` to insert four spaces in table cells.
If you need a list with real bullet points, use the bullet point HTML code:
```
Header 1 | Header 2
:--- | :---
Body 1 | List:<br> • One<br> • Two
```
## Text style
You can style text in the following ways:
* ```**bold**```
* ```_italic_``` or ```*italic*```
## Variables in curly braces
To correctly display variables that are in curly braces, escape the curly braces with the `{% raw %}{% endraw %}` tags:
````
"message_template": {
"source": "the index is {% raw %}{{ctx.index}}{% endraw %}"
}
````
The variable `ctx.index` is rendered in double curly braces.
## Videos
To insert a video, add a YouTube player include similar to the following:
```
{% include youtube-player.html id='_g46WiGPhFs' %}
```
Note that the `id` variable refers to the YouTube video ID at the end of the URL. For example, the YouTube video at the URL `https://youtu.be/_g46WiGPhFs` has the ID `_g46WiGPhFs`. The ID must be surrounded with single quotation marks.
