I Prefer RST to Markdown
6 days ago
- #markdown
- #documentation
- #rst
- The author prefers reStructured Text (rST) over markdown for writing books, citing its flexibility and extensibility.
- rST is described as a midweight representation of an abstract documentation tree, allowing for more complex document processing compared to markdown's lightweight HTML representation.
- Key advantages of rST include the ability to extend Sphinx with new text objects and transform the document tree before rendering, which is useful for features like cross-referencing and custom directives.
- The author provides a use case from their book 'Logic for Programmers', where they created a custom exercise extension to manage exercises and solutions dynamically based on the compilation target.
- Despite rST's benefits, the author acknowledges that its syntax may be off-putting to some and suggests alternatives like asciidoc, MyST, or Typst for those who prefer different aesthetics.
- The post concludes with a note about the author's upcoming absence and an update about their book 'Logic for Programmers', which covers formal logic applications in software engineering.