13 ms·
A few years ago I wrote up some notes on the subset of reStructuredText that's worth committing to memory: https://simonwillison.net/2018/Aug/25/restructuredtex
by simonw 2y ago
A few years ago I wrote up some notes on the subset of reStructuredText that's worth committing to memory: https://simonwillison.net/2018/Aug/25/restructuredtext/ https://simonwillison.net/2018/Aug/25/restructuredtext/
I've started using MyST for my more recent projects, which gives me the features I care about from reStructuredText - references and table of contents - but lets me use markdown syntax, which is easier for contributors.
- smore 2y agoGreat points about links, especially external links — it makes a lot more sense in the context of a documentation site where you might have the same external link referenced multiple times in the site, but you only want to have to update it once if it changes. The real gamechanger is for internal links (rST+Sphinx) and the use of the `:ref:` and `:doc:` directives so that you can reference an anchor or a doc link in the same content without having to type the header manually (which will inevitably go stale). https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role https://www.sphinx-doc.org/en/master/usage/referencing.html#... that is one of the things I miss most about writing in rST, for sure.