id	title	sidebar_label	description
style-guide	Sumo Docs Style Guide	Style Guide	A guide to styling and formatting Sumo Logic Docs.

import useBaseUrl from '@docusaurus/useBaseUrl';

This page describes how to author Sumo Docs, which are written in GitHub-flavored markdown.

The Sumo Logic Style Guide is a guide to language at Sumo Logic, so that we can speak as one company with a unified voice, and know what we mean when we talk about our product. The Style Guide began as a document used by the Documentation team to make decisions about tone, voice, and word usage. We thought it would be useful to share with everyone in our community.

This is a living document. If you're looking for a style rule or UI component usage that's not defined here, let us know. The Documentation team will look it up and add usage guidance.

Writing Resources

If you need help with a convention, word to use, or format to follow, we will keep a cheatsheet of styles here. We also follow:

Merriam-Webster Dictionary
The Chicago Manual of Style
Microsoft Manual of Style
- User Input | Formatting Text in Instructions

For terminology usage guidance, see our Word List.

If you're new to writing tech content or would like to learn more, check out these resources:

Write the Docs. Association of tech writers, developers, trainers, and more that have collected ideas, created training and guidelines, and actively discuss documentation.
Google Technical Writing Courses. Self-paced courses to refine your writing. The courses may use a style different from ours, but still an excellent to get started.
Every Page is Page One. A helpful method for considering what goes into a page is to think of every page as page one. With the extreme use of search engines or sharing a link to find content, users may land in the middle of a section or tutorial. These ideas help hone your content and focus on user needs.

Helpful blogs on tech writing:

Usability and Tech Writing. Jakob Neilson defined usability, including insights on technical writing and learning, helpful for writing docs
Feathers tech writing. Pioneered API and technical tech writing, insights and instructions
I'd rather be writing. Guides and thoughts on tech writing process and content

The Sumo Logic Docs team will review submissions, provide suggested edits, add new content into the navigation, and answer any questions you have.

:::tip To create a new doc quickly, use a template. You can copy and paste the file, add your content, and submit a PR.

Doc topic (generic) template
Partner app template :::

Voice and Tone

We are clear, genuine, and trustworthy. We understand that our customers entrust us with their vital data and never make light about our commitment to data access and security.
The reader should feel confident and informed. We should strive to engage our customers, and show them where to get additional assistance when needed.
Describe Sumo Logic in a professional and truthful manner. Avoid generic, unsubstantial adjectives like "very" or phrases like "we're the best". Instead, illustrate these points by letting our product speak for itself.
Avoid using a stiff, institutional voice. Instead, write with an instructive and conversational tone. For example, when linking to the support site, use terms like "Need help? Let us know" instead of "Please email our support personnel" to give our company a friendly face.
Instructional content and blog posts should be written at approximately the 8th-grade reading level, particularly in introductory sections, for readability and SEO. You can test your content here.
When explaining a process or procedure, clarity is critical. Edit words that distract or confuse. Put yourself into the reader's shoes and think about what actions you are recommended to them when an error message is displayed, rather than merely stating what went wrong. Example: "Could not create the user." vs "This email is already registered in the system. Please use a different email or contact Sumo Logic for assistance."
We have a sense of humor! Conveying that we do serious work, but we don't take ourselves too seriously, makes Sumo Logic feel likable.

Active Voice

When writing instructions, use the active voice whenever possible. For example, "Sumo Logic ingests multiple streams of data", not "Multiple streams of data are ingested by Sumo Logic".

This gives a call to action for the reader or user to effectively get something done. It also reduces word count and keeps instructions clear.

Active ✅	Not Active ❌	Why?
Add a resource...	You can add a resource...	They know they can do a thing. Clearly state to do the thing.
Build the query using the following...	Please build the query using the following...	We need them to complete a task. No need for please.
To add a new collector: 1. Access Sumo Logic and find the...	1. When you need to add a new collector, access Sumo Logic and find the...	Introduce your instructions with the goal, then dive into the instructions. This is called a stem, and it helps focus the task and keeps you active.

Inclusive language

By writing inclusively and using culturally neutral language, our words resonate with global audiences and make everyone feel welcome, no matter their race, gender, socioeconomic status, and ability.

Do not use idioms, slang, expressions, or terminology only understood by a specific region or group.
Avoid overly technical jargon.
Address the reader as "you", as you would in conversation. For example, instead of saying, "The user must provide his or her API key" or "One must provide their API key", say, "You'll need to provide your API key".
Unless you're referring to a specific person, do not use gender pronouns (he/she).

✅ "allowlist"
✅ "denylist"
✅ "placeholder data"
✅ "primary" or "main"
✅ "press" or "click"

❌ "whitelist"
❌ "blacklist"
❌ "dummy data"
❌ "master"
❌ "hit"

Doc structure summary

Frontmatter (metadata) goes at the top
Tell the user in the doc introduction (first paragraph) what the page teaches, why they should read it, and who should read it.
Let the user know what step/place they are in for a tutorial in the introduction/at top. The layout automatically provides a previous/next at the bottom of the page.
Link out to important concepts and overviews for additional reading. This is helpful for instruction pages or tutorials.
Keep instructions concise, easy to follow, not too many screenshots.
Include any notes, warnings, tips, or other admonitions.

Abbreviations

Avoid the use of abbreviations like “e.g.”, “i.e.”, and “etc.”. Although they may be well understood, such abbreviations don’t support our goal of a conversational tone. In other words, don’t use language you wouldn’t use verbally.

Instead of "e.g.", use “for example”
Instead of "i.e.", use “that is”

Acronyms

An acronym uses the first initials of a word or phrase, for brevity. Our industry is full of them, and they can get confusing if their usage isn't clear. Acronyms should be capitalized, if not used directly in a query, etc. Unless the usage is clear from the context, for the first usage, spell out the phrase, then present the acronym in parenthesis. For example: Secure Shell (SSH).

All companies have numerous acronyms for product, features, solutions, and more. Our documentation includes acronyms for Sumo Logic and third party software. Always fully spell out the first instance of the acronym on the page, then you can use it throughout. Do not spell out in a heading, but in paragraphs or bullets.

For example, the first time you use AWS Application Load Balancer (ALB), you introduce or use it like that the first time on the page. Through the rest of the page, you can use ALB.

Admonitions

We refer to callout elements like Tip, Note, Warning, and Caution as admonitions.

Docusaurus has a special syntax to create admonitions and callouts, including note, tip, important, caution, warning, and sumo. You can use markdown content in the admonitions, code blocks, links, bullets, images, videos, and much more.

:::note
This is a note.
:::

:::tip
This is a tip about a cool feature option.
:::

:::important
This is some vital information.
:::

:::danger
This action is dangerous and could result in data loss.
:::

:::caution
This could note important and problematic information.
:::

:::sumo Best Practice
Highlight specific info, best practices, links, [training links](https://www.sumologic.com/learn/training/), and other information from Sumo specialists. You can change the title based on the content.
:::

:::note This is a note. :::

:::tip This is a tip about a cool feature option. :::

:::important This is some vital information. :::

:::danger This action is dangerous and could result in data loss. :::

:::caution This could note important and problematic information. :::

:::sumo Best Practice Highlight specific info, best practices, links, training links, and other information from Sumo specialists. You can change the title based on the content. :::

You can use code blocks in admonitions. Here's an example:

:::tip Here's a cool tip.

"overrides": [
    {
    "series": [],
    "queries": [
        "A"
        ],
    "userProvidedChartType": false,
    "properties": {
        "type": "column"
        },
    "unsafeCanvasJSProperties": {
        "bevelEnabled": true,
        "indexLabelPlacement": "inside",
        "indexLabel": "{y}",
        "indexLabelOrientation": "vertical"
        }
    }
]

:::

Beta Releases

Closed Beta

For a Closed Beta release:

Underneath the frontmatter, add the Robots meta tag (to prevent search crawlers from picking it up) and the Beta badge.

---
id: xyz-source
title: XYZ Source (Beta)
description: The XYZ Source provides a secure endpoint to receive event data.
---

<head>
  <meta name="robots" content="noindex" />
</head>

<p><a href="/docs/beta"><span className="beta">Beta</span></a></p>

First paragraph goes here...

Do not add the doc to sidebars.ts.
Publish the doc.

When the feature moves from Beta to GA, remove the Robots meta tag, remove the Beta label, and add the doc to sidebars.ts.

Open Beta

For an Open Beta release:

Underneath the frontmatter, add the Beta label.

---
id: xyz-source
title: XYZ Source (Beta)
description: The XYZ Source provides a secure endpoint to receive event data.
---

<p><a href="/docs/beta"><span className="beta">Beta</span></a></p>

First paragraph goes here...

Add the doc in sidebars.ts.
Publish the doc.

When the feature moves from Beta to GA, remove the Beta label.

Capitalization

Title case (initial cap) all doc titles. Example: Global Intelligence for Apache Tomcat App
Sentence case all other headers (H2, H3, H4). The only exception is proper nouns, which are always title case. Example: Throughput signals and contributing factors

Code (Inline)

Use single backticks (` `) to format inline code, such as commands, API method names, and code. For information on code blocks (scripts), see Code Blocks.

Example: `_view = sumologic_slo_output`

Example: _view = sumologic_slo_output

Code Blocks

Use code blocks to format scripts, such as the JSON example below. This is important for scripts and CLI. Format blocks of code by placing triple backticks before and after the code.

If you know the code language, include that in the first set of backticks to activate syntax highlighting. See this list of supported languages. Use sql to format Sumo queries and json for Sumo logs.

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

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

Here's how to add a title to your code block.

```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
    return (
        <h1>Hello, Docusaurus!</h1>
    )
}
```

function HelloDocusaurus() {
  return <h1>Hello, Docusaurus!</h1>;
}

To highlight lines in the code, use {#} in the title line with lines numbers. This example highlights lines 2 through 6.

```sql {2-6}
_sourceCategory=reinvent/travel/checkout
[subquery:_sourceCategory=reinvent/travel/nginx
     | count by src_ip
     | topk(1,_count)
     | compose src_ip keywords
]
| json field=_raw "funcName"
| where funcname in ("process_cart","charge")
| if (funcname = "process_cart" , "Checkout", "Purchased") as funcname
| count by funcname
```

_sourceCategory=reinvent/travel/checkout
[subquery:_sourceCategory=reinvent/travel/nginx
     | count by src_ip
     | topk(1,_count)
     | compose src_ip keywords
]
| json field=_raw "funcName"
| where funcname in ("process_cart","charge")
| if (funcname = "process_cart" , "Checkout", "Purchased") as funcname
| count by funcname

For a full list of options, see Docusaurus Code Blocks.

Collapsible text blocks

You can use an expander to collapse long content that can be searched, but not displayed, when loading a page. We recommend using expanders only for additional content and long code samples. Content required for instructions and steps should not be placed in an expander.

You can include markdown content in expanders including code samples, embedded videos, bulleted lists, and more.

<details><summary>Title for the expander</summary>

Place long lists or lots of content in this section. The reader can expand/collapse as needed.

Add all content after Summary and before the closing details tags.

</details>

Example expander

Place long lists or lots of content in this section. The reader can expand/collapse as needed.

"overrides": [
    {
    "series": [],
    "queries": [
        "A"
        ],
    "userProvidedChartType": false,
    "properties": {
        "type": "column"
        },
    "unsafeCanvasJSProperties": {
        "bevelEnabled": true,
        "indexLabelPlacement": "inside",
        "indexLabel": "{y}",
        "indexLabelOrientation": "vertical"
        }
    }
]

Contractions

Using contractions contributes to our goals of striking a conversational, friendly tone. Use common contractions, like “don’t”, “won’t”, and “you’ll”. Avoid less common contractions, like “should’ve”, or “it’ll”. Do not use negative contractions (don't, can't, shouldn't), as they can be easily mistaken for the opposite meaning. Spell out those words.

Downloadable files

To link to a downloadable asset file, such as a .yaml, .json, or .xml:

Drag and drop your file to the static/files folder. In this example, we'll drop in a file called domainCollector.ps1.
<img src={useBaseUrl('img/contributing/static-file.png')} alt="header sizes" width="250"/>
Go to your doc in progress and use the following syntax to link the file: <Tabs className="unique-tabs" defaultValue="Markdown" values={[ {label: 'Markdown', value: 'Markdown'}, {label: 'Result', value: 'Result'}, ]}>

<a href="https://help.sumologic.com/files/domainCollector.ps1" target="_blank">domainCollector.ps1</a>

domainCollector.ps1

Nearly all file formats are supported. For more information, see Docusaurus Static Assets.

If your file is available in another public Sumo Logic repo, provide the standard URL link. Here's an example.

Emphasis

Bold

Use bold for UI elements you interact with, such as a button or tab.

Italics

Use italics for:

Defining a term the first time. For example, when defining a collector the first time, you would italicize once with the definition.
Providing content to enter into a field.

Underlines

Never underline text.

Emphasis, aka italics, with *asterisks* or _underscores_.

Strong emphasis, aka bold, with two **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough uses two tildes. ~~Scratch this.~~

Emphasis, aka italics, with asterisks or underscores.

Strong emphasis, aka bold, with two asterisks or underscores.

Combined emphasis with asterisks and underscores.

Strikethrough uses two tildes. ~~Scratch this.~~

Font

We use Lab Grotesque in our docs site and across all Sumo Logic media.

Headings

Use hashtags # to indicate the heading level and group content. Always start with H2 headers (##) in your doc body. Link anchors also generate automatically.

We mark a heading using a number of # for the level. This section is using an H3 heading, which is ### Headings.
Never use H1 (#) in your document. This is generated automatically by the page title (title: in frontmatter).
Headings should always be clean, plain text. Do not use bold, italics, or code ticks.
Be careful of using special characters. Dashes are ok, but try to avoid other punctuation.

## I'm an H2

### I'm an H3

#### I'm an H4

##### I'm an H5

###### I'm an H6

Headings must be used in correct order. The subsection of an H2 header would be H3 - you wouldn't jump to an H4 or H5. Skipping over a header level affects search and SEO structures to search crawlers like Google. Malformed structures can reduce search and SEO for the page. Docusaurus carefully formats generated pages to ensure strong SEO.

Documenting procedures

When a topic provides instructions for a significant multi-step process, organize the content in sections with headings that signpost the nature of the information. Include "Step" in the heading to make it clear that the section is part of a larger configuration process. For example:

Hub pages

To generated a full list of docs within a folder, add this code to the file:

import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

## Guide contents

In this section, we'll introduce the following concepts:

<DocCardList items={useCurrentSidebarCategory().items}/>

This is best used in an index file, including a list of all files and folders in that folder to the file. See any category file for a section in the site for how this looks.

Images

Add an image

Save your image to the /static/img folder. This folder structure mirrors the doc section folders.
- When updating an existing images (like if there's a Sumo UI change), do not add a new version; always replace existing images. Image files take up a lot of room and can slow build times.
- File format be .png or .gif.
Add the import line to the top of your doc, underneath the front matter header, if it's not already there.

import useBaseUrl from '@docusaurus/useBaseUrl';

Copy the below code snippet and paste it where you want your image to appear.

<img src={useBaseUrl('img/<your-image-file-path>.png')} alt="<your image description>" width="<insert-pixel-number>"/>

Replace with file path above with your own image file path. The file path must start with img (do not preface it with /static) because Docusaurus builds and saves these static assets and serves from the baseUrl (or domain). :::info For web-hosted images, do not use the useBaseUrl syntax.
- ✅ Do: <img src='https://sumologic-app-data-v2.s3.amazonaws.com/dashboards/Jira-OpenTelemetry/Jira-Catalina.png' alt="Catalina" />
- ❌ Don't: <img src={useBaseUrl('https://sumologic-app-data-v2.s3.amazonaws.com/dashboards/Jira-OpenTelemetry/Jira-Catalina.png')} alt="Catalina" />
  :::
Add alt text for your image (for example, "Image properties dialog" or "Sumo Logic logo"). This is a brief description what the image is meant to show. Alt text is a label, not a caption, doesn't need to describe all details of an image. If you are editing and you come across an image without alt text, add it!

More about alt text

Alt text is used by readers who can't see images well, or who have software that reads the text aloud, and even by readers with slow Internet connections who don't want to wait for images to download. Alt text is required under US Government GSA Section 508 regulations. Non-compliance with Section 508 can cost a company federal sales. Many companies start out ignoring this future possibility and, like everything, it is more expensive to fix later.

Use the width to resize oversized and/or pixelated images, if needed.

<img src={useBaseUrl('img/sumo-square.png')} alt="Sumo Logic thumbnail logo" width="150"/>

Image sizes

When sizing images, use your discretion.

Logos

For square logos, set the width to about 45-55px.

Yes ✅	No ❌
<img src={useBaseUrl('img/contributing/logo-yes.png')} alt="alt-text" width="400"/>	<img src={useBaseUrl('img/contributing/logo-no.png')} alt="alt-text" width="400"/>

For wide logos (like in this doc), set the width to about 90-120px.

Screenshots

Ensure that screenshots are large enough so that the content is legible, but not comically oversized. Use your discretion.

Yes ✅	No ❌
<img src={useBaseUrl('img/contributing/screenshot-yes.png')} alt="alt-text" width="400"/>	<img src={useBaseUrl('img/contributing/screenshot-no.png')} alt="alt-text" width="400"/>

Screenshots should never be wider than 600px.

Images in lists

When adding an image to a bulleted or sequential list, include the image snippet in-line with the list item, with a <br/> element in between, like this:

1. Here is a dinosaur.<br/><img src={useBaseUrl('img/docusaurus.png')} alt="alt-text" width="100"/>

Here is a dinosaur.
<img src={useBaseUrl('img/docusaurus.png')} alt="alt-text" width="100"/>

Screenshots

Capture screenshots using SnagIt in .png format. Use SnagIt's border effect to apply a gray (RGB 212, 212, 212) four-point border.

By default, images that you insert into a page are set to be responsive - resized for the type of device the reader is using.

Masking sensitive information

We mask sensitive information like usernames, email addresses, and IP addresses. In Snagit or a similar program, use the shape tool to mask the text using solid gray, (RGB 212, 212, 212).

Callouts

Create callouts using the shape tool in SnagIt. Callouts should be red, 100% opacity, no drop shadow effect, 2 pts wide.

Lists

You can mix ordered (or numbered) and unordered (or bulleted) lists together. Use extra lines and tabs (or 2 spaces) to move content under these bullets, including other bullets, paragraphs, images, and more. Be careful of indenting too much; three tab indents will automatically render as code.

In a list item made up of an introductory word or phrase and an explanatory sentence or paragraph, separate the introductory text and the explanation with a period (.) rather than a dash (-). For example:

1. **Entity**. Select the Entity field in the Record that the resulting Signal should be associated with.
1. **Description (Optional)**. Define the description for the Signal.

Entity. Select the Entity field in the Record that the resulting Signal should be associated with.
Description (Optional). Define the description for the Signal.

Numbered Lists

Use numbered lists when providing a set of instructions or steps.

Always start with 1.. Markdown automatically numbers sequentially when building the site. This can be helpful when you need to add or change the order of instructions (no need to edit every number).

1. First ordered list item.
1. Another item.
   - Unordered sub-list.
1. Actual numbers don't matter, just that it is a number.
   1. Ordered sub-list.
1. And another item.

  More content for this entry. And a screenshot:<br/> ![span hover](/img/apm/traces/span-hover-view.png)

First ordered list item.
Another item.
- Unordered sub-list.
Actual numbers don't matter, just that it is a number.
1. Ordered sub-list.
And another item.
- More content for this entry. And a screenshot:

Bulleted Lists

Use bulleted lists when the items don't need to be presented in sequential order. End each bullet in a terminal period. Use asterisks * for unordered, bulleted lists.

* Unordered list line 1.
* Line 2.
   <br/>Content to show under 2.
* Another set of bullets.
* Here we go, another!

Unordered list line 1.
Line 2.
Content to show under 2.
Another set of bullets.
Here we go, another!

You can configure your editor to always use this format for lists. For Visual Studio Code, configure the following settings:

Ordered List: Marker set to one.
Unordered List: Marker set to *.

Ensure parallel grammatical structure - that is, start each bullet with the same part of speech.

Links

For docs links, use relative file paths. For everything else (external links), use absolute URL paths.

Linking to other headers in the same file:

Here's how to make a [table](#tables).

Linking to files in the same folder:

* Check out our [glossary](glossary.md).
   <br/>or
* Check out our [glossary](./glossary.md).
   <br/>or
* Check out our [glossary](/docs/contributing/glossary).

Linking to files in other parent folders:

* Learn how to [sign up with Sumo](../get-started/sign-up.md).
   <br/>or
* Learn how to [sign up with Sumo](/docs/get-started/sign-up).

Linking to external URLs:

For more information, see [Export Logs to Sumo Logic](https://auth0.com/docs/extensions/sumologic).

Linking to other headers in the same file:

Here's how to make a table.

Linking to files in the same folder:

Check out our glossary.
or
Check out our glossary.
or
Check out our glossary.

Linking to files in other parent folders:

Learn how to sign up with Sumo.
or
Learn how to sign up with Sumo.

Linking to external URLs:

For more information, see Export Logs to Sumo Logic.

Markdown

Markdown is a simple, text-based format you can write using text editors, IDEs, or the GitHub website to write content. We use Docusaurus to manage, style, and build our site. We use GitHub-flavored Markdown, with some additional options. You can find more info at:

Docusaurus | Markdown Cheat Sheet
Markdown Guide
Markdown Cheatsheet

File naming convention

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

Metadata (Frontmatter)

Markdown documents have metadata (e.g., title, description, and search keywords) at the top called frontmatter. Every page should have an id used for sidebar navigation.

---
id: page-id
title: Page title
sidebar_label: Navigation title
description: Learn more about...
keywords:
    - metrics
    - traces
tags: [apm, metrics]  
---

Parameter	Description
`id:`	(Required) Id for the page used in the sidebar and as the canonical link. Keep it short and only use dashes.
`slug:`	(Optional) Overrides the `id:` for the canonical link. Best used for index pages for sections.
`title:`	(Required) For SEO, be sure to sure main keywords in your title and keep it under 60 characters. This title is used in navigation if a `sidebar_label` is not included.
`sidebar_label:`	(Optional) Use a different title for the side navigation. Keep this title short. It does not affect the canonical link or page title.
`description:`	(Optional) 1-2 sentences describing what the user will find in the doc. It appears in search engine results. If omitted, search engines will pull first couple sentences instead.
`keywords:`	(Optional) List of page keywords, which boosts SEO.
`tags:`	(Optional) A string or list of tags that adds a label and permalink to tag to help with sorting.

For a full list of options, see Docusaurus Markdown front matter.

Navigation menus

Top-level navigation content is controlled in our docusaurus.config.js file.

Our sidebars.ts file controls the sidebar navigation for the entire site. It consists of multiple sidebars and sections based on the Guides top navigation, drilling down per guide. A list of sections and advice on content is at the top of the sidebars file, with comments throughout.

To add a specific page, you include the directory path and topic id from the frontmatter. For example, this page is contributing/style-guide.
To add a section within a section, use a category section with page links in it (see below example).
To add an index for a section, create an index.md page in the folder. Give it a slug: name where the name is the folder for the entire section like contribution-guide. In the category, use a link line with the folder name and index for example: link: {type: 'doc', id: 'contributing/index'},.
To add a new page, make note of the file path and id. For example, this document is located in the folder contributing with an id of create-document. When adding this file to the sidebar, it would be added to the contributing/create-document.

Example: add contribution/create-document to sidebars.ts

//Contribution guide for documentation
  contributing: [
    {
      type: 'category',
      label: 'Contribution Guide',
      collapsible: true,
      collapsed: false,
      link: {type: 'doc', id: 'contributing/index'},
      items: [
        'contributing/create-document',
        'contributing/build-deploy',
        'contributing/translations',
        {
          type: 'category',
          label: 'Templates',
          collapsible: true,
          collapsed: false,
          items: [
            'contributing/templates/partner-app-doc'
          ]
        }
      ],
    },
  ],

To add a category, or dropdown list of documentation, use the following format:

Example: add sidebar category example with additional section

    {
      type: 'category',
      label: 'Name of Guide',
      collapsible: true,
      collapsed: false,
      link: {type: 'doc', id: 'foldername/id-first-page'},
      items: [
        'foldername/doc-id1',
        'foldername/doc-id2',
        {
          type: 'category',
          label: 'Section in Guide',
          collapsible: true,
          collapsed: false,
          link: {type: 'doc', id: 'foldername/id-section'},
          items: [
            'foldername/doc-id3',
            'foldername/doc-id4',
          ]
        }
      ],
    },

To add a dedicated sidebar, use the following format:

Example: adding a dedicated sidebar for a guide

module.exports = {
  sectionName: [
    {
      type: 'category',
      label: 'Name of Guide',
      collapsible: true,
      collapsed: false,
      link: {type: 'doc', id: 'foldername/id-first-page'},
      items: [
        'foldername/doc-id1',
        'foldername/doc-id2',
        {
          type: 'category',
          label: 'Section in Guide',
          collapsible: true,
          collapsed: false,
          link: {type: 'doc', id: 'foldername/id-section'},
          items: [
            'foldername/doc-id3',
            'foldername/doc-id4',
          ]
        }
      ],
    },
    {
      type: 'category',
      label: 'Name of Another Guide',
      collapsible: true,
      collapsed: false,
      link: {type: 'doc', id: 'otherfoldername/id-first-page'},
      items: [
        'otherfoldername/doc-id1',
        'otherfoldername/doc-id2',
        {
          type: 'category',
          label: 'Section in Another Guide',
          collapsible: true,
          collapsed: false,
          link: {type: 'doc', id: 'otherfoldername/id-section'},
          items: [
            'otherfoldername/doc-id3',
            'otherfoldername/doc-id4',
          ]
        }
      ],
    },
  ]

Patents and trademarks

Protecting our patents and trademarks is important to do correctly. We don't want to expose the company to a loss of trademark or patent just because we didn't list it correctly.

This is a partial list of trademarked terms, which should be capitalized exactly as shown below.

Sumo Logic
Big Data for Real Time IT
Log Reduce
Elastic Log Processing
Push Analytics

Never use Sumo Logic in the plural or possessive form.

Punctuation

Punctuation is placed outside of quotation marks, British English style. For everything else (dates, times, spelling), we use American English style.

Commas

We use the Oxford (serial) comma. For example, use "I had eggs, toast, and orange juice", not "I had eggs, toast and orange juice".

Release Notes

Keep release notes concise with links to documentation and images for updated UI elements. You're welcome to add frontmatter such as tags and keywords.

Text only

To add release notes without images:

In the Blog folder, create a new markdown file with the following name format: YYYY-MM-DD-product.md.

Add the following frontmatter:

---
title: Product or Feature Name
tags: [apps, tracing]
hide_table_of_contents: true
image: https://help.sumologic.com/img/sumo-square.png
keywords:
  - sumo logic
  - service release notes
  - open source
authors:
  - url: https://help.sumologic.com/release-notes-service/rss.xml
    image_url: /img/release-notes/rss-orange.png
---

title: Name of the release notes including Product or Feature
tags: Add a comma-separated list of existing tags, including:
hide-table-of-contents: Hide the TOC on the page, keeping the notes clean and wide on the page.

Document the release notes. Add links, bullets, and images as needed.

Long Release Notes

For lengthy release notes, we recommend introducing the notes and adding a truncate line (), followed by the full set of release notes.

Text and Images

To add release notes with images:

In the Blog folder, create a new folder with the following name format: YYYY-MM-DD-product.
In the new folder, create a markdown file named index.md. Add your release notes with frontmatter:
```
---
title: Product or Feature Name
tags: [apps, tracing]
hide_table_of_contents: true
---
```
- title: Name of the release notes including Product or Feature
- tags: Add a comma-separated list of existing tags, including:
- hide-table-of-contents: Hide the TOC on the page, keeping the notes clean and wide on the page.
Save images to this folder and add them to the markdown file: ![alt text](image-name.png).

Reusing Content

For repeatable content (like an identical section that appears in several docs), you can save a lot of time by creating one instance of that content in the /docs/reuse folder and then import that snippet to other docs.

Create a new markdown file and save it to the /docs/reuse folder.
Import that content to another doc by adding this snippet (substitute the file path with your own).
```
{@import ../../reuse/filename.md}
```

Headings in the reuse folder will not appear in the right-side nav in docs where they're imported. For this reason, unless the headers are H4 or below, reuse the content only but retain headings in the other docs.

Example: the content under the Cloud-to-Cloud source docs > Restarting Your Source section (example) lives in the reuse folder. The H3 headers live in the actual docs, and H4 headers live in the reuse file:

### Restarting your source

{@import ../reuse/restart-c2c-source.md}

Restarting your source

{@import ../reuse/restart-c2c-source.md}

Tables

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

Tables use plain markdown with one header, default left-aligned columns, and multi-colored rows. You can use Markdown for links and images. To break up content, you can use <br/> for line breaks.

| Column Name | Example Value | Description |
| :-- | :-- | :-- |
| Trace ID | ffaf2f69ee8ad0c1 | The unique identifier of the trace. |
| Root Service | api | The service that started the trace. |
| Started At | 07/27/2020 09:01:04.533 | When the trace started. |
| Duration | 12.582 ms | The amount of time the trace spans.  |
| Number of spans | 35 | A trace consists of spans. This number tells you how many spans are in the trace. |
| Duration Breakdown | ![breakdown](/img/apm/traces/breakdown.png) | Each color indicates a service. The colors assigned to services are always the same on your account. You can change the color in the span summary tab after clicking on the individual span in trace view.<br/>Hover over to view a percentage breakdown of how long each span covers in the trace.<br/>![span hover](/img/apm/traces/span-hover-view.png) |
| Number of errors | 0 | The number of errors in the trace. |
| Status | 200 | The HTTP status code of the trace. |

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

Column Name	Example Value	Description
Trace ID	ffaf2f69ee8ad0c1	The unique identifier of the trace.
Root Service	api	The service that started the trace.
Started At	07/27/2020 09:01:04.533	When the trace started.
Duration	12.582 ms	The amount of time the trace spans.
Number of spans	35	A trace consists of spans. This number tells you how many spans are in the trace.
Duration Breakdown		Each color indicates a service. The colors assigned to services are always the same on your account. You can change the color in the span summary tab after clicking on the individual span in trace view. Hover over to view a percentage breakdown of how long each span covers in the trace.
Number of errors	0	The number of errors in the trace.
Status	200	The HTTP status code of the trace.

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

Docusaurus also supports HTML tables.

Tabs

Use the following code to create tabbed content. You can use Markdown in these tabs, including text, code content, images, and more.

At the bottom of the Markdown file, add the following code:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

For each set of tabs, use the following code:

<Tabs
  className="unique-tabs"
  defaultValue="tab1"
  values={[
    {label: 'Tab 1', value: 'tab1'},
    {label: 'Tab 2', value: 'tab2'},
  ]}>

<TabItem value="tab1">

Add content here for first tab.

</TabItem>
<TabItem value="tab2">

Add content here for second tab.

</TabItem>
</Tabs>

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

See the following tabbed code examples:

Setup a Source in Sumo Logic:

Navigate to Collection management (Manage Data > Collection) Use an existing Hosted Collector, or create a new one. Next to the collector, select “Add Source”. Select “AWS Kinesis Firehose for Logs” Enter a Name to identify the source. Enter a Source Category following the best practices found in “Good Source Category, Bad Source Category”

Deploy the Cloudformation Template to Create a Kinesis Firehose Delivery Stream:

Download the Cloudformation template.
Open CloudFormation in AWS.
Create a new stack using the CloudFormation template you downloaded.
Provide the URL you created from your Sumo source.
Select an S3 bucket to deliver failed logs, or create a new one.
Click next.

Accept the IAM permissions, and create the stack.

Info for the second tab would go here! Content can include markdown, code blocks, notes, and more.

SEO

For clarity and search engine discoverability:

Doc titles are very important for SEO. Use primary target keywords, try to mention "Sumo Logic, and keep length under 60 characters.
- Example: ~~Monitoring with the Observability Solution~~ → Monitoring with Sumo Logic Observability
Use H2 sections to break up content and try to use primary keywords here as well.
- Example: AWS Observability Solution.
H3 and H4 headers don't impact SEO as much. Use short, meaningful titles for readability and search.
- Example: System architecture and monitoring.

:::sumo For internal contributors

If you change a URL, set up a redirect so that users don’t get a 404 page.
Use Google Analytics to make data-driven decisions. :::

Videos

To embed a YouTube video on a doc:

Copy and paste the following code into your page (including the import Iframe line).

<Iframe url="https://www.youtube.com/embed/abcde12345?rel=0"
     width="854px"
     height="480px"
     id="myId"
     className="video-container"
     display="initial"
     position="relative"
     allow="accelerometer; autoplay=1; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
     allowfullscreen
     />

import Iframe from 'react-iframe';

Remove the URL ID from the snippet (abcde12345) and replace it with your own video ID, which you can find in the YouTube link URL.
Ensure that ?rel=0 is appended to the end of the URL. This ensures that only videos from the current YouTube channel will be suggested to the viewer after they've finished viewing the embedded video.

<Iframe url="https://www.youtube.com/embed/ZcbHoC1jZz4?rel=0"
        width="854px"
        height="480px"
        id="myId"
        className="video-container"
        display="initial"
        position="relative"
        allow="accelerometer; autoplay=1; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
        allowfullscreen
        />

import Iframe from 'react-iframe';

import Iframe from 'react-iframe';

React components

MDX

MDX can make your documentation more interactive and allows using any React components inside Markdown:

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '20px',
      color: '#fff',
      padding: '10px',
      cursor: 'pointer',
    }}
    onClick={() => {
      alert(`You clicked the color ${color} with label ${children}`)
    }}>
    {children}
  </span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

This is <Highlight color="#1877F2">Facebook blue</Highlight> !

export const Highlight = ({children, color}) => ( <span style={{ backgroundColor: color, borderRadius: '20px', color: '#fff', padding: '10px', cursor: 'pointer', }} onClick={() => { alert(You clicked the color ${color} with label ${children}); }}> {children} );

This is Docusaurus green !

This is Facebook blue !

Mermaid Charts

Mermaid provides sequence diagrams, charts, and more. Use these charts to detail processes, workflows, inheritance, and more. See the Mermaid guide for specifics and examples, and use the live editor to generate code.

See the following example code for adding Mermaid charts. You need to include the import line once per page.

<Mermaid chart={`
	graph LR;
		A-->B;
		B-->C;
		B-->D[Example Label];
`}/>
import Mermaid from '@theme/Mermaid';

<Mermaid chart={graph LR; A-->B; B-->C; B-->D[Example Label];}/>

import Mermaid from '@theme/Mermaid';

Files

style-guide.md

Latest commit

History

style-guide.md

File metadata and controls

Writing Resources

Voice and Tone

Active Voice

Inclusive language

Doc structure summary

Abbreviations

Acronyms

Admonitions

Beta Releases

Closed Beta

Open Beta

Capitalization

Code (Inline)

Code Blocks

Collapsible text blocks

Contractions

Downloadable files

Emphasis

Bold

Italics

Underlines

Font

Headings

Documenting procedures

Hub pages

Images

Add an image

Image sizes

Logos

Screenshots

Images in lists

Screenshots

Masking sensitive information

Callouts

Lists

Numbered Lists

Bulleted Lists

Links

Markdown

File naming convention

Metadata (Frontmatter)

Navigation menus

Patents and trademarks

Punctuation

Commas

Release Notes

Text only

Long Release Notes

Text and Images

Reusing Content

Restarting your source

Tables

Tabs

SEO

Videos

React components

MDX

Mermaid Charts