From 80103c552f549def31ea01bf55f0df79d7ac9b89 Mon Sep 17 00:00:00 2001
From: Matthias Geier <Matthias.Geier@gmail.com>
Date: Sat, 1 May 2021 16:48:04 +0200
Subject: [PATCH] DOC: Show how to use Markdown source files

---
 doc/{README.md => README} |  2 +-
 doc/a-markdown-file.md    | 43 +++++++++++++++++++++++++++++++++++++++
 doc/conf.py               |  1 +
 doc/custom-formats.pct.py |  3 ++-
 doc/index.rst             |  1 +
 5 files changed, 48 insertions(+), 2 deletions(-)
 rename doc/{README.md => README} (67%)
 create mode 100644 doc/a-markdown-file.md

diff --git a/doc/README.md b/doc/README
similarity index 67%
rename from doc/README.md
rename to doc/README
index 84fc88e0..61d7ff8f 100644
--- a/doc/README.md
+++ b/doc/README
@@ -1,5 +1,5 @@
 This folder contains the source files for the documentation.
-See [CONTRIBUTING](../CONTRIBUTING.rst) for how to create the HTML and LaTeX
+See ../CONTRIBUTING.rst for how to create the HTML and LaTeX
 files from these sources.
 
 The online documentation is available at https://nbsphinx.readthedocs.io/.
diff --git a/doc/a-markdown-file.md b/doc/a-markdown-file.md
new file mode 100644
index 00000000..29124aa5
--- /dev/null
+++ b/doc/a-markdown-file.md
@@ -0,0 +1,43 @@
+# Using Markdown Files
+
+Sphinx on its own doesn't know how to handle Markdown files,
+but there are extensions that enable their usage as Sphinx source files.
+For an example, see the
+[Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/markdown.html).
+
+Alternatively, when using `nbsphinx` it is also possible to use Markdown
+files via [custom notebook formats](custom-formats.ipynb).
+
+You only need to install the [jupytext](https://jupytext.readthedocs.io/)
+package and add a configuration setting to `conf.py`,
+which can be used to select one of
+[several Markdown flavors supported by jupytext](https://jupytext.readthedocs.io/en/latest/formats.html#markdown-formats)
+(here we are using R Markdown):
+
+```python
+nbsphinx_custom_formats = {
+    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
+}
+```
+
+This very page was generated from a Markdown file using these settings.
+
+
+## Links to Notebooks (and Other Sphinx Source Files)
+
+Links to other Sphinx source files can be created like in
+[Markdown cells of notebooks](markdown-cells.ipynb#Links-to-Other-Notebooks).
+
+
+## Math
+
+Math equation can be used just like in
+[Markdown cells of notebooks](markdown-cells.ipynb#Equations).
+
+Inline like this: $\text{e}^{i\pi} = -1$.
+
+Or as a separate block:
+
+\begin{equation*}
+\int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0)
+\end{equation*}
diff --git a/doc/conf.py b/doc/conf.py
index 5865a20c..5c90f813 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -80,6 +80,7 @@
 # Support for notebook formats other than .ipynb
 nbsphinx_custom_formats = {
     '.pct.py': ['jupytext.reads', {'fmt': 'py:percent'}],
+    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
 }
 
 # -- The settings below this line are not specific to nbsphinx ------------
diff --git a/doc/custom-formats.pct.py b/doc/custom-formats.pct.py
index c6885332..edb9c4c4 100644
--- a/doc/custom-formats.pct.py
+++ b/doc/custom-formats.pct.py
@@ -68,7 +68,8 @@
 # .. literalinclude:: conf.py
 #     :language: python
 #     :start-at: nbsphinx_custom_formats
-#     :lines: -3
+#     :lines: -4
+#     :emphasize-lines: 2
 
 # %% [markdown]
 # Another example is [this gallery example page](gallery/due-rst.pct.py).
diff --git a/doc/index.rst b/doc/index.rst
index e1be5477..d6da19d1 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -20,6 +20,7 @@ was generated from Jupyter notebooks.
     subdir/*
     custom-css
     a-normal-rst-file
+    a-markdown-file
     links
     contributing
     version-history