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.
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:
We use tables to call out longer, complex, selections of data where clarity between the elements is required. For example:
|Argument||1.99||Needs to be defined!|
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
Class names, for example when referring to underlying parts of the Humio code, are style like
Parameters within configurations are styled
User input, for example a command within output is style like
this, while replaceable items, for example when referring to a filename are style like
this, you can see an example:logscale
Filenames, directories and paths are marked up using
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
Variables, within Humio and the environment, are styled
Arguments to functions:
Buttons within the UI:
Menus in the output have thestyle, while an individual is identified separately.
Variable names, for example when configuring Humio will use the
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.
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.
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.
For graphics and illustrations we use images and screenshots, or for diagrams we use an automated format called Mermaid:
Figure 2. Figure