My Markdown Style Guide
The laws that govern circumstances are abolished by new circumstances.
—Napoleon Bonaparte
Table of contents
Introduction
I like writing in Markdown. It’s readable, lightweight, and portable. It’s plain text so you don’t need special applications to read or write with it. In this article, I post my guidelines on how I write Markdown files. I follow a certain set of rules so that my files look consistent with one another, and so that GNU Emacs will be able to format it nicely.
Headings
Level 1
Level 1 headings are ideal when used as document titles. They should be used only once and they must be in the first line of a file. It should describe what the file or document is all about. I use the = (equals) symbol to indicate the level 1 heading, instead of the # (hash) symbol. Using = makes it easy to spot the heading, and it distinguishes it from the other markers. I use it as:
How to Fly Like a Lobster
=========================
instead of
# How to Fly Like a Lobster
Level 2
Level 2 headings indicate the top-level sections of a document. They are the primary dividers in a file. Similar to the level 1 heading, I use the - (hyphen) symbol to mark the heading. I use it as:
Preparing Your Pincers
----------------------
instead of
## Preparing Your Pincers
Lower levels
For level 3 and lower headings, I use # with the appropriate number of repetitions to indicate the level.
Level 3:
### Fuel
Level 4:
#### Organic
And, so on.
Spacing
The space between document elements should be consistent to facilitate readability. After a heading, create a blank line:
Yeah, yeah, yeah
================
Some text here
When starting a new level, create two blank lines before it:
Yeah, yeah, yeah
================
Some text here
Preparing Your Pincers
----------------------
Meh
Another good reason for having a blank space after every heading is to make it easy for text editors like GNU Emacs to format the text. The keyboard shortcut M-q, bound by default to fill-paragraph, reformats a text block so that the maximum line width is filled correctly. The command fill-paragraph uses the fill-column variable–bound by default to 70—to reformat a text body.
So, if you have the text:
Preparing Your Pincers
----------------------
Meh meh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh meh
and you press M-q while point (cursor) is somewhere in the last line, it becomes:
Preparing Your Pincers
----------------------
Meh meh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh
mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh meh
Code blocks
When the code or command block occupies one to two lines, indent it with four spaces:
VAR=blahblahblah
function meh () { echo meh }
If there are three or more lines, use a pair of three backticks (```) to delimit the start and end of a code block:
ˋˋˋbash
$ mkdir foo
$ echo foo > foo/foo
$ rm -rf foo
$ date
ˋˋˋBullets
When making lists, I like to use the - (hyphen) character to indicate the first level. Then, I use the + (plus) character to indicate the second level. Finally, for level 3 and lower, I use * (asterisk) character.
- is easier to type on a keyboard than *; it doesn’t require you to press Shift on standard keyboards. Additionally, compared to *, the hyphen has a more consistent glyph across different typefaces.
For example:
- lobsters
+ pincers
+ thorax
- crabs
+ pincers
* laser cannon
* chainsaw
* detachable
- unicorns
Anchors
When the target document format of your Markdown files is HTML, it is a good habit to label your sections properly. For example, this section is written as:
<a name="anchors">Anchors</a>
------------------------------
This makes it easy later on to create a table of contents, like so:
Table of contents
-----------------
- [Anchors](#anchors)
Line width
In the old days, it’s good to wrap your lines at the 70 character line width. Nowadays, a higher limit—made possible by modern graphics system—is more desirable so that we can pack more information in one line.
70 characters:
Meh meh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh
mehmeh meh mehmeh meh meh meh meh mehmeh meh mehmeh meh mehmeh meh meh
100 characters:
Meh meh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh mehmeh meh meh meh meh
mehmeh meh mehmeh meh mehmeh meh meh
This guideline, however, may not apply if you are using the editors of services like GitHub or GitLab, wherein it is usually more convenient to let the UI wrap the text.
Extras
When using GNU Emacs, I use these commands, bound to M-g =, M-g -, and M-g `, respectively, to make it easy for me to insert the delimiters. For example, if I have the following text, where ^ is point:
What Is Out There?
^
then, when I press M-g =, it will become:
What Is Out There?
==================
^
The same apply with level 2 headings. So if I have:
Monsters and angels
^
then, when I press M-g -, it will become:
Monsters and angels
-------------------
^
When I have the following:
Code snippet:
^
then, when I press M-g `, it will become:
Code snippet:
``````
^
Closing remarks
By following these simple guidelines, I create consistency among my Markdown source files. These guidelines serve as my template when creating new documents or modifying existing ones. If you have suggestions and criticisms, send in your pull requests!