Skip to main content

Docs Site Standards

There are a number of standards that every docs site page tends to follow, as to make the docs site easy to read and use. These standards are just guidelines and don't have to be followed to a T, but are generally in place to add parity and align all doc pages.

Below is the guide to these standards:

Page Standards​

Header & Position​

Every page, as you'll notice in code, includes a 'title' and 'sidebar position'. These two values as written in the example below control the name of the document page and where it appears in the side bar.

---
title: How to Contribute
sidebar_position: 2
---
  • 'title' refers to the text that will appear in the left sidebar AND at the top of the page.
  • 'sidebar_position' refers to the order the pages will appear in the left sidebar within their directory.
    • Position 0 is reserved for the landing page.

Then, the filename is written as "01my-documentation" where the starting number '01' matches the sidebar position.

Page Description​

Each page, then has a short 'Page Description' where a brief overview of the page is given. Below is an example of this set up.

---
title: How To Play D&D
sidebar_position: 3
---

The rules of D&D can be vast and overwhelming, but this guide 
is simple and designed to guide new players. If You're ever stuck 
or confused, reach out to your DM!

---

## First Section Header

Styling & Additions​

Common Text Styling​

The docs site uses MDX markdown, meaning you can achieve bold text or cool links with very simple text-based styling. Below is a guide to the most common:

Note that HTML tags work as well! Like the always useful linebreak <br/>
<u> or the handy underline <u/>

Images​

Images can be added, but require the file to be added to the GitHub repo and the use of an HTML image tag. Notice that all images should be stored under the static\img directory and then follow a branching folder path that mirrors the page they were added for. As example:

<img src='\img\company-info\docs-site\standards\shrimp.gif' width='400' />

Tables​

Tables can be added with the following setup:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row1C1   | Row1C2   | Row1C3   |
| Row2C1   | Row2C2   | Row2C3   |
Column 1Column 2Column 3
Row1C1Row1C2Row1C3
Row2C1Row2C2Row2C3

Code Snippets​

Chunks of code can be shared without special characters causing issues: Single Lines

The snippet ` SELECT * FROM MyTable ` can be used to get all records.

The snippet SELECT * FROM MyTable can be used to get all records.

Multi-Line Blocks (Note, the starting '|' character was used here only for formatting)

|```
|SELECT * FROM MyTable
|WHERE MyValue = 3
|AND MySecondValue IS NULL
|```
|SELECT * FROM MyTable
|WHERE MyValue = 3
|AND MySecondValue IS NULL
Last updated on by Zach Sedlack