Markdown is very flexible. To ensure this flexibility does not help create inconsistencies, I try to adhere to following guidelines. These are not meant as strict rules, but rather set of hints, and reminders for myself next time I forget how do I do spacing etc.
The guidelines take only original MD into account.
Wrap at 75 columns at most (fmt(1) default). Wrapping to less can be beneficial (e.g. for re-quoting or in block comments) but less than 61 is not considered sane.
Try to have 2 spaces after sentence.
Avoid huge paragraphs.
Avoid tiny paragraphs (except as a means of emphasis)
Avoid "strong" like the plague (rule of thumb: max. once per page).
Use ===
, ---
, ###
, ####
for H1, H2, H3...
For #-based headings, append hashes also after the heading text
(e.g. ### Foo ###
, not ### Foo
)
Have 2 empty lines before each heading, 1 empty line after
In longer step-by-step howtos, consider using numbered headings instead of lists.
Make sure to have empty line before and after.
Except for very simple lists where all items are just few words, add one empty line between items.
Align 2nd line and the rest to 4 spaces, (i.e. the previous alignment plus 4 spaces).
For unordered lists, use asterisk, at least for the first level.
Optimal spacing is 1 space, asterisk, 2 spaces, e.g. * foo
.
For ordered lists, optimal spacing is one or zero spaces in front
of the number, then one space, e.g. 9. Foo
, then 10. Bar
.
For IT-related texts, variable names, underscores, tool names,
filenames are considered as "jargon", which falls into the typical
case for emphasized text. Therefore, use *myvar*
or *mytool*
.
However, if the text is (or should be, by author's opinion) represented as code, backticks may be better choice.
Use reference-style, i.e. [link text][1]
and then, after paragraph
(or later if that makes sense), use [1]: http://www.foo.../
.
Note that you don't need to use numbers: keyword is OK (even spaced), but keep it consistent within the document.
You can also use [link][]
; here the keyword = link text (i.e.
[link]: http://whatever
would follow).
Links can be local (although I have only used this in Github).
Remember that you can have code blocks in lists (step-by-step howtos) and even in quotations:
John [said][1]:
> Always call `foo()` before `bar()`:
>
> foo();
> bar();
>
> and *everything* will work.
Try for copy/paste-able code i.e. avoid prompt char ($
, %
, %
)
unless you are pasting output. To convey the need of root privilege,
mention that in surrounding text or use sudo.