Skip to content

Markdown Formats and Templates

Jump to bottom
Lori Krell edited this page Feb 14, 2022 · 6 revisions

Learn more about Markdown with this guide! We use GitHub flavored Markdown with some additional options. Here are more guides and options:

Filename

A Markdown file has a filename and extension of .md. We recommend keeping the filename short. It does not affect the canonical link.

Elements of a Page

We provide templates (coming soon) to help create a new page. Every page includes the following:

  • Frontmatter - This is the metadata for a webpage, including the title, description, and search keywords.
  • Headings - These mark the sections, from H2 (##) to H5 (#####). Use H1 only once at the top for the title.
  • Content - All of the content, including paragraphs, lists, instructions, images, graphs, and more.

Frontmatter

Every file begins with front matter or metadata for your content. This information includes:

---
id: page-id
sidebar_title: Navigation title
description: Learn more about... 
---

# Title of the Page
Parameter Description
id: Id for the page used in the sidebar and as the canonical link.
sidebar_title: Optional, use a different title for the side navigation. It does not affect the canonical link or page title.
description: 1 sentence describing what the user will find in the page for searches. Otherwise the first couple sentences are used for searches.

Paragraphs

As you start writing content, it automatically generates along the left side (or margin). To create a paragraph, leave an empty line between sentences.

If you need to indent content, use the tab key or enter 2 spaces. Each tab moves content to the right, indenting the page content.

Text effects

To format for bolding and italics, see the following:

Example Output
*emphasis* emphasis
**bold** bold

Bulleted lists

We recommend using a dash (-) for each line in a bulleted list. Lists also support *.

* List Item 1
* List Item 2

  * Indented List Item
  * Another one

  • List Item 1

  • List Item 2

    • Indented List Item
    • Another one

Numbered steps

Numbered lists add numbers to a set of instructions or steps. Start every line with 1. When building the documentation, the instructions automatically number for you. This is helpful when you need to add or change the order of instructions. You do not need to edit every number.

1. Access Sumo Logic and select your account then **Preferences**.
1. Under Access Keys, click **Create**.
1. Enter...
  1. Access Sumo Logic and select your account then Preferences.
  2. Under Access Keys, click Create.
  3. Enter...

Tables

Simple tables can help format content. For example, lists of attributes with descriptions. Adding the style below the table helps with formatting.

Colons can be used to align columns.

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

There must be at least 3 dashes separating each header cell.
The outer pipes (|) are optional, and you don't need to make the 
raw Markdown line up prettily. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

Colons can be used to align columns.

Tables Are Cool
col 3 is right-aligned $1600
col 2 is centered $12
zebra stripes are neat $1

There must be at least 3 dashes separating each header cell. The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.

Markdown Less Pretty
Still renders nicely
1 2 3

Links

Adding links to content outside of documentation: [GitHub](http://github.com)

Adding links between pages are relative links with the path and name of the file without the .md or .mdx extension:

[Topic Name](/path/filename.md)

Images

We recommend saving all images in PNG format. Images are typically saved in the /static/images folder location. Always include alt text for images.

Use the following format for placing images inline (paragraphs, tables, bullets, etc) and in its own line:

![Alt Text](/images/filename.png)

Notes and Callouts

Notes and callouts are annotations. Use annotations to highlight information, including tips, notes, warnings, etc.

:::note Title for the Note
Add markdown here. This supports note, tip, info, warning, important, and some custom looks like contribution and training!

Make sure to have a blank line above and below the whole section. You can also use code, code blocks, tables, and much more in these callouts.
:::

A visual example will be provided in a template.

Code

Use the following formats for commands, API method names, and code.

Inline code examples use single ticks around `text` for code formatting.

Here is an example of code inline.

For blocks of code, use triple ticks (```) before and after the code. If you know the code language, include that in the first set of ticks, for example ```json. This applies code highlighting for the language. See this list of available languages.

The following is an example of JSON:

{  
    "employee": {  
        "name": "Jane Smith",   
        "team": "Operations",   
        "manager": true  
    }  
}

Templates

To quickly create a page, use a template. You can copy and paste the file, add your content, and submit a PR. If you need formats for specific code, see the formats template.

(coming soon)

  • Doc topic - Use for any documentation page
  • APIs - Use for API and code
  • Format template

Sumo Logic 2021

Clone this wiki locally