Land major header/indent rst to md changes

[mvorisek]

for #381, land these changes in separate commit for better git tracking