mybook/guidelines/markdown.md

Markdown guidelines

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.

Generic

• 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).

Headings

• 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.

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.

Jargon names

• 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.

Links

• 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).

Images

• Needless to say, they make no sense in plain text. Otherwise look at official Markdown specs.

Code

• 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.