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:

  1. Step 1

  2. Step 2

    1. Substep a

    2. Substep b

    3. Substep c

  3. 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 style

  • Class 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 like this, you can see an example:

    logscale
    shell> 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: Click Here

    Menus in the output have the Menu style, while an individual Item 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.

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:

graph LR; Data{"Data"} --> Parse Parse --> Digest Digest --> Store style Digest fill:#2ac76d;

Figure 2. Figure