I get why Markdown won over Restructured Text, but damn if I’m not gonna be sad about it. Writing rST is so much better for complex, in-depth documentation.
To me, the problem is that you now have to use two syntaxes. Anyone who wants to contribute to your docs has to be told - “Markdown, but don’t forget all the Restructuredtext syntax and directives as well.” Isn’t this admitting that restructuredtext is better for your needs? And isn’t there a logical course of action in that case?
Sphinx is very widely used and readthedocs is brilliant. I don’t think it is going away anytime soon, we don’t have to worry about Markdown having “won”, since in some domains it clearly hasn’t. There is room for more than one markup language just like there is room for more than one programming language.
For me it’s like… I think that Markdown syntax is “better” than ReST, but it lacks the extensibility. So “ReST-flavored Markdown” is more interesting to me than “ReST”.
This is all a bit relative though, and if you are working on (for example) a general documentation thing with collaborators, just using ReST seems better
I get why Markdown won over Restructured Text, but damn if I’m not gonna be sad about it. Writing rST is so much better for complex, in-depth documentation.
as I understand it, asciidoc is basically a superset of markdown, and it allows a lot of the same stuff that rST does.
I’m sad that Markdown won out over Asciidoc, too.
To me, the problem is that you now have to use two syntaxes. Anyone who wants to contribute to your docs has to be told - “Markdown, but don’t forget all the Restructuredtext syntax and directives as well.” Isn’t this admitting that restructuredtext is better for your needs? And isn’t there a logical course of action in that case?
Sphinx is very widely used and readthedocs is brilliant. I don’t think it is going away anytime soon, we don’t have to worry about Markdown having “won”, since in some domains it clearly hasn’t. There is room for more than one markup language just like there is room for more than one programming language.
For me it’s like… I think that Markdown syntax is “better” than ReST, but it lacks the extensibility. So “ReST-flavored Markdown” is more interesting to me than “ReST”.
This is all a bit relative though, and if you are working on (for example) a general documentation thing with collaborators, just using ReST seems better