Re:ReStructuredText vs. Markdown for technical documentation
by timClicks on Friday February 24, 2017 @01:58PM
(#13726541)
If you're writing a book, I would strongly recommend Asciidoc syntax and the Asciidoctor toolchain.
Re:ReStructuredText vs. Markdown for technical documentation
by linsomniac on Friday February 24, 2017 @03:55PM
(#13727803)
Thanks, I'll take a look, even though I have no plans of a book. :-)
If I was writing a technical book, I'd probably use ReST.
But, 99.9% of the time, my needs are much more mundane and fit well within the limitations of Markdown. Usually I can just sit down and write Markdown, sometimes I need to bring up a cheatsheet. When I just need to add some documentation related to my work, Markdown is perfect.
What I'd really like is something where I can write Markdown, but if I run into needing something it can't do then switch over to ReST. Because of the overlap, that seems like it should be doable. I was looking at some static site generators that might do that, but I had limited time to evaluate them and couldn't get my existing ReST documents directly to render there so I had to get back to work.
If anyone has had any success with that, I'd love to hear about it.
Oh, that and a way to see the results without having to render and load the results (which currently involves mercurial, fabric, sphinx, and a browser for me). I don't need WYSIWIG, but a quick render would be nice.