Having been recently introduced to GitHub and the world of programming, I rapidly understood the importance of comprehensive README files for communicating any project (mainly, because, most of the time, any other way I have no idea what's going on). Those are formatted using (GitHub Flavored) Markdown, or, alternatively, HTML for more formatting options.
This guide was developed from that understanding, with the hope it can be helpful to anyone else out there.
Disclaimer: I come from a background in design, so I also cry a little when I see unclear information hierarchy. Plus, I'm a firm believer that allocating time for organization and communication can boost efficiency in the future. Feedback is more than welcome!
What is Markdown?
Markdown is a simplified markup language, adding formatting elements to plain text, created by John Gruber with the collaboration of Aaron Swartz in 2004.
In truth, it's both a plain text formatting syntax, and a "a software tool, written in Perl, that converts the plain text formatting to HTML". 1
GitHub Flavored Markdown (GFM) is a variant of Markdown based on CommonMark, following its specification apart from some added extensions (e.g.: strikethrough, task lists, tables, alerts,...). It suports HTML, and that's why one can use HTML tags instead of or in addition to Markdown formatting.
Why use Markdown?
Markdown's syntax is easy-to-learn and use, making it very fitting for software documentation due to its portability, flexibility and readability. It produces clear and consistent text.
How to use Markdown?
Just write your documentation content using (GitHub Flavored) Markdown syntax and conventions, as shown below.
Headings are used to name documents or sections within documents. They define importance, from the most important
# Heading 1to the least important###### Heading 6. In defining sections, they are also useful when one wants to link content to a certain section. See Links.
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6Here is how they are displayed:
To create a paragraph, add a blank line in-between two or more lines of text.
Line 1
Line 2Here is how they are displayed:
Line 1
Line 2
Italic, Bold and Strikethrough can be used to add emphasis.
_italic_
**bold**
~~strikethrough~~
**_all in italics and bold_**
_all in italics and **nested bold**_
**all in bold and _nested italics_**Here is how they are displayed:
italic
bold
strikethrough
all in italics and bold
all in italics and nested bold
all in bold and nested italics
Hyperlinks are used as a way to navigate online content, pointing to a specific location. In the present context, we can use them either to link to different pages, documents, etc., or to sections within our own document.
[text](www.link-address.com)
[text](#name-of-section)
[text](./name-of-file-within-same-repo)Footnotes can be used for additional information or citations. You can check the bottom of this document to see how they are displayed.
Text 1 [^1]
Text 2 [^2]
[^1]: Additional information on subject
[^2]: [Display text](link address to source)Lists can be useful in helping readers skim and scan, presenting a set of items in a clear manner, or outlining steps in a process.
Unordered lists
- 1st element
- 2nd element
- 3rd elementHere is how they are displayed:
- 1st element
- 2nd element
- 3rd element
Ordered lists
1. 1st element
2. 2nd element
3. 3rd elementHere is how they are displayed:
- 1st element
- 2nd element
- 3rd element
Nested and mixed lists
- 1st element
- ...
- ...
- ...
- 2nd element
- ...
- 3rd element
and
- 1st element
1. ...
2. ...
3. ...
- 2nd element
1. ...
- 3rd elementHere is how they are displayed:
- 1st element
- ...
- ...
- ...
- 2nd element
- ...
- 3rd element
and
- 1st element
- ...
- ...
- ...
- 2nd element
- ...
- 3rd element
A task list is a set of tasks presented in separate lines with a clickable checkbox. You can select or deselect the checkboxes to mark the tasks as complete or incomplete.
- [x] Complete task
- [x] Completed subtask
- [ ] To do
- [ ] To doHere is how it is displayed:
- Complete task
- Completed subtask
- To do
- To do
Tables can be used to organize data that can't be adequately described in the text, commonly for being too detailed or extensive. They allow the reader to quickly see the results or patterns.
Column header 1 | Column header 2 | Column header 3
--|--|--
Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3
Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3
Row 3, Col 1 | Row 3, Col 2 | Row 3, Col 3
Row 4, Col 1 | Row 4, Col 2 | ...Here is how they are displayed:
| Column header 1 | Column header 2 | Column header 3 |
|---|---|---|
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |
| Row 3, Col 1 | Row 3, Col 2 | Row 3, Col 3 |
| Row 4, Col 1 | Row 4, Col 2 | ... |
Left, center and right aligned table
Left-aligned header| Center-aligned header | Right-aligned header
:--|:--:|--:
Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3
Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3
Row 3, Col 1 | Row 3, Col 2 | Row 3, Col 3
Row 4, Col 1 | Row 4, Col 2 | ...Here is how they are displayed:
| Left-aligned header | Center-aligned header | Right-aligned header |
|---|---|---|
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |
| Row 3, Col 1 | Row 3, Col 2 | Row 3, Col 3 |
| Row 4, Col 1 | Row 4, Col 2 | ... |
Quoted text is indented, with a different type color.
> 1st level of indentation
>> 2nd level ...
>>> 3rd level ...Here is how they are displayed:
1st level of indentation
2nd level ...
3rd level ...
Alerts are used to highlight important information. Currently, there are three types, as shown below. Beware not to overuse them, as they will loose their intended impact.
>[!NOTE]
>Highlighting information to take into account, even when skimming.
>[!TIP]
>Optional information to help a user be more successful.
>[!IMPORTANT]
>Crucial information for users to succeed.
>[!CAUTION]
>Negative potential consequences of an action.
>[!WARNING]
>Critical content requiring immediate attention.Here is how they are displayed:
You can both quote inline code within two
single backticks, knowing that the text within them won't be formatted; or create code blocks usingtriple backticks. When using the latter, you can also enable syntax highlighting by adding an optionallanguage identifier.
Inline quoted code
inline `#include <stdio.h>`Here is how it is displayed:
inline #include <stdio.h>
Code block
```c
#include <stdio.h>
int main(void)
{
printf("Hello, World!");
return (0);
}
```
Here is how it is displayed:
#include <stdio.h>
int main(void)
{
printf("Hello, World!");
return (0);
}Dividers, also known as Horizontal Rules, can be used to separate sections.
section 1
___
section 2Here is how they are displayed:
section 1
section 2
The use of emojis can help in conveying tone, expressing emotion or sometimes just in breaking monotony. 🥳
:emojicode:
You can add an image either by linking to its source, or by uploading it by dragging and dropping, selecting or pasting it.
Here is how it is displayed:
Superscript and Subscript provide additional options for formatting text.
This is a <sup>superscript</sup> text.
This is a <sub>subscript</sub> text.Here is how it is displayed:
This is a superscript text.
This is a subscript text.
Hotkeys are indicated by the
<kbd>tag.
Example: <kbd>ctrl</kbd> <kbd>alt</kbd> <kbd>del</kbd>.Here is how it is displayed:
Example: ctrl alt del.
The
alignattribute can have one of the following values:left,right,centerandjustify. It can be used with different elements.
<p align="left">Left-aligned paragraph</p>
<div align="center"><h3>Center-aligned heading</h3><p>and paragraph within division (section)</p></div>
<h4 align="right">Right-aligned heading</h4>
<p align="justify"><em>Justified and emphasized text: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</em></p>Here is how it it displayed:
Left-aligned paragraph
Justified and emphasized text: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
By now, it's probably pretty obvious that you can add a toggle section... Default behavior would be toggled, but you can set it to display untoggled by default:
<details open>. Also note that whilehtmltags work well withinMarkdown, the other way around might not be true. So, just usehtml tagswithinhtmlwhenever possible.
<details open>
<summary><h3>Main toggle, that is also a heading</h3></summary>
<details>
<summary>Nested toggle 1</summary>
Content
</details>
<details>
<summary>Nested toggle 2</summary>
Content
</details>
</details>Here is how it is displayed:
Markdown 1.0.1 readme source code accessed 22 Oct. 2023
Wikipedia: Markdown accessed 22 Oct. 2023
How do I use Markdown? accessed 22 Oct. 2023
LinkedIn: What are the benefits and challenges of using Markdown for software documentation? accessed 22 Oct. 2023
Basic writing and formatting syntax accessed 22 Oct. 2023
@mota494's READMESheet accessed 22 Oct. 2023
Markdown guide: basic syntax accessed 22 Oct. 2023
GitHub Docs: About task lists accessed 22 Oct. 2023
[Markdown] An option to highlight a "Note" and "Warning" using blockquote (Beta) #16925 accessed 22 Oct. 2023
Footnotes
-
Markdown 1.0.1 readme source code accessed 22 Oct. 2023 ↩