Refactoring rst for better html generation with pandoc

@stuartw Can you please take a look?