Alerts (Note, Tip, Important, Caution, Warning)

Alerts is a HDocBook Markdown extension that will create block quotes that render on Hornbill H-DOC with colors and icons that indicate call-out information within the document.

Avoid notes, tips, and “important” boxes. Readers tend to skip over them. It’s better to put that information directly into the article text.

If you need to use alerts, limit them to one or two per article. Multiple notes should never be next to each other in an article.

The following alert types are supported:

::: note
Information the user should notice even when skimming.
:::

::: tip
Optional information to help a user be more successful.
:::

::: important 
Essential information required for user success.
:::

::: caution
Negative potential consequences of an action, be careful.
:::

::: warning
Dangerous consequences of an action.
:::

These alerts look like this on Hornbill Docs:

Angle Brackets

If you need to use angle brackets <> in your text, you need to encode these using standard HTML entity encoding.

The following:

<between>

will render as: <between>

Blockquotes

Blockquotes are created using the > character:

> This is a blockquote. It is usually rendered indented and with a different background color.

The preceding example renders as follows:

This is a blockquote. It is usually rendered indented and with a different background color.

Bold and Italic text

To format text as bold, enclose it in two asterisks:

This text is **bold**.

To format text as italic, enclose it in single asterisks:

This text is *italic*.

To format text as both bold and italic, enclose it in three asterisks:

This text is both ***bold and italic***.

Code Tags

Hornbill Docs supports in-article code highlighing, using the popular highlight.js library.

To add blocks of code to your articles, you need to wrap your code with three backticks, and set an (optional) language to apply highlighted code, as so:

md
```js
// Your JavaScript code could go here
console.log('Hello, world');
```

Which would render as:

// Your JavaScript code could go here
console.log('Hello, world');

Headings

Hornbill Docs supports six levels of headings, specified by one through six hash # characters, followed by a space, and then the heading text:

# Heading 1 (H1)
## Heading 2 (H2)
### Heading 3 (H3)
#### Heading 4 (H4)
##### Heading 5 (H5)
###### Heading 6 (H6)

The above Markdown will render like this.

Heading 1 (H1)

Heading 2 (H2)

HTML

Markdown supports inline HTML. As a general rule, HTML is not recommended for publishing to Hornbill Docs, but it may be useful in a limited number of situations. Basically, you should avoid using inline HTML to the greatest extent possible.

When using inline HTML in your Markdown book content, you will need to be aware of, and cater for, the conditions for embedding Markdown syntax within HTML tags. These are documented in the HTML Blocks section of the CommonMark Specification.

Images

The following image types are supported.

• .jpg
• .png
• .svg

For illustrations, flow diagrams and info graphics, we recommend you have your graphic designer use SVG format, and follow the Hornbill Graphics and Illustration Style Guide in order to ensure that images scale properly for screen, print and PDF, and in the case of screen rendering look high-quality in both light and dark screen rendering modes.

The basic Markdown syntax you should use to embed an image in your content is:

![Alt Text](/path/to/image.jpg)

Links

For information on using links, see Using Links In Documentation.

Lists - Numbered and Bulleted

1. The first item
1. The second item in the parent list
   1. and this is the first child item
   2. in a nested numbered list
1. The third item, and so on...

* The first item
* The second item in the parent list
   * and this is the first child item
   * in a nested numbered list
* The third item, and so on...

Superscript / Subscript

Subscript and superscript are “inline” styles used normally for technical documentation. As a best practice, use these styles only in a context that requires subscript/superscript for technical accuracy (e.g. for formulas) and NOT for creating smaller text items, such as notes under images and so on.

To get superscript or subscript we are using the in-line HTML feature of the markdown processor:

Get <sub>subscript</sub> like this

Which will render:

Get _subscript like this

And get <sup>superscript</sup> like this.

Which will render:

And get ^superscript like this.

Tables

Markdown provides a simple way to create a table using the | pipe and - hyphen symbols. An example of a simple table is shown below.

|Column Header 1 |Col 2   | Col Three|
|---------------|--------|----------|
|any information|in your |table |
|and you don't need to |worry too much about |alignment|

And this is what the above renders to:

To align the table content horizontally you can use colons in the header separating lines either size of the hyphens like this:

| Left Aligned         |    Center Aligned    |   Right Aligned |
| :------------------- | :------------------: | ---------------:|
| Left Here            |      Center Here     |      Right Here |
| 1.00                 | 4.57                 | 88            |
| one                  | two                  | three             |

The above renders the following table:

|              |column 1 |Column 2|
|--------------|---------|--------|
|**Row 1 Name**|Data 1a  |Data 2a |
|**Row 2 Name**|Cell 1b  |Data 2b |