Style Guide

Rootwire welcomes your contributions to our documentation. This document describes the options available for creating content for the site, along with some guidelines and conventions.

Markdown

This site uses Docusaurus version 2. Docusaurus uses the remarkable Markdown processor to convert GitHub Flavored Markdown into HTML. Docusaurus Markdown supports Basic Markdown Syntax and most Extended Syntax. You can see which features are supported here.

Frontmatter

At the top of each docs page, you need to include these things:

Variable	Description
id	A brief string that uniquely identifies the page within its parent folder. The id and the name of the file should be the same.
title	The main title of the page. This value will automatically be rendered using the H1 style at the top of the page.
sidebar_label	This is what will appear in the left hand navigation tree for the page.
description (optional)	This is what appears when the page is referenced in a Google search result.
keywords (optional)	A list of terms that help categorise the page for SEO purposes.
tags (optional)	A list of terms that help categorise within the site - use lowercase

It looks like this in the document:

---
id: style-guide
title: Style Guide Introduction
sidebar_label: Style Guide
description: The Rootwire OpenDocs Documentation Style Guide
keywords:
- contributing
- style
- markdown
tags:
- contributing
- style
- markdown
---

Introduction

The first paragraph of the documentation should set the user's expectations for what they will find on the page. Describe the key benefits to the user, but do not include links.

Headers

For accessibility and SEO reasons, never have an H4 header that isn't under an H3 header, or an H3 header that isn't under an H2 header.

• H1 headers should never be used in a document since the title is automatically generated as an H1.
• H2 headers are used for SEO, so make sure they succinctly represent what a user will find on the page in that section.
• H3 headers are included in the page's table of contents on the right, so make sure the title describes something a user might want to directly navigate to.
• H4 headers are to emphasize things within a subsection of the page; these can be longer than the other headers if needed because they aren't included in the Table of Contents.

Markdown Code:

## H2 Header

### H3 Header

#### H4 Header

Content

All words are rendered in the same paragraph even with line breaks, so long as there isn't an empty line. As such, it is good practice for each line to be less than 120 characters long for readability, when possible.

Markdown	This will all be on one line. The empty line above creates a new paragraph. This forces a soft return<br /> rather than creating a new paragraph
Display	This will all be on one line. The empty line above creates a new paragraph. This forces a soft return rather than creating a new paragraph

Images

All image files should be included in the _files directory inside the directory containing the content E.G: Images for a document in the /docs/contributing directory would be located in the /docs/contributing/_files directory.

Videos

Any referenced videos need to be from a YouTube account. The suggested iframe code structure is as follows:

<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/dQw4w9WgXcQ"
frameborder="0"
allow="accelerometer;
autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>

Tabs

Tabs are a great option when an example is different in different contexts. The primary usage of tabs on this site is to illustrate the same example in multiple languages. For example, a snippet might exist in bash, Python and Powershell, and the tabs should be placed in that order.

tip

When a page includes multiple sets of tabs, use a groupId so when the user selects a particular tab, all tabs with that ID will switch to the selected tab.

To use tabs, you need to import two special methods by placing these lines below the Frontmatter, but above the Introduction:

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

and then use the tabs as follows:

Markdown	<Tabs groupId="lang-ex"> <TabItem value="bash" label="bash" default> This would include information or examples for Bash </TabItem> <TabItem value="powershell" label="Powershell"> This would include information or examples for Powershell </TabItem> </Tabs>
Display	bash This would include information or examples for Bash Powershell This would include information or examples for Powershell

Inline Code

To refer to a single class or method name in a sentence, place single backticks around the name.

Markdown	This comment refers to the `Firewall` device
Display	This comment refers to the Firewall device

Code Blocks

The best way to display code is with code blocks. Markdown will highlight each language differently, so it is helpful to specify which language you are using, and it's a good idea to include a title with the code block as well.

Markdown	```powershell title="Custom Title" Get-ChildItem -Recurse ```
Display	Custom Title Get-ChildItem -Recurse

Expanding Code Blocks

If you have an especially large code block that you'd like to reference on the page, but do not want it to take up too much space on the page by default, we encourage the use of details elements.

HTML	<details> <summary> <strong>Click here</strong> to see an example of something hidden by default. </summary> This is hidden by default. </details>
Display	Click here to see an example of something hidden by default. This is hidden by default.

Admonitions

There are four types of Docusaurus admonitions:

• Note - Relevant information.
• Tip - A user should do this.
• Caution - A user should pay attention to this.
• Warning - A user might do something dangerous.

Markdown	:::note Relevant information for you. ::: :::tip You should do this. ::: :::caution You should probably pay attention to this. ::: :::warning You are about to do something dangerous. :::
Display	note Relevant information for you. tip You should do this. caution You should probably pay attention to this. danger You are about to do something dangerous.

Context Limited

There are two ways to provide context for users for when special conditions or limitations apply to designated information.

Badges

Badges are color-coded images that apply to entire pages or large sections of documentation.

Green badges are used for everything except for deprecated information, which is indicated with a Gold badge.

HTML	<p><span className="rootwireGreen">Beta</span></p> <p><span className="rootwireGreen">Draft</span></p> <p><span className="rootwireGreen">Enterprise</span></p> <p><span className="rootwireGreen">Live Testing Only</span></p> <p><span className="rootwireGreen">Early Access</span></p> <p><span className="rootwireGold">Deprecated</span></p>
Display	Beta Draft Enterprise Live Testing Only Early Access Deprecated

Highlighted Text

For information in a subsection or in a table that needs additional context, use a span element with one of the highlight classes. These can also be used to indicate that the content only applies to specific versions of a technology.

HTML	<p><span class="highlight windows">Windows version >= 2012</span></p> <p><span class="highlight linux-rhel">Linux - Red Had</span></p> <p><span class="highlight linux-ubuntu">Linux - Ubuntu</span></p>
Display	Windows version >= 2012 Linux - Red Had Linux - Ubuntu

Cards

For overview pages that have four categories, we often use these Boxes. Note that you can't use Markdown inside this HTML.

HTML

<div className="box-wrapper" markdown="1"> <div className="box box1 card"> <div className="container"> <h2>Box 1</h2> <p>Box 1 things.</p> <ul> <li><a href="">Link 1</a></li> <li><a href="">Link 2</a></li> </ul> </div> </div> <div className="box box2 card"> <div className="container"> <h2>Box 2</h2> <p>Box 2 things.</p> <ul> <li><a href="">Link 1</a></li> </ul> </div> </div> <div className="box box3 card"> <div className="container"> <h2>Box 3</h2> <p>Box 3 things, <a href="">Link 1</a>.</p> <ul> <li><a href="">Link 2</a></li> </ul> </div> </div> <div className="box box4 card"> <div className="container"> <h2>Box 4</h2> <p>Box 4 things.</p> <ul> <li><a href="">Link 1</a></li> <li><a href="">Link 2</a></li> </ul> </div> </div> </div>

Display

Box 1 Box 1 things. Link 1 Link 2 Box 2 Box 2 things. Link 1 Box 3 Box 3 things, Link 1. Link 2 Box 4 Box 4 things. Link 1 Link 2