Skip to content

Commit f47553a

Browse files
Copilothumitosericholscher
authored
Docs: add mystmd to the list of supported doctools (#12608)
- [x] Understand the issue requirements - add mystmd to the list of supported doctools - [x] Review the doctools.rst structure and existing documentation tool pages - [x] Research mystmd tool capabilities (TypeScript/JavaScript, MyST Markdown, HTML output) - [x] Add mystmd entry to doctools.rst list with grid-item-card - [x] Create mystmd.rst documentation page with configuration instructions - [x] Verify documentation builds correctly - [x] Apply review suggestions: - Changed title to "Deploying MyST Markdown on Read the Docs" - Removed unnecessary comment about docs directory in YAML - Removed "Configuring MyST Markdown and Read the Docs Addons" section (no longer needed per jupyter-book/mystmd#2178) - Use 2-space indentation in YAML configuration block ## Summary This PR adds MyST Markdown (`mystmd`) to the supported documentation tools list at https://docs.readthedocs.com/platform/latest/intro/doctools.html with a dedicated configuration page. ### Files changed: 1. **docs/user/intro/doctools.rst** - Added grid-item-card for MyST Markdown (supports `md`, `ipynb`; written in JavaScript) 2. **docs/user/intro/mystmd.rst** - New documentation page with minimal configuration example Example repo: https://github.com/readthedocs/test-builds/tree/mystmd Demo: https://test-builds.readthedocs.io/en/mystmd/ <!-- START COPILOT CODING AGENT SUFFIX --> <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>Docs: add `mystmd` to the list of supported doctools</issue_title> > <issue_description>Expand https://docs.readthedocs.com/platform/latest/intro/doctools.html with `mystmd`. Mention what are the suggested configuration (option at framework level or using a redirect: #12323) > > > * https://mystmd.org/</issue_description> > > <agent_instructions>Use readthedocs/addons#654 for reference since it's a similar task for another documentation tool</agent_instructions> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > <comment_new><author>@humitos</author><body> > Yes, together with the page that explains how to configure mystmd on Read the Docs.</body></comment_new> > </comments> > </details> - Fixes #12344 <!-- START COPILOT CODING AGENT TIPS --> --- 💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey). --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: humitos <244656+humitos@users.noreply.github.com> Co-authored-by: Manuel Kaufmann <humitos@gmail.com> Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>
1 parent 08e8366 commit f47553a

File tree

2 files changed

+70
-0
lines changed

2 files changed

+70
-0
lines changed

‎docs/user/intro/doctools.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,17 @@ Below is a list of popular documentation tools that you can use to write your do
8686
Written in
8787
:bdg-info:`javascript`
8888

89+
.. grid-item-card:: MyST Markdown
90+
:link: mystmd.html
91+
92+
MyST Markdown is a powerful authoring framework for scientific communication including blogs, books, papers, and articles.
93+
94+
Supported formats
95+
:bdg-success:`md` :bdg-success:`ipynb`
96+
97+
Written in
98+
:bdg-info:`javascript`
99+
89100
.. toctree::
90101
:hidden:
91102

@@ -96,3 +107,4 @@ Below is a list of popular documentation tools that you can use to write your do
96107
/intro/mdbook
97108
/intro/vitepress
98109
/intro/antora
110+
/intro/mystmd

‎docs/user/intro/mystmd.rst‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
Deploying MyST Markdown on Read the Docs
2+
========================================
3+
4+
.. meta::
5+
:description lang=en: Learn how to host MyST Markdown documentation on Read the Docs.
6+
7+
`MyST Markdown`_ is a set of open-source, community-driven tools designed for scientific communication,
8+
including a powerful authoring framework that supports blogs, online books, scientific papers, reports and journal articles.
9+
10+
Minimal configuration is required to build an existing MyST Markdown project on Read the Docs.
11+
12+
.. code-block:: yaml
13+
:caption: .readthedocs.yaml
14+
15+
version: 2
16+
17+
build:
18+
os: ubuntu-lts-latest
19+
tools:
20+
nodejs: "latest"
21+
jobs:
22+
install:
23+
# Install mystmd dependencies
24+
- npm install -g mystmd
25+
build:
26+
html:
27+
# Build the site
28+
- cd docs/ && myst build --html
29+
post_build:
30+
# Copy generated files into Read the Docs directory
31+
- mkdir --parents $READTHEDOCS_OUTPUT/html/
32+
- cp --recursive docs/_build/html/* $READTHEDOCS_OUTPUT/html/
33+
34+
.. _MyST Markdown: https://mystmd.org/
35+
36+
Getting started
37+
---------------
38+
39+
- If you have an existing MyST Markdown project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide.
40+
- If you're new to MyST Markdown, check out the official `MyST quickstart guide`_.
41+
42+
.. _MyST quickstart guide: https://mystmd.org/guide/quickstart
43+
44+
Example repository and demo
45+
---------------------------
46+
47+
Example repository
48+
https://github.com/readthedocs/test-builds/tree/mystmd
49+
50+
Demo
51+
https://test-builds.readthedocs.io/en/mystmd/
52+
53+
Further reading
54+
---------------
55+
56+
* `MyST Markdown documentation`_
57+
58+
.. _MyST Markdown documentation: https://mystmd.org/guide

0 commit comments

Comments
 (0)