Write for Us

As High Fidelity has features that are constantly changing and growing as the product evolves, we need to ensure that our documentation reflects the latest information. We would love to have you contribute to our documentation and help us keep it up-to-date!

Our docs run on a flat-file CMS called Grav. All of the pages are written in markdown and automatically compiled into HTML and cached for performance.

On This Page

Edit an Existing File

The API documentation is generated using automated processes. At this time, these pages cannot be edited.

  1. Go to our GitHub repository and locate the markdown file you want to edit. For more information about editing files in Markdown, see our Markdown Guide.
  2. You'll need a GitHub account to make edits. Once you're done making changes, create a pull request (PR) with your changes.
  3. We will review your changes and approve them, or send them back for changes.

Create a New Page

Since we're using Grav and its documentation theme, we need to ensure that every page follows the page type requirements specified by Grav. This is particularly important when you are creating a new page for our documentation.

Here are the specifications for new pages in our documentation system:

  1. Each page has its own folder. The folder name starts with the a number that indicates its hierarchy in the parent folder. The folder name should be in small letters with no spaces and only hyphens between words. The image below shows you an example folder structure, along with the Table of Contents output that you would see.

    Because each of the folders represent a page, there should always be only one markdown file in each folder. When you create and save your markdown file, make sure you name it docs.md.

  2. All markdown files start with a YAML statement before the content. These statements help the CMS ensure that your page has the right formatting and is discoverable in the docs. Your YAML statements should look like this:
---
title: %Your Page Name/Title %
    taxonomy: 
    category: docs
---
  1. Any images or gifs you want to include in your page should be saved in the same folder as your page's markdown file.
  2. Use the YouTube plugin code to add an embedded version of the video. Your code should look like this:
    [plugin:youtube](https://www.youtube.com/your-url)

Markdown Guide

All of High Fidelity's documentation is written in Markdown. High Fidelity also uses Markdown to format item descriptions when you submit something to the Marketplace. Markdown is a lightweight markup language with plain text formatting syntax. Its design allows it to be converted to many output formats, including HTML.

When modifying our documentation, using Markdown doesn't mean that you can't also use HTML. You can add HTML tags to any Markdown file. This is helpful if you prefer certain HTML tags to Markdown syntax, or if you need to use complex formatting that is not supported by Markdown.

Headings

Markdown Syntax HTML Output
# h1 Heading <h1>h1 Heading</h1>

h1 Heading

## h2 Heading <h2>h2 Heading</h2>

h2 Heading

### h3 Heading <h3>h3 Heading</h3>

h3 Heading

#### h4 Heading <h4>h4 Heading</h4>

h4 Heading

##### h5 Heading <h5>h5 Heading</h5>
h5 Heading
###### h6 Heading <h6>h6 Heading</h6>
h6 Heading

Emphasis

If there is more than one markdown syntax listed, feel free to use any of them. The output will be the same.

Markdown Syntax HTML Output
italicized text
_italicized text_
<em>italicized text</em> italicized text
**bold text**
__bold text__
<strong>bold text</strong> bold text
***bold AND italicized text***
___bold AND italicized text___
<strong><em>bold text</em></strong> bold AND italicized text
​~​~​strikethrough~~ <del>strikethrough</del> strikethrough

Line Breaks

To create paragraphs, use a blank line to separate one or more lines of text. You should not indent paragraphs with spaces or tabs.

To create a line break, end a line with two or more spaces, and then hit return.

Markdown Syntax HTML Output
I really like using Markdown.

I think I'll use it to format all of my documents from now on.

<p>I really like using Markdown.</p>

<p>I think I'll use it to format all of my documents from now on.</p>

I really like using Markdown.

I think I'll use it to format all of my documents from now on.

This is the first line.
And this is the second line.
<p>This is the first line.<br>And this is the second line.</p> This is the first line.
And this is the second line.

Blockquotes

To create a blockquote, add a > in front of a paragraph.

> This is a blockquote

The rendered output looks like this:

This is a blockquote.

Blockquotes can contain multiple paragraphs. Add a > on the blank lines between the paragraphs.

> This is a blockquote. 
>
> It has a second paragraph.

The rendered output looks like this:

This is a blockquote.

It has a second paragraph.

You can also nest blockquotes:

> This is a blockquote. 
>> The second paragraph is nested.

The rendered output looks like this:

This is a blockquote.

The second paragraph is nested.

Notices

We have four different notices that are used in our documentation. Please note that notices are not supported for Marketplace item descriptions.

>>> Yellow messages are informational and preceded by three > symbols.

>>>> Red messages warns the user about something and are preceded by four > symbols.

>>>>> Blue messages are notes that give more information to the user and need to stand out. They are preceded by five > symbols.

>>>>>> Green messages are tips that help the user do something. They are preceded by six > symbols.

Lists

To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.

To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or more items to create a nested list.

Markdown Syntax HTML Output
1. First item
2. Second item
3. Third item
4. Fourth item
<ol>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
<li>Fourth item</li>
</ol>
1. First item
2. Second item
3. Third item
4. Fourth item
1. First item
2. Second item
3. Third item
     1. Indented item
     2. Indented item
4. Fourth item
<ol>
<li>First item</li>
<li>Second item</li>
<li>Third item
<ol>
<li>Indented item</li>
<li>Indented item</li>
</ol>
</li>
<li>Fourth item</li>
</ol>
1. First item
2. Second item
3. Third item
     1. Indented item
     2. Indented item
4. Fourth item
* First item
* Second item
* Third item
* Fourth item
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
<li>Fourth item</li>
</ul>
  • First item
  • Second item
  • Third item
  • Fourth item
+ First item
+ Second item
+ Third item
     + Indented item
     + Indented item
+ Fourth item
<ol>
<li>First item</li>
<li>Second item</li>
<li>Third item
<ol>
<li>Indented item</li>
<li>Indented item</li>
</ol>
</li>
<li>Fourth item</li>
</ol>
  • First item
  • Second item
  • Third item
    • Indented item
    • Indented item
  • Fourth item

Tables

Tables are created by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned. Please note that tables are not available in Marketplace item descriptions.

Markdown Syntax:

| Column A | Column B | Column C |
|----------|----------|----------|
| 1        | A        | !        |
| 2        | B        | @        |

HTML Syntax:

<table>
  <tr>
    <th>Column A</th>
    <th>Column B</th>
    <th>Column C</th>
  </tr>
  <tr>
    <td>1</td>
    <td>A</td>
    <td>!</td>
  </tr>
  <tr>
    <td>2</td>
    <td>B</td>
    <td>@</td>
  </tr>
</table>

Rendered output:

Column A Column B Column C
1 A !
2 B @

Images

Markdown Syntax HTML Output
![alt text](image.png) <img src="image.png" alt="alt text" />

Links

Markdown Syntax HTML Output
<https://www.highfidelity.com> <a href="https://www.highfidelity.com">
     https://www.highfidelity.com
</a>
https://www.highfidelity.com
[High Fidelity](https://www.highfidelity.com) <a href="https://www.highfidelity.com">High Fidelity</a> High Fidelity
<support@highfidelity.io> <a href="mailto:support@highfidelity.io">
     support@highfidelity.io
</a>
support@highfidelity.io

Code Samples

Markdown Syntax HTML Output
`inline code` <code>inline code</code> Here is some inline code.
```
block
of
code
```
<pre>block
of
code</pre>

Horizontal Rules

If there is more than one markdown syntax listed, feel free to use any of them. The output will be the same.

Markdown Syntax HTML Output
___
---
***
<hr />

See Also