News for hackers. Stuff that matters.
Re:ReStructuredText vs. Markdown for technical documentation by linsomniac on Friday February 24, 2017 @01:46PM (#13726398)
I really want to love ReST. Part of that is that I like writing in text but having it look good. Part of it is non-technical; I've known the ReST developer forever. And if you need to do something complex, ReST is definitely the way to go.

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.

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. :-)