Repository navigation
Migrate all ReST files to Markdown formats #168
Description
Sphinx has supported both ReST and Markdown formats for a long time. Apparently, ReST is much complex than Markdown. It would be easier for us to update and maintain the website if we convert .rst files to .md files.
Activity
anbj commentedon Aug 3, 2026
Do you know of an automated way of doing this?
I guess you could argue that this be done for the GMT docs as well.
joa-quim commentedon Aug 3, 2026
I hear that Markdown is also more limited than RsT. Does it worth the risk?
seisman commentedon Aug 4, 2026
MyST markdown is almost as powerful as ReST. It even can use raw ReST directives. See https://mystmd.org/ for more information.
Actually the GMT Chinese documentation has migrated most its content (except the manpages for GMT modules) from ReST to Markdown (see PR gmt-china/GMT_docs#1346, but the PR comments were written in Chinese)
anbj commentedon Aug 4, 2026
Did you convert from ReST to MyST by hand?
seisman commentedon Aug 4, 2026
We used the rst2myst tool (https://github.com/executablebooks/rst-to-myst). It usually works well but is not ideal, so manual fixes are needed. Please see our experience at gmt-china/GMT_docs#1344 (comment) (again in Chinese )
anbj commentedon Aug 4, 2026
Thanks!
Esteban82 commentedon Aug 26, 2026
I trust your word that it's worth doing.