html: fix invalid html / mako structure

Fix bad nesting of tags and mako conditional and drop superfluous '}' outside
the mako block.

docs: rework stuff

The existing docs were far from how we wanted it to be. There was so much to do
and it is not feasible to do that cleanup it in clean patches.

Instead, I took a sweep through the docs and changed what I thought could
benefit from a change: structure, examples, advices, language, markup, content,
etc.

updated CONTRIBUTORS
- code garden