You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository has been archived by the owner on Sep 14, 2019. It is now read-only.
Currently the README is in reStructuredText, which has some disadvantages:
It's unintuitive compared to Markdown, especially for newcomers. (I haven't used it in a long time, and I'm having a difficult time making changes to it, especially given that I have no way to live-preview my changes on my local system.)
It's not possible to easily copy content to/from other Markdown content--e.g. other project READMEs, or instructions.md, or GitHub comments.
The only potential advantage I see in using RST is that it'll be easy to migrate our documentation to Sphinx, but I don't see that happening anytime soon...
The text was updated successfully, but these errors were encountered:
I recently did a little survey of how many 18F repos had README.md vs. README.rst, and Markdown won by a million miles, so I must conclude a little sadly that Markdown in 18F's standard.
Ok! Don't get me wrong, I actually really like rst for Sphinx because it's a lot more powerful in that context... I'm just not a huge fan of it for READMEs, whose formatting needs are typically pretty simple...
Since I proposed this, I'm happy to take on this work myself, unless you really want to!
Currently the README is in reStructuredText, which has some disadvantages:
instructions.md
, or GitHub comments.The only potential advantage I see in using RST is that it'll be easy to migrate our documentation to Sphinx, but I don't see that happening anytime soon...
The text was updated successfully, but these errors were encountered: