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.

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