reStructuredText (RST) and Markdown (MyST) pros & cons

Features

• Built in support for extensibility

• Supports re-usable content

• Automatic generation and updating of table of contents

• Supports advanced tables

• Supports diagrams via Graphviz

• Requires custom parsers to support extensibility, but offers a large library of flavors and custom parsers

• No out-of-the-box support for re-usable content

• Supports simple tables

• Supported by GitHub pages

Syntax and complexity

• Complex syntax that can be hard to read

• Previewing requires extra setup in VS Code

• Official documentation of how to use RST formatting and syntax is very limited

• More widely supported than RST

• Third-party extensions, if required for extra features, poses a risk if they are abandoned in the future

• Harder to maintain large projects as re-usable content is not supported

• Easy to onboard or hand-over to other developers as most developers know markdown

Maintainability

• Re-usable content makes it easy to maintain and update several pages at once

• Less need for third-party extensions reduces risk of incompatibility due to abandoned extensions

• Supports directives and roles

• More widely supported than RST

• Third-party extensions, if required for extra features, poses a risk if they are abandoned in the future

• Harder to maintain large projects as re-usable content is not supported

• Easy to onboard or hand-over to other developers as most developers know markdown

Community support

• Small community

• Small community means issues are solved slower and new features takes longer to be tested and implemented

• Large community

• Due to large community, issues are solved quickly