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.