Markdown with Sphinx#

Markdown and reStructuredText can be used in the same Sphinx project.

If you haven’t done so you’ll first need to install myst_parser and add it to your extensions in your conf.py

conda install -c conda-forge myst-parser

pip install myst_parser

Then in your conf.py:

extensions = ['myst_parser']

Warning

Markdown doesn’t support a lot of the features of Sphinx, like inline markup and directives. However, it works for basic prose content. reStructuredText is the preferred format for technical documentation, please read this blog post for motivation.

Add a Markdown page to toctree#

In the source/ folder make a file call mymarkdown.md

touch mymarkdown.md

Open mymarkdown.md and add a header and some other content

This code came from https://markdown-it.github.io/

# Example Markdown

## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading


## Horizontal Rules

___

---

***


## Typographic replacements

Enable typographer option to see result.

(c) (C) (r) (R) (tm) (TM) (p) (P) +-

test.. test... test..... test?..... test!....

!!!!!! ???? ,,  -- ---

"Smartypants, double quotes" and 'single quotes'


## Emphasis

**This is bold text**

__This is bold text__

*This is italic text*

_This is italic text_

~~Strikethrough~~


## Blockquotes


> Blockquotes can also be nested...
>> ...by using additional greater-than signs right next to each other...
> > > ...or with spaces between arrows.


## Lists

Unordered

+ Create a list by starting a line with `+`, `-`, or `*`
+ Sub-lists are made by indenting 2 spaces:
- Marker character change forces new list start:
    * Ac tristique libero volutpat at
    + Facilisis in pretium nisl aliquet
    - Nulla volutpat aliquam velit
+ Very easy!

Ordered

1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
3. Integer molestie lorem at massa


1. You can use sequential numbers...
1. ...or keep all the numbers as `1.`

Start numbering with offset:

57. foo
1. bar


## Code

Inline `code`

Indented code

    // Some comments
    line 1 of code
    line 2 of code
    line 3 of code


Block code "fences"

```
Sample text here...
```

Syntax highlighting

``` js
var foo = function (bar) {
return bar++;
};

console.log(foo(5));
```

Head over to your index.rst and add mymarkdown to the toctree.

.. WFRT-DEMO documentation master file, created by
sphinx-quickstart on Wed Sep 16 13:47:52 2020.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to WFRT-DEMO's documentation!
=====================================

.. toctree::
:maxdepth: 2
:caption: Contents:

   api
   mymarkdown

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Lets rebuild our webiste

make clean
make html

Push this work to GitHub and see the new markdown page.

git add .
git commit -m "added mymarkdown to docs"
git push