1# Using Markdown Files
2
3Sphinx on its own doesn't know how to handle Markdown files,
4but there are extensions that enable their usage as Sphinx source files.
5For an example, see the
6[Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/markdown.html).
7
8Alternatively, when using `nbsphinx` it is also possible to use Markdown
9files via [custom notebook formats](custom-formats.pct.py).
10
11You only need to install the [jupytext](https://jupytext.readthedocs.io/)
12package and add a configuration setting to `conf.py`,
13which can be used to select one of
14[several Markdown flavors supported by jupytext](https://jupytext.readthedocs.io/en/latest/formats.html#markdown-formats)
15(here we are using R Markdown):
16
17```python
18nbsphinx_custom_formats = {
19    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
20}
21```
22
23This very page was generated from a Markdown file using these settings.
24
25
26## Links to Notebooks (and Other Sphinx Source Files)
27
28Links to other Sphinx source files can be created like in
29[Markdown cells of notebooks](markdown-cells.ipynb#Links-to-Other-Notebooks).
30
31
32## Math
33
34Mathematical equations can be used just like in
35[Markdown cells of notebooks](markdown-cells.ipynb#Equations).
36
37Inline like this: $\text{e}^{i\pi} = -1$.
38
39Or as a separate block:
40
41\begin{equation*}
42\int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0)
43\end{equation*}
44
45
46## Tables
47
48A     | B     | A and B
49------|-------|--------
50False | False | False
51True  | False | False
52False | True  | False
53True  | True  | True
54
55
56## Images
57
58![Jupyter notebook icon](images/notebook_icon.png)
59