☂️ Migrate RST docs to Markdown - ongoing good first issue
See original GitHub issue☂️ This is an epic / umbrella issue We expect this to be done in multiple PRs as it’s better to change a few pages at a time, please reference this issue in any new PRs
Description
- In early 2021 Wagtail began the move to Markdown documentation instead of RST (ReStructured Text) to make it easier for new developers to get started with the docs.
- Our goal is to migrate all documentation to Markdown (.md) files.
- If you want to contribute to these efforts it is a great way to get started with Wagtail contributions as you get to read the documentation and learn about our PR process.
How to work on this
- First, pick a section you feel you can migrate, see the list below, add a comment to this issue with what area you are keen to work on.
- Be sure to read the latest docs on how to use the markdown syntax - https://docs.wagtail.org/en/latest/contributing/documentation_guidelines.html
- A nice to have, but not required, is to also format the resulting markdown file with prettier, this can be done by commenting out the
.md
temporarily in the.prettierignore
file and also updating the package.json formatting script by adding.md
- then run your formatting on the files changed. Be sure not to commit the changes to the prettier config or package file though. - see the related PRs below for references to how this has been done for some parts of the docs already.
Sections
-
docs/advanced_topics/api
- https://github.com/wagtail/wagtail/pull/8569 -
docs/advanced_topics/customisation
- https://github.com/wagtail/wagtail/pull/8596 -
docs/advanced_topics/images
- https://github.com/wagtail/wagtail/pull/8601 -
docs/advanced_topics
(direct files only) - https://github.com/wagtail/wagtail/pull/8643 -
docs/extending/**
- https://github.com/wagtail/wagtail/pull/8701 -
docs/topics/search
- https://github.com/wagtail/wagtail/pull/8754 -
docs/topics
(direct files only) - https://github.com/wagtail/wagtail/pull/8721 -
docs/reference/contrib/modeladmin
https://github.com/wagtail/wagtail/pull/8443 -
docs/reference/streamfield
- https://github.com/wagtail/wagtail/pull/8444 -
docs/reference/contrib/**
(files within reference/contrib folder) https://github.com/wagtail/wagtail/pull/8568 -
docs/support
(single page) https://github.com/wagtail/wagtail/pull/8756 -
docs/releases/upgrading
(single page) https://github.com/wagtail/wagtail/pull/8769 -
docs/reference
(direct files only) - https://github.com/wagtail/wagtail/pull/8759 -
docs/contributing
- https://github.com/wagtail/wagtail/pull/8784 -
docs/reference/pages
- https://github.com/wagtail/wagtail/pull/8881 -
docs/reference/contrib
- https://github.com/wagtail/wagtail/pull/8779
Previous PRs
Issue Analytics
- State:
- Created a year ago
- Comments:25 (25 by maintainers)
Top Results From Across the Web
How to migrate from reStructuredText to MyST Markdown
In this guide, you will find how you can start writing Markdown in your existing reStructuredText project, or migrate it completely.
Read more >Document Your Scientific Project With Markdown, Sphinx, and ...
MyST vs reStructuredText (5 minutes) Differences between the two markup languages, current status of the ecosystem, pros and cons. -3. Write ...
Read more >reStructuredText vs Markdown for documentation
In this post I am going to share my experience of using Markdown and reStructuredText (RST) for technical documentation.
Read more >PyScaffold Documentation - Read the Docs
PyScaffold is a project generator for bootstrapping high-quality Python packages, ready to be shared on PyPI and installable via pip.
Read more >How to programmatically enforcing a pandoc markdown style
I want to incorporate the said trick as a cleanup tool to normalize the source code (in pandoc markdown with minimal raw LaTeX)....
Read more >Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start FreeTop Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
Top GitHub Comments
As of Wagtail 4.0 - all core documentation will be in markdown and not RST - finishing off a ~18 month migration to markdown.
Thanks to everyone who took time to contribute to this, it will now be much easier for new contributors to be able to update the documentation.
Go for it.