Fix documentation formatting issues

[eddybl]

The most important two fixes:

1. Fix broken table of contents. While it worked while looking at the MD file in github, most links did not work on the github.io page
2. Fix user callable functions. It seemed like quite a few functions were not properly separated by line breaks

Minor fixes which my MD linting tool complained about:

1. Reduced the amount of trailing white-spaces
2. Reduced the amount of double blank lines (which are not rendered anyway)