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.

If you are familliar with Python, especially PEP8, you can think of this document as my personal PEP8-for-Markdown.

The guidelines take only original MD into account.

Generic

• Wrap at 75 columns at most (fmt(1) default).

• Wrapping documents to less can be beneficial (e.g. for re-quoting).

• Some lists, code blocks or blockquotes may look better wrapped to less than surrounding paragraphs, i.e. to "make up" for the left indentation. (This is most apparent in case of medium-sized list/block between paragraphs.)

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

• Unless you are pasting output, avoid prompt char ($, %, %) in order to provide code that can be copied. To convey the need of root privilege, mention that in surrounding text or use sudo.

  Note that this does not mean that code should be copied around to a productive environment, but in most cases it's good if reader can try it out the snippet. Know your audience and use your best judgment.