Introduction

Follow these guidelines to ensure consistent formatting of all external documentation.

Section Headings

Asciidoctor makes all section headings into anchors.

Try to make section headers as specific as possible, so the anchors are descriptive in case when sharing links to specific sections of the docs.
- Don't: == Installing
- Do: == Installing <feature_name>

The syntax for an internal link to an anchor is <<_anchor_title,link text>>.

The syntax for the anchor itself (often a section heading, but not required to be one): [[_anchor_title]]anchor text.

Ensure section titles have a blank line preceding them or they will not render correctly.

Each topic should be in it's own .adoc file with appropriate header settings. For document reuse, start each file's heading sections at level two (== Title). The jbake template will adjust the level to the appropriate setting in the target document.

Paragraphs

To help with editability, each sentence should be on a new line. Asciidoctor renders them as a single paragraph, until a blank line signals a new paragraph. This makes it easier to browse and make corrections. A possible exception is within tables or lists where it may affect the readability of the table syntax.

When a section title is changed, external and internal links will be be broken. Do a search for the _anchor_title to find internal links.

Links

External Links

When including external URLs in documentation, to avoid displaying the entire URL, use this following Asciidoctor format:

http://google.com[link text]

Internal Links

EXPERIMENTAL - This section refers to new functionality created in version 2.14.0

Special formatting is used to create links within and between pages of documentation. Links can send user to a separate section of the current document or another page in the documentation library. These are the conventions of creating those links

<<{target-prefix}anchor_text,Display Text>>

The Asciidoc syntax for an internal link is wrapped in double angle-brackets << >>.
Each target document template file sets a set of properties for the other target documents that will resolve and send the reader to that page.
- Introduction ({introduction-prefix}): Overview of concepts, standards, and capabilities.
- Quick Start ({quickstart-prefix}): Instructions for a test or demo instance.
- Managing ({managing-prefix}): Instructions for a hardened production instance.
- Using ({using-prefix}): Instructions for users querying and ingesting data.
- Integrating ({integrating-prefix}): Instructions for integrators connecting to an instance externally
- Architecture ({architecture-prefix}): Description of system architecture.
- Developing ({developing-prefix}): Instructions for creating custom implementation of components.
- Reference ({reference-prefix}): Reference material for configurations and features.
- Metadata Reference ({metadata-prefix}): Reference for metadata schemas and attributes.
Next, use the anchor text you are linking to. (minus the leading underscore-- that is added by the prefix property,
A comma separates the anchor itself from the display text.
Display text should describe the information being linked to. This is often the section header, but, if needed, should be modified to fit the sentence and context of the paragraph where the link appears.

Anchors

Section headings create automated anchors based on the text of the header with a leading underscore and spaces replaced with underscores.

== Section Heading

becomes

_section_heading

Manual anchors can also be created to link to any arbitrary spot in the text and should follow the same conventions in most cases. Asciidoctor anchors have a syntax as follows:

[[_manual_anchor]]Anchor Text

The square brackets define an anchor.
Use the leading underscore instead of the prefix because this anchor is only a destination, not a link.
The anchor text is arbitrary. Manual anchors should usually be used for captions or the start of a relevant

Special Formatting Conventions

Element	Convention	Example	Comments
Titles of documents	normal
File types	normal	a pdf file
File names / file paths / URIs / URLs	`monospace`	`/etc/security`
Error messages	sentence case, quoted
Names of Organizations or Companies	normal	... the Apache Foundation
email addresses	`monospace`
Names of products and versions	normal
Sample usernames / passwords	`monospace`
Ports used in a sentence	normal
IP addresses / ports	`monospace`
Input or parameters	`monospace`
references to line numbers (in code samples)	normal		avoid if possible
Inline code quotes	`monospace`
Code Blocks	`monospace`		See code block table for other formatting conventions
Button names / Menu Names / Icon Names	bold
Application names(referenced in a sentence)	normal
Application tab (in instruction sequences)	bold		bold anything "clickable"

Writing About Procedures

Maintain consistency when writing instructions for procedures.

Admin Console Procedures

Start any installation or configuration procedures done through the admin console in the same way.

Always start with "Navigate to the *${admin-console}*." as the first step.
Use a numbered list.
Put only one action per step.
End each step with a period, even if not a complete sentence.
Prefer "Select" over "Click," or "Click on".
Use the exact wording for text links, buttons, or icons.
- For unnamed icons, use the tool tip description.

Command Console Procedures

Intrigue Procedures

Writing Explanations

Formatting Tables & Diagrams

Introduce the table or diagram to explain the information described in the table. Links should be to the section containing the table, or to an anchor added to the introduction, instead of directly to the block.

Give the table or diagram a specific, descriptive title/caption.
- Asciidoctor syntax for a caption is a leading . with no space: .Caption Text .
Use Asciidoctor-diagram Ditaa syntax formatted tables when possible.
- Avoid using ${branding} substitutions, as they may not resolve correctly within the diagram in custom distributions.
- Default colors are cDEF, c369, and cCCC.
  - Accent colors to use sparingly: c5F5, cF55, c555

Tables

Tables can be formatted in a few ways, but to maintain consistency, these conventions should be followed.

Start with a title, if applicable.

.Dot Title

Within square brackets, define the number of columns, and the relative width of each column. Add a header, if appropriate. (while it is possible to define a number of equally-columns with [cols="3"], in practice, this syntax often has problems with dropping table rows

[cols="1,3,1" options="header"]

On the next line, add the table delimiter.

|===

Keep each cell on a separate line with a blank line between rows, and close with another table delimiter.

 |cell 1
 |cell 2
 |cell 3

 |cell 4
 |cell 5
 |cell 6

|===

If Asciidoctor syntax is needed within a table cell, prepend an a character before the | that starts the cell.
See Asciidoctor documentation for advanced topics, such as spanning columns or row.

.Table title
[cols="1,3,1" options="header"]
|===
|Header 1
|Header 2
|Header 3

|cell 1
|cell 2
a|cell 3
* list item 1
* list item 2

|===

Table delimiters can be dangerous, if one is deleted or a stray is left in the documentation, it will essentially try to put all content that follows into a single table cell, which loses all formatting and often will cause a build to fail on pdf generation.

Not all formatting is available within table cells. Bulleted lists and callouts do not get converted when inside a table cell, but can be approximated with line breaks.

Diagrams

[ditaa,diagram-file-name,png]
....
+--------+
|Object 1|
|cDEF    |
+--------+
....

Formatting Code Blocks

Short blocks of code, system attributes and properties, and file names/extensions/directories should be surrounded by backticks to render as monospace. Longer code samples should be set off in code blocks as follows. Adding an anchor is optional, but encouraged. Anchors should be unique to not conflict with anchors in other sections.

Make a code block for anything longer than a single line. Short snippets of less than one line can be formatted monospace inline.

Introduce the code block and the context for it. Links should be to the section containing the code block, or to an anchor added to the introduction, instead of directly to the block.

Provide a descriptive caption
- Asciidoctor syntax for a caption is a leading . with no space: .Caption Text .
Specify the language, if possible, to enable syntax highlighting. See list of supported languages: CodeRay.
- Example: [source, java]
If more than five lines, add line numbers with linenums
- [source, javascript, linenums]
- Exception: don't use line numbers for blocks of console input / output.

.[[anchor]]Caption or Description Line
[source,language,linenums]
----
// code ....
----