Investigate and implement using `.md` files in docs

[andrewtavis]

Terms

• I have searched open and closed feature requests
• I agree to follow activist's Code of Conduct

Description

i18n-check has Sphynx based docs for readthedocs that are in the /docs directory. As of now we're doing a conversion of the .md docs files like the contributing guide and the changelog via the Gemini, which is not the best as it's error prone and manual. It'd be great if we could learn how to use the markdown files in the docs directly :)

Contribution

Happy to support with this as needed and review a PR! 😊

[andrewtavis]

CC @kmje405 as I brought this up in your PR :) Ideas on this from you would be welcome! Assigning @j-kendrick0 and I as we'd discussed this before 😊

[passionworkeer]

Great idea! For using .md in Sphinx: 1) Install myst-parser (pip install myst-parser), 2) Add extensions = ['myst_parser'] to conf.py, 3) Rename .md to .md.txt or configure source_suffix = {'.rst': 'restructuredtext', '.md': 'markdown'}. MyST also supports direct markdown features like tables, footnotes, and directives. This approach is more reliable than Gemini conversion!

[andrewtavis]

Closed by 644d13d 😊 Realized that another project of mine was using .md files in Sphynx docs, @j-kendrick0 :) Needed to adjust a little bit, with one stylistic change being that we did need to adopt only one H1 in the contributing guide so that the links in the docs would be rendered appropriately in the index.

Thanks again for all your help in the docs! Really has been helpful! 🙏