Style Guide
When writing new documentation please try to follow the style guide for adding in new content. If you don't follow the guide it will cause a delay in how quickly the content is pulled into the documentation as editors will need to adjust or correct the content. This project also uses a markdown linter to check for any overall stylistic inconsistencies and catch some common problems with syntax. For more information on what markdown rules we adhere to read to the bottom of this page for more information.
Headers
At the very least you should have a main header which can be written as so below:
# This is our main header
You can also have other headers underneath the main header. Secondary headers will automaticly have a menu option generated for them to quickly bring readers to that header's section from the left hand side menu of the page.
## This is a secondary header
### This is a tertiary header
Text
Text can be modified in several ways, you can bold, italalicize, or strikethough portions of text.
Text can be modified in several ways, you can **bold**, *italalicize*, or ~~strikethough~~ portions of text.
Additionally for calling out commands or files (eg. sync or /etc/hosts) in descriptions outside of code blocks you can use inline code blocks to seperate them out from the rest of the text for easy reading.
Code Blocks
You can also insert code blocks into the documentation and even get some syntax highlighting
echo "How are you today?"
exit 0
```bash
echo "How are you today?"
exit 0
```
Tables
Below you will find an example of a formatted table. In the second column you will notice that we have the column values center aligned, and the third column we have right aligned.
| Partition | # Nodes | # CPUs |
|---|---|---|
| SHAS | 470 | 11,280 |
| SMEM | 7 | 168 |
| SKNL | 20 | 5,440 |
| Partition | # Nodes | # CPUs |
|-------------|:----------:|---------:|
|SHAS | 470 | 11,280 |
|SMEM | 7 | 168 |
|SKNL | 20 | 5,440 |
Lists
You can include both unordered and ordered lists like seen below as well
- This is the first item
- Here is a second item
- Finally a third item
- First unordered item
- Second unordered item
- Final unordered item
1. This is the first item
2. Here is a second item
3. Finally a third item
- First unordered item
- Second unordered item
- Final unordered item
Notes
You can also write notes or info boxes to provide extra context or helpful notes when needed using the following syntax
this is a note, it can be pointless
Notes are quite helpful for providing context
Warnings
You can write warning boxes when you want to alert the reader that that there is important information to consider before they act or execute a command
You have been warned!
Warning boxes should be used sparingly and only when the reader should take caution before proceeding further
Danger
Danger boxes should be used very sparingly and should alert the reader that they either should not do what is suggested in the box, or should avoid it all together.
Danger Dr. Smith! Do not use rm -rf \
Always backup important system files before you decide to blow them away
# examples of Notes, Warnings, Tips, and Danger cards
```note
text here
```
```tip
text here
```
```warning
text here
```
```tip
text here
```
```danger
text here
```
Markdown Linter
For this project we use the markdown linting capabilities offered by Markdownlint, deployed as a github action to lint all commits to the master branch of this repository. We have a markdown lint rules file within the .github/linters directory with the settings that we use for various rules and rule exceptions where they are needed.
A few notable rules to keep in mind are MD003 which specifies that there can only be one H1 header in a document, and MD026 which specifies that there should be no punctuation in a header element.