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 we use a code markup, while for search fragments or simple text we use a literal markup style

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

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

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

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:

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

Figure 2. Figure