Understanding Library Markup
Headings are used within a single page to highlight different sections and structures. This helps with navigation and the Table of Contents for a single page is always reflect in the sidebar on the right of each page.
Pages which require more than four levels of headers are split into separate pages.
Heading 1
Heading 2
Heading 3
Heading 4
Lists and Steps
We use bullet lists where we want to provide a list of information or options:
List item A
Sub list item 1
Sub list item 2
List item B
List item C
We use numbered lists when there is a list of steps or a sequence to follow:
Step 1
Step 2
Substep a
Substep b
Substep c
Step 3
Tables
We use tables to call out longer, complex, selections of data where clarity between the elements is required. For example:
Treat | Quantity | Description |
---|---|---|
Function | 2.99 | Does something |
Variable | 1.49 | Placeholder value |
Argument | 1.99 | Needs to be defined! |
Inline markup
To help the readability of the text, we use a variety of inline markup styles to help distinguish between different semantic elements of the text:
For simple term references within text, for example to call out an element or term we use simple highlighting
For code markup, when referencing a code fragment, or search fragment we use a
code markup
styleClass names, for example when referring to underlying parts of the Humio code, are style like
Classname
Parameters within configurations are styled
parameter
.User input, for example a command within output is style like
this
, while replaceable items, for example when referring to a filename are style likethis
, you can see an example:logscaleshell>
tar zxf
zookeeper.tar.gz
Filenames, directories and paths are marked up using
/path/to/filename
For keyboard combinations A or Ctrl+A
References to UI components, including This is guilabel
Function names and class names within the product are styled
function()
Variables, within Humio and the environment, are styled
VARIABLE_NAME
Arguments to functions:
argument
Buttons within the UI:
Menus in the output have the
style, while an individual is identified separately.Variable names, for example when configuring Humio will use the
Variable_name
style.Commands used in the shell, for example java or humioctl
We sometimes call out Terms or Functionality Names
Errors are called with a specific Error Message and we'll call out the message explicitly within the documentation. A corresponding Errorname and errortype may also be used.
Links
Links to other areas of the documentation are marked up as link: Understanding Library Markup.
External links outside of the Library, for example Humio will have a an external link icon.
Notices
We have different explicit call outs to highlight important information:
Note. Basic notes are used to highlight information that is an aside to current topic.
Warning. Warnings are used to highlight issues which may be dangerous or damaging.
Important. Important notes should be read before continuing.
Hint. For hints on how best to use Humio.
Tip. For quick tips on how best to use Humio.
Danger. Dangerous steps, that may involve potential data loss.
Error. Errors and error messages.
Version Markup
Within the core documentation, we will explicitly call out changes in versions within a page using the following formats:
Available: Functionality v1.28
This block is used to show when a new feature or functionality was added in a particular version. We'll highlight what has changed between this and the last version.
Deprecated: Functionality v60.47
Where functionality or features has been deprecated, with a view to removal in a future version, we will call it out here.
Removed: Functionality v99.99
When specific functionality has been removed, a note in this format with a version number will be used.
Product Specific: Area
Product specific changes or availability will be highlighted in this type of block.
Graphics
For graphics and illustrations we use images and screenshots, or for diagrams we use an automated format called Mermaid:
Figure 2. Figure