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 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.
/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.
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 ```
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|
| Partition | # Nodes | # CPUs | |-------------|:----------:|---------:| |SHAS | 470 | 11,280 | |SMEM | 7 | 168 | |SKNL | 20 | 5,440 |
You can include both unordered and ordered lists like seen below as well
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
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
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 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 ```
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.
Jekyll RTD Theme documentation