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 we use a
code markup
, while for search fragments or simple text we use aliteral markup
styleClass names, for example when referring to underlying parts of the LogScale 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:shellshell>
tar zxf
zookeeper.tar.gz
Filenames, directories and paths are marked up using
/path/to/filename
For keyboard combinations A or Ctrl+A
URLs use
http://library.humio.com
References to UI components, use Search Box
Function names and class names within the product are styled
function()
Variables, within LogScale and the environment, are styled
VARIABLE_NAME
Arguments to functions:
argument
Links to the pages within the UI:
Repository Settings
Buttons within the UI:
Menus in the output have the
style, while an individual is identified separately.Variable names, for example when configuring LogScale will use the
HUMIO_LOGS
style.Commands used in the shell, for example java or humioctl
Packages use the PackageName style.
Integrations use Integration format.
Field names within repositories use the fieldname
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.
For GraphQL references we use:
Queries
Mutations
Arguments
Fields
Links
Links to other areas of the documentation are marked up as link: Understanding Library Markup.
External links outside of the Library, for example LogScale 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
Hint
For hints on how best to use LogScale.
Tip
Tip
For quick tips on how best to use LogScale.
Danger
Danger
Dangerous steps, that may involve potential data loss.
Error
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