how can I add a custom markdown document written myself to a sphinx documentation
- User
how can I add a custom markdown document written myself to a sphinx documentation
- Assistant
To add a custom Markdown document that you've written yourself to your Sphinx documentation, follow these steps:
✅ Steps to Add a Custom Markdown File to Sphinx Documentation
1. Ensure MyST Parser is Installed
Sphinx does not support Markdown by default. You need the MyST parser, which allows Markdown in Sphinx projects.
Install it via pip:
pip install myst-parser
2. Configure
conf.pyto Use MySTIn your
conf.py(found in your Sphinx documentation root, usuallydocs/conf.py), add'myst_parser'to theextensionslist:extensions = [ 'myst_parser', # other extensions... ]
3. Place Your Markdown File in the Project
Place your custom markdown file (e.g.,
yourpage.md) in your documentation source folder (oftendocs/).Example:
project/ ├── docs/ │ ├── index.rst │ ├── yourpage.md ← Add it here │ └── conf.py
4. Reference the Markdown File in
index.rstTo include the Markdown document in your table of contents or make it part of the nav, link it in
index.rst(or wherever your TOC is):.. toctree:: :maxdepth: 2 :caption: Contents: yourpage # No .md extension needed✅ If using reStructuredText in
index.rst, just include the file name without the.md.
5. Build the Documentation
Now build the documentation:
sphinx-build -b html ./docs ./docs/_build/htmlOr if using
make:make htmlGo to
_build/html/index.htmlin your browser to see the result.
✅ Bonus: Use Markdown as Root
index.md(Optional)If you prefer using Markdown for the main page too, you can rename your
index.rsttoindex.mdand write it in Markdown. MyST parser supports this fully. Update your Sphinx config accordingly if necessary.
📝 Example
Given:
docs/index.rstdocs/custom_page.md
Contents of
custom_page.md:# Custom Page Title This is *my* custom page written in **Markdown**.Contents of
index.rst:Welcome to My Project ===================== .. toctree:: :maxdepth: 1 :caption: Contents: custom_pageAfter building,
custom_page.mdwill show up as a page in your documentation.
Let me know if you're using ReadTheDocs, want to include it in a sidebar/nav, or render it with special styles!
- User
what is the default builtin method to do this in sphinx ?
- Assistant
Great question! By default, Sphinx only supports reStructuredText (
.rst), not Markdown. This means:💡 Out of the box, Sphinx does not support Markdown files.
You must use an extension to handle Markdown content.
✅ So What's the Default Built-in Method?
✔️ The default (built-in) way to include documentation in Sphinx is:
- Writing your documents in
.rst(reStructuredText). - Using a
toctreedirective to link to.rstfiles.
Example:
.. toctree:: :maxdepth: 2 :caption: Table of Contents introduction install usageWhere:
introduction.rst,install.rst, etc. are written in reStructuredText format.
🛑 Therefore:
There is no built-in support for
.mdfiles in Sphinx.To Use Markdown:
You must use the MyST Parser extension, which is now the de facto standard for using Markdown in Sphinx.
✅ Summary
Feature Built-in Sphinx Requires Extension .rstsupport (reStructuredText)✅ Yes ❌ No .mdsupport (Markdown)❌ No ✅ Yes – via myst_parser
If you're looking for a default-only path without installing anything:
👉 Just use.rstfiles in your documentation.If you'd prefer Markdown, then adding
myst_parseris the standard, widely accepted method — and it integrates very cleanly with Sphinx.
Would you like me to help convert your Markdown file to reStructuredText (
.rst) if you want to go the built-in route? - Writing your documents in
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.