solr/solr-ref-guide/src/meta-docs/asciidoc-syntax.adoc

= AsciiDoc Syntax Cheatsheet
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

The definitive manual on AsciiDoc syntax is in the http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]. To help people get started, however, here is a simpler cheat sheet.

== AsciiDoc vs Asciidoctor Syntax
We use tools from the Asciidoctor project to build the HTML version of the Ref Guide. Asciidoctor is a Ruby port of the original AsciiDoc project, which was mostly abandoned several years ago.

While much of the syntax between the two is the same, there are many conventions supported by Asciidoctor that did not exist in AsciiDoc. While the Asciidoctor project has tried to provide back-compatibility with the older project, that may not be true forever. For this reason, it's strongly recommended to only use the Asciidoctor User Manual as a reference for any syntax that's not described here.

== Basic AsciiDoc Syntax

=== Bold

Put asterisks around text to make it *bold*.

More info: http://asciidoctor.org/docs/user-manual/#bold-and-italic

=== Italics

Use underlines on either side of a string to put text into _italics_.

More info: http://asciidoctor.org/docs/user-manual/#bold-and-italic

=== Headings

Equal signs (`=`) are used for heading levels. Each equal sign is a level. Each page can *only* have one top level (i.e., only one section with a single `=`).

Levels should be appropriately nested. During the build, validation occurs to ensure that level 3s are preceded by level 2s, level 4s are preceded by level 3s, etc. Including out-of-sequence heading levels (such as a level 3 then a level 5) will not fail the build, but will produce an error.

More info: http://asciidoctor.org/docs/user-manual/#sections

== Code Examples

Use backticks ``` for text that should be monospaced, such as code or a class name in the body of a paragraph.

More info: http://asciidoctor.org/docs/user-manual/#mono

Longer code examples can be separated from text with `source` blocks. These allow defining the syntax being used so the code is properly highlighted.

.Example Source Block
[source]
----
[source,xml]
<field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />
----

If your code block will include line breaks, put 4 hyphens (`----`) before and after the entire block.

More info: http://asciidoctor.org/docs/user-manual/#source-code-blocks

=== Source Block Syntax Highlighting

The HTML output uses Rouge to add syntax highlighting to code examples. This is done by adding the language of the code block after the `source`, as shown in the above example source block (`xml` in that case).

Rouge has a long selection of lexers available. You can see the full list at https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers. Use one of the valid short names to get syntax highlighting for that language.

Ideally, we will have an appropriate lexer to use for all source blocks, but that's not possible. When in doubt, choose `text`, or leave it blank.

=== Importing Code Snippets from Other Files

The build system has the ability to "include" snippets located in other files -- even non-AsciiDoc files such as `*.java` source code files.

Snippets are bounded by "tag" comments placed at the start and end of the section you would like to import.  Opening tags look like: `// tag::snippetName[]`.  Closing tags follow the format: `// end::snippetName[]`.  Snippets can be dropped into an `.adoc` file using an `include` directive, following the format: `include::PathToFileWithSnippet[tag=snippetName]`.  Note that when relative paths are provided in these directives, those paths are resolved relative to the location of the AsciiDoc file that the `include` appears in.

Snippets can be included directly from any file in the Lucene/Solr GIT repo by refering to a `solr-root-path` variable prior to the file path, for example:

[source]
--
[source,java,indent=0]
----
\include::{solr-root-path}core/src/java/org/apache/solr/core/SolrCore.java[tag=something]
----
--

When building the Guide, the `solr-root-path` attribute will be automatically set correctly for the (temporary) `build/solr-ref-guide/content` directory used by Ant.

In order for editors (such as ATOM) to be able to offer "live preview" of the `*.adoc` files using these includes, the `solr-root-path` attribute must also be set as a document level attribute in each file, with the correct relative path.

For example, `using-solrj.adoc` sets `solr-root-path` in its header, along with an `example-source-dir` attribute (that depends on `solr-root-path`) in order to reduce redundancy in the many `include::` directives it specifies...

[source]
--
= Using SolrJ
:solr-root-path: ../../
:example-source-dir: {solr-root-path}solrj/src/test/org/apache/solr/client/ref_guide_examples/
...
[source,java,indent=0]
----
\include::{example-source-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-solrclient-timeouts]
----
...
[source,java,indent=0]
----
\include::{example-source-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-other-apis]
----
...
--

For more information on the `include` directive, see the documentation at http://asciidoctor.org/docs/user-manual/#include-partial.

=== Block Titles

Titles can be added to most blocks (images, source blocks, tables, etc.) by simply prefacing the title with a period (`.`). For example, to add a title to the source block example above:

[source]
----
.Example ID field
[source,xml]
<field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />
----

== Links

=== Link to Sites on the Internet
When converting content to HTML, Asciidoctor will automatically render many link types (such as `http:` and `mailto:`) without any additional syntax.

However, you can add a name to a link by adding the URI followed by square brackets:

[source]
http://solr.apache.org/[Solr Website]

=== Link to Other Pages/Sections of the Guide
A warning up front, linking to other pages can be a little bit painful. There are slightly different rules depending on the type of link you want to create, and where you are linking from.

The build process includes a validation for internal or inter-page links, so if you can build the docs locally, you can use that to verify you constructed your link properly (or pay attention to the Jenkins build after your commit).

With all of the below examples, you can add text to display as the link title by adding a comma after the section reference followed by the display text, as in:

[source]
<<schema-api.adoc#modify-the-schema,Modify the Schema>>

==== Link to a Section on the Same Page

To link to an anchor (or section title) on the _same page_, you can simply use double angle brackets (`<< >>`) around the anchor/heading/section title you want to link to. Any section title (a heading that starts with equal signs) automatically becomes an anchor during conversion and is available for deep linking.

Example::
If I have a section on a page that looks like this (from `defining-fields.adoc`):
+
[source]
----
== Field Properties

Field definitions can have the following properties:
----
+
To link to this section from another part of the same `defining-fields.adoc` page, I simply need to put the section title in double angle brackets, as in:
+
[source]
See also the <<Field Properties>> section.
+
The section title will be used as the display text; to customize that add a comma after the the section title, then the text you want used for display.

More info: http://asciidoctor.org/docs/user-manual/#internal-cross-references

==== Link to a Section with an Anchor ID
When linking to any section (on the same page or another one), you must also be aware of any pre-defined anchors that may be in use (these will be in double brackets, like `[[ ]]`). When the page is converted, those will be the references your link needs to point to.

Example::
Take this example from `configsets-api.adoc`:
+
[source]
----
[[configsets-create]]
== Create a ConfigSet
----
+
To link to this section, there are two approaches depending on where you are linking from:

* From the same page, simply use the anchor name: `\<<configsets-create>>`.
* From another page, use the page name and the anchor name: `\<<configsets-api.adoc#configsets-create>>`.

==== Link to Another Page
To link to _another page_ or a section on another page, you must refer to the full filename and refer to the section you want to link to.

Unfortunately, when you want to refer the reader to another page without deep-linking to a section, you cannot simply put the other file name in angle brackets and call it a day.
*You must always link to a specific section*. If all you want is a reference to the top of another page, you can use the implicit `id` of the page -- the filename w/o the `.adoc` extension -- as your anchor reference.

Example::
To construct a link to the `upgrading-solr.adoc` page, we need to refer to the file name (`upgrading-solr.adoc`), then use the page id (`upgrading-solr`) as the anchor reference. As in:
+
[source]
For more information about upgrades, see <<upgrading-solr.adoc#upgrading-solr>>.

==== Link to a Section on Another Page
Linking to a section is the same conceptually as linking to the top of a page, you just need to take a little extra care to format the anchor ID in your link reference properly.

When you link to a section on another page, you must make a simple conversion of the title into the format the section ID will be created during the conversion. These are the rules that transform the sections:
--
* All characters are lower-cased.
** `Using security.json with Solr` becomes `using security.json with solr`
* All non-alpha characters are removed, with the exception of hyphens (so all periods, commas, ampersands, parentheses, etc., are stripped).
** `using security.json with solr` becomes `using security json with solr`
* All whitespaces are replaced with hyphens.
** `using security json with solr` becomes `using-security-json-with-solr`
--
Example::
The file `schema-api.adoc` has a section "Modify the Schema" that looks like this:
+
[source]
----
== Modify the Schema

`POST /_collection_/schema`
----
+
To link from to this section from another page, you would create a link structured like this:
+
--
* the file name of the page with the section (`schema-api.adoc`),
* then the hash symbol (`#`),
* then the converted section title (`modify-the-schema`),
* then a comma and any link title for display.
--
+
The link in context would look like this:
+
[source]
For more information, see the section <<schema-api.adoc#modify-the-schema,Modify the Schema>>.

More info: http://asciidoctor.org/docs/user-manual/#inter-document-cross-references

== Ordered and Unordered Lists

AsciiDoc supports three types of lists:

* Unordered lists
* Ordered lists
* Labeled lists

Each type of list can be mixed with the other types. So, you could have an ordered list inside a labeled list if necessary.

=== Unordered Lists
Simple bulleted lists need each line to start with an asterisk (`*`). It should be the first character of the line, and be followed by a space.

These lists also need to be separated from the

More info: http://asciidoctor.org/docs/user-manual/#unordered-lists

=== Ordered Lists
Numbered lists need each line to start with a period (`.`). It should be the first character of the line, and be followed by a space.

This style is preferred over manually numbering your list.

More info: http://asciidoctor.org/docs/user-manual/#ordered-lists

=== Labeled Lists
These are like question & answer lists or glossary definitions. Each line should start with the list item followed by double colons (`::`), then a space or new line.

Labeled lists can be nested by adding an additional colon (such as `:::`, etc.).

If your content will span multiple paragraphs or include source blocks, etc., you will want to add a plus sign (`+`) to keep the sections together for your reader.

TIP: We prefer this style of list for parameters because it allows more freedom in how you present the details for each parameter. For example, it supports ordered or unordered lists inside it automatically, and you can include multiple paragraphs and source blocks without trying to cram them into a smaller table cell.

More info: http://asciidoctor.org/docs/user-manual/#labeled-list

== Images

There are two ways to include an image: inline or as a block.

Inline images are those where text will flow around the image. Block images are those that appear on their own line, set off from any other text on the page.

Both approaches use the `image` tag before the image filename, but the number of colons after `image` define if it is inline or a block. Inline images use one colon (`image:`), while block images use two colons (`image::`).

Block images automatically include a caption label and a number (such as `Figure 1`). If a block image includes a title, it will be included as the text of the caption.

Optional attributes allow you to set the alt text, the size of the image, if it should be a link, float and alignment.

More info: http://asciidoctor.org/docs/user-manual/#images

== Tables

Tables can be complex, but it is pretty easy to make a basic table that fits most needs.

=== Basic Tables
The basic structure of a table is similar to Markdown, with pipes (`|`) delimiting columns between rows:

[source]
----
|===
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===
----

Note the use of `|===` at the start and end. For basic tables that's not exactly required, but it does help to delimit the start and end of the table in case you accidentally introduce (or maybe prefer) spaces between the rows.

=== Header Rows
To add a header to a table, you need only set the `header` attribute at the start of the table:

[source]
----
[options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===
----

=== Defining Column Styles
If you need to define specific styles to all rows in a column, you can do so with the attributes.

This example will center all content in all rows:

[source]
----
[cols="2*^" options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===
----

Alignments or any other styles can be applied only to a specific column. For example, this would only center the last column of the table:

[source]
----
[cols="2*,^" options="header"]
|===
| header col 1 | header col 2|
| col 1 row 1 | col 2 row 1|
| col 1 row 2 | col 2 row 2|
|===
----

Many more examples of formatting:

* Columns: http://asciidoctor.org/docs/user-manual/#cols-format
* Cells: http://asciidoctor.org/docs/user-manual/#cell

=== More Options

Tables can also be given footer rows, borders, and captions. You can  determine the width of columns, or the width of the table as a whole.

CSV or DSV can also be used instead of formatting the data in pipes.

More info: http://asciidoctor.org/docs/user-manual/#tables

== Admonitions (Notes, Warnings)

AsciiDoc supports several types of callout boxes, called "admonitions":

* NOTE
* TIP
* IMPORTANT
* CAUTION
* WARNING

It is enough to start a paragraph with one of these words followed by a colon (such as `NOTE:`). When it is converted to HTML, those sections will be formatted properly - indented from the main text and showing an icon inline.

You can add titles to admonitions by making it an admonition block. The structure of an admonition block is like this:

[source]
----
.Title of Note
[NOTE]
====
Text of note
====
----

In this example, the type of admonition is included in square brackets (`[NOTE]`), and the title is prefixed with a period. Four equal signs give the start and end points of the note text (which can include new lines, lists, code examples, etc.).

More info: http://asciidoctor.org/docs/user-manual/#admonition

== STEM Notation Support

We have set up the Ref Guide to be able to support STEM notation whenever it's needed.

The http://asciimath.org/[AsciiMath] syntax is supported by default, but LaTeX syntax is also available.

To insert a mathematical formula inline with your text, you can simply write:

[source]
----
stem:[a//b]
----

MathJax.js will render the formula as proper mathematical notation when a user loads the page.
When the above example is converted to HTML, it will look like this to a user: stem:[a//b]

To insert LaTeX, preface the formula with `latexmath` instead of `stem`:

[source]
----
latexmath:[tp \leq 1 - (1 - sim^{rows})^{bands}]
----

Long formulas, or formulas which should to be set off from the main text, can use the block syntax prefaced by `stem` or `latexmath`:

[source]
----
[stem]
++++
sqrt(3x-1)+(1+x)^2 < y
++++
----

or for LaTeX:

[source]
----
[latexmath]
++++
[tp \leq 1 - (1 - sim^{rows})^{bands}]
++++
----

More info: https://asciidoctor.org/docs/user-manual/#stem-in