INDEX
Documentation Library
Search for information on Hornbill Documentation.
{{docApp.searchResultFilteredItems.length}} results for "{{docApp.currentResultsSearchText}}" in {{docApp.searchFilterBySpecificBookTitle}}
-
{{resultItem.title}}
{{resultItem.url}}
Have questions about this site?
What is this site?
- This website is Hornbill's new product documentation website and is currently under development.
- It is intended that all existing and future public-facing documentation we produce will be available to search, browse and share.
- Hornbill's current documentation is available at Hornbill Wiki but over time this content will be migrated to this documentation site.
- Please feel free to have a look around at any time.
Why has Hornbill created this site?
- Hornbill's products have moved on considerably since we introduced it almost 10 years ago. At the time, the MediaWiki tool was sufficient, but we have outgrown it.
- Our customers are more enterprise focused and more self-sufficient than ever before, so for 2023 and beyond we have established a new documentation platform and team to drive our documentation initiative forwards.
- We are aiming to deprecate the use of Hornbill Wiki for most Hornbill related documentation.
- We want to enable our growing partner network with product resources and information, documentation beyond our Wiki approach is required.
- We could definitely do with some help, and may even pay for some! If you have domain knowledge and would like to help, please check out our Hornbill Docs Contributor Guide and contact the Hornbill docs team at docs@hornbill.com.
What will this site be good for?
- Community contribution will be facilitated, encouraged, and most welcome.
- High quality documentation, will be kept up to date as rapidly as our products evolve.
- Real-time content search and discovery.
- Articles organized into books, books into libraries, creating a more natural and logical structure to our documentation.
- Legacy API documentation and various other documentation sources will all be consolidated into a single unified documentation system.
- Documentation available in browser as well as printable/viewable as PDF on demand.
- Personalized documentation experience, allowing dark/light mode, article subscriptions, social media sharing and other useful features.
- Almost all publicly available documentation on docs.hornbill.com will be open-source and available to fork on GitHub, allowing customers to derive their own custom documentation around Hornbill products should they wish to.
What is the timeline for this site?
- We have taken the decision to publish and make available early, there is very little content at this time.
- As and when we have completed/usable documentation, it will be published here.
- We have a host of additional features we wish to add over time, so please watch this space.
- We expect most of our existing documentation should be reviewed/migrated to docs.hornbill.com over the coming months.
- The documentation project will be ongoing, will continue to expand, evolve and improve day-by-day.
{{docApp.libraryHomeViewProduct.title || docApp.libraryHomeViewProduct.id}}
{{docApp.libraryHomeViewProduct.description}}
{{group.title || group.id}}
{{group.description}}
Every system that uses Markdown is generally built on a basic Markdown syntax, frequently based on the strongly typed and documented CommonMark specification. However, individual Markdown systems generally need to expand the syntax to include extra functions or rendering capabilities that are specific to the needs of the system.
Accordingly, the HDocBook Markdown syntax is also based on CommonMark but extends that with additional capabilities that allow rich documentation content features and visualizations to be created. This article is the reference for both basic and extended syntax for the HDocBook Markdown grammar and feature set.
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:
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.
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');
Supported Languages
The following highlight.js supported languages are also supported in hdoc-tools:
apache
bash
cpp
cs
css
markdown
dart
diff
dns
dockerfile
dos
foxpro
fsharp
go
http
ini
java
javascript
json
kotlin
less
makefile
xml
nginx
perl
pgsql
php
powershell
python
rust
sql
swift
typescript
vbnet
ruby
yaml
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)
Heading 3 (H3)
Heading 4 (H4)
Heading 5 (H5)
Heading 6 (H6)
Note
- There must be at least one space between the
#
and heading text. - Only a single H1 heading should exist in any Markdown file, and should be the first content item in the document.
- For templates that include the right-hand table of contents, H2 and H3 headings will automatically appear inside it.
- You can put links to individual headings in a Markdown file using anchor links, as so:
[create an anchor](#anchors-in-markdown)
.
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.
Important
Hornbill Docs does not support runtime-compiled stylesheets, and therefore the use of <style />
HTML tags in book markdown or static HTML documents is unsupported.
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
Numbered List
To create a numbered list, you can use any numbers, but for consistency it’s best to just use all 1’s and the rendering process will take care of sequencing the numbers correctly for you. The numbers are rendered in ascending order sequentially. For increased readability in markdown, you can increment your list numbers manually.
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...
This renders as follows:
- 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…
Bulleted List
You can create a bulleted list using either -
or *
followed by a space at the start of each item. Choose one, then stick to that throughout the entire article:
* 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...
This renders to a bulleted list follows:
- This is
- a parent bulleted list
- and this is
- a nested bulleted list
- All done!
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:
Column Header1 | Col 2 | Col Three |
---|---|---|
any information | in your | table |
and you don’t need to | worry too much about | alignment |
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:
Left Aligned | Center Aligned | Right Aligned |
---|---|---|
Left Here | Center Here | Right Here |
1.00 | 4.57 | 88 |
one | two | three |
Tip
If you want a more interactive way to create a table you can use any one of a number of online markdown table generators, for example:
Data matrix tables
You can create a data matrix table like this:
| |column 1 |Column 2|
|--------------|---------|--------|
|**Row 1 Name**|Data 1a |Data 2a |
|**Row 2 Name**|Cell 1b |Data 2b |
The example renders as:
column 1 | Column 2 | |
---|---|---|
Row 1 Name | Data 1a | Data 2a |
Row 2 Name | Cell 1b | Data 2b |
This is really the same as any other table, except every entry in the first column is styled bold (**bold**
) using normal bold syntax.
- Version {{docApp.book.version}}
- Node {{docApp.node}} / {{docApp.build}}