Adding upstream version 0.18.1.upstream/0.18.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

26 files changed, 3629 insertions, 0 deletions

diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..22f62c8
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,2 @@
+_build/
+_api/
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..914a4f5
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,27 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# raise warnings to errors
+html-strict:
+	@$(SPHINXBUILD) -b html -nW --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -r $(BUILDDIR)
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
new file mode 100644
index 0000000..f126fba
--- /dev/null
+++ b/docs/_static/custom.css
@@ -0,0 +1,24 @@
+/** Add a counter before subsections **/
+h1 {
+    counter-reset: subsection;
+    text-decoration: underline;
+}
+h2 {
+    counter-reset: subsubsection;
+}
+h2::before {
+    counter-increment: subsection;
+    content: counter(subsection) ". ";
+}
+h3::before {
+    counter-increment: subsubsection;
+    content: counter(subsection) "." counter(subsubsection) ". ";
+}
+
+/** No icon for admonitions with no-icon class */
+.admonition > .admonition-title, div.admonition.no-icon > .admonition-title::before {
+    content: "";
+}
+.admonition > .admonition-title, div.admonition.no-icon > .admonition-title {
+    padding-left: .6rem;
+}
diff --git a/docs/_static/logo-square.svg b/docs/_static/logo-square.svg
new file mode 100644
index 0000000..a283cba
--- /dev/null
+++ b/docs/_static/logo-square.svg
@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 81.78 73.9"><defs><style>.cls-1{fill:#616161;}.cls-2{fill:#f37726;}</style></defs><title>Artboard 4</title><path class="cls-1" d="M14.66,41.7V38.09l4.67-.79V4.44l-4.67-.8V0h12.2L40.3,31.66h.17L53.47,0H66.05V3.64l-4.67.8V37.3l4.67.79V41.7h-15V38.09L56,37.3V7.7l-.15,0L42.3,40.22H38.55l-14-32.49-.14,0,.18,17.43V37.3l5.05.79V41.7Z"/><path class="cls-2" d="M37.88,73.9q0-8.82-10.13-8.82H19.33q-7.83,0-12.53-3.79T0,50.25l4.8-1.63q2.7,8.46,13.78,8.75h9.17q9.63,0,13.13,7.53Q44.3,57.37,54,57.37h8.45q11.76,0,14.55-8.72l4.78,1.6Q79.71,57.61,75,61.33T62.63,65.08H53.88q-10,0-10,8.82"/></svg>
diff --git a/docs/_static/logo-wide.svg b/docs/_static/logo-wide.svg
new file mode 100644
index 0000000..4dbdfef
--- /dev/null
+++ b/docs/_static/logo-wide.svg
@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 215.62 110"><defs><style>.cls-1{fill:#616161;}.cls-2{fill:#f37726;}</style></defs><title>Artboard 1</title><path class="cls-1" d="M27,63.43V59.74l4.78-.83V25.32L27,24.49V20.77H39.47L53.2,53.15h.19l13.3-32.38H79.55v3.72l-4.79.83V58.91l4.79.83v3.69H64.22V59.74l5-.83V28.65l-.14,0L55.26,61.9H51.42L37.09,28.68l-.14,0,.21,17.84V58.91l5.15.83v3.69ZM91.35,76.22a13.26,13.26,0,0,1-1.75-.15c-.72-.11-1.28-.21-1.67-.31l.59-4.54a12.21,12.21,0,0,0,1.36.1c.59,0,1,0,1.22,0a3.69,3.69,0,0,0,3-1.4,15.13,15.13,0,0,0,2.15-3.83l1.38-3.34L86.41,35.91,83,35.44V31.72H96.3v3.72l-3.83.6,6.17,15.84,1.5,4.14h.18l7.32-20-4-.6V31.72h13v3.72l-3.28.47L100.88,68.29a19,19,0,0,1-2.13,4.09,9.13,9.13,0,0,1-3,2.81A8.6,8.6,0,0,1,91.35,76.22ZM135,64a24.79,24.79,0,0,1-7.5-1.14,24.21,24.21,0,0,1-6.87-3.52V50.27h4.48l1,6.7a17,17,0,0,0,4.13,1.83,17.26,17.26,0,0,0,4.81.64,12.24,12.24,0,0,0,5-.89,7.05,7.05,0,0,0,3.11-2.47,6.84,6.84,0,0,0,.16-7.15,7.79,7.79,0,0,0-3.1-2.63,24.72,24.72,0,0,0-5.87-2,27.61,27.61,0,0,1-7.42-2.74,12.83,12.83,0,0,1-4.61-4.15,10.17,10.17,0,0,1-1.57-5.61,10.43,10.43,0,0,1,1.77-6,12.13,12.13,0,0,1,4.94-4.16,16.82,16.82,0,0,1,7.39-1.53,21.34,21.34,0,0,1,7.92,1.36,19.44,19.44,0,0,1,5.67,3.3v8.51h-4.48l-1-6.09a11.47,11.47,0,0,0-3.29-1.75,14.48,14.48,0,0,0-4.86-.7,10.17,10.17,0,0,0-4.33.86,7,7,0,0,0-2.94,2.42,6.34,6.34,0,0,0-1,3.65,5.57,5.57,0,0,0,.95,3.24,7.85,7.85,0,0,0,3.09,2.42,31.77,31.77,0,0,0,5.77,1.94Q143,41,146.44,44.26a10.61,10.61,0,0,1,3.49,8.06,10.35,10.35,0,0,1-1.86,6.09,12.28,12.28,0,0,1-5.21,4.14A19.32,19.32,0,0,1,135,64Zm30.47-.61V59.74l4.79-.83V25.13h-9.68l-.84,5.92h-4.34V20.77h35.45V31.05h-4.28l-.88-5.92H176V58.91l4.78.83v3.69Z"/><path class="cls-2" d="M24,83q-8.25-2.33-11.75-7.4A21.21,21.21,0,0,1,8.8,63.3V54.63q0-4.74-2.16-7.38T0,44.61V38.38q4.49,0,6.64-2.6T8.8,28.39v-8.7a21.14,21.14,0,0,1,3.48-12.3Q15.77,2.34,24,0l1.69,5a10.7,10.7,0,0,0-6.63,5.32,20.45,20.45,0,0,0-2,9.42v8.7a16.58,16.58,0,0,1-1.79,7.84A12.45,12.45,0,0,1,10,41.52a12.5,12.5,0,0,1,5.36,5.34,16.49,16.49,0,0,1,1.79,7.77V63.3a20.15,20.15,0,0,0,2,9.37A10.85,10.85,0,0,0,25.72,78Z"/><path class="cls-2" d="M192,82.46l-1.67-4.93a10.72,10.72,0,0,0,6.45-5.23,19.44,19.44,0,0,0,2-9.22V54.53a15.61,15.61,0,0,1,1.88-7.78,12.22,12.22,0,0,1,5.78-5.14,11.72,11.72,0,0,1-5.78-5,15.83,15.83,0,0,1-1.88-7.87V20.13a19.74,19.74,0,0,0-2-9.27,10.52,10.52,0,0,0-6.45-5.23L192,.75Q200,3,203.48,8a20.81,20.81,0,0,1,3.43,12.11v8.58q0,4.7,2.13,7.26t6.58,2.56v6.13q-4.45,0-6.58,2.61t-2.13,7.26v8.55a20.8,20.8,0,0,1-3.43,12.08Q200,80.16,192,82.46Z"/><path class="cls-1" d="M12.46,105.84l-4.19-11H8.19c.08.88.12,1.91.12,3.1v7.87H7V93.47H9.14l3.92,10.2h.08l3.94-10.2h2.16v12.37H17.8v-8c0-.91,0-1.91.11-3h-.06l-4.24,11Zm15.66,0-.29-1.31h-.06a3.92,3.92,0,0,1-1.39,1.17,4.13,4.13,0,0,1-1.72.32,3.1,3.1,0,0,1-2.15-.71,2.62,2.62,0,0,1-.79-2c0-1.87,1.5-2.86,4.49-3l1.58,0V99.7a2.31,2.31,0,0,0-.47-1.59,1.91,1.91,0,0,0-1.5-.53,6.2,6.2,0,0,0-2.63.7l-.42-1.06a6.86,6.86,0,0,1,3.13-.8,3.57,3.57,0,0,1,2.47.74,3.07,3.07,0,0,1,.79,2.36v6.32Zm-3.18-1a2.87,2.87,0,0,0,2.07-.72,2.66,2.66,0,0,0,.75-2v-.84l-1.41.06a5.25,5.25,0,0,0-2.42.53,1.57,1.57,0,0,0-.74,1.43,1.47,1.47,0,0,0,.46,1.17A2,2,0,0,0,24.94,104.86Zm11.34-8.45a6.08,6.08,0,0,1,1.11.09l-.18,1.31a4.66,4.66,0,0,0-1-.14,2.52,2.52,0,0,0-1.94.92,3.35,3.35,0,0,0-.79,2.28v5H32.05V96.58h1.16l.17,1.7h.06a4.1,4.1,0,0,1,1.23-1.39A2.89,2.89,0,0,1,36.28,96.41Zm4.23,4.68a14.94,14.94,0,0,1,1.11-1.34l3-3.17h1.66l-3.75,3.94,4,5.32h-1.7l-3.26-4.37-1.07.9v3.47H39.12V92.67h1.39v7c0,.31,0,.79-.06,1.43ZM52.14,106a4.29,4.29,0,0,1-3.25-1.25,4.89,4.89,0,0,1-1.19-3.49,5.33,5.33,0,0,1,1.11-3.55,3.68,3.68,0,0,1,3-1.32,3.5,3.5,0,0,1,2.75,1.14,4.37,4.37,0,0,1,1,3v.89H49.16a3.7,3.7,0,0,0,.82,2.47,2.87,2.87,0,0,0,2.21.84,7.64,7.64,0,0,0,3-.62v1.25a7.61,7.61,0,0,1-1.43.46A7.15,7.15,0,0,1,52.14,106Zm-.37-8.44a2.32,2.32,0,0,0-1.8.73,3.34,3.34,0,0,0-.77,2h4.85a3.05,3.05,0,0,0-.6-2A2.07,2.07,0,0,0,51.77,97.58Zm12.48,7h-.08a3.27,3.27,0,0,1-2.9,1.43,3.48,3.48,0,0,1-2.83-1.24,5.46,5.46,0,0,1-1-3.55,5.55,5.55,0,0,1,1-3.56,3.44,3.44,0,0,1,2.83-1.26,3.36,3.36,0,0,1,2.89,1.36h.11l0-.66,0-.66V92.67h1.41v13.17H64.44Zm-2.81.25a2.54,2.54,0,0,0,2.09-.78,4,4,0,0,0,.64-2.53v-.3a4.63,4.63,0,0,0-.65-2.81,2.51,2.51,0,0,0-2.1-.84,2.14,2.14,0,0,0-1.89,1,4.76,4.76,0,0,0-.65,2.7,4.64,4.64,0,0,0,.65,2.69A2.23,2.23,0,0,0,61.44,104.84Zm8.52,1h-1.4V92.67H70Zm1.51-9.26H73l2,5.28a18.81,18.81,0,0,1,.83,2.61h.08q.11-.42.45-1.47t2.3-6.42h1.52l-4,10.54a5.11,5.11,0,0,1-1.39,2.22,2.91,2.91,0,0,1-1.94.66,5.93,5.93,0,0,1-1.26-.14v-1.13a4,4,0,0,0,1,.11,2.13,2.13,0,0,0,2.06-1.62l.52-1.33Zm21.91,6a3.07,3.07,0,0,1-1.19,2.56A5.2,5.2,0,0,1,89,106a8,8,0,0,1-3.39-.57v-1.39a9,9,0,0,0,1.66.5,8.35,8.35,0,0,0,1.78.19,3.46,3.46,0,0,0,2.15-.55,1.78,1.78,0,0,0,.74-1.51,1.86,1.86,0,0,0-.27-1,2.19,2.19,0,0,0-.86-.77,13.3,13.3,0,0,0-1.82-.78,5.73,5.73,0,0,1-2.47-1.47,3.22,3.22,0,0,1-.74-2.2,2.75,2.75,0,0,1,1.07-2.28,4.46,4.46,0,0,1,2.84-.84,8.54,8.54,0,0,1,3.41.67l-.46,1.25a7.62,7.62,0,0,0-3-.64,2.77,2.77,0,0,0-1.78.5,1.59,1.59,0,0,0-.64,1.36,2.13,2.13,0,0,0,.23,1.06,2.25,2.25,0,0,0,.8.75A10.53,10.53,0,0,0,90,99a6.8,6.8,0,0,1,2.68,1.48A3,3,0,0,1,93.38,102.55Zm5.3,2.31a5.55,5.55,0,0,0,.72,0,5.43,5.43,0,0,0,.55-.12v1.08a2.37,2.37,0,0,1-.67.17,4.81,4.81,0,0,1-.8.08c-1.79,0-2.69-1-2.69-2.85V97.66H94.47V97l1.32-.57.6-2h.81v2.16h2.69v1.08H97.2v5.46a1.93,1.93,0,0,0,.39,1.29A1.4,1.4,0,0,0,98.68,104.86ZM106,96.41a6.23,6.23,0,0,1,1.11.09L107,97.81a4.66,4.66,0,0,0-1-.14,2.5,2.5,0,0,0-1.93.92,3.31,3.31,0,0,0-.8,2.28v5H101.8V96.58H103l.17,1.7h.06a4.12,4.12,0,0,1,1.24-1.39A2.87,2.87,0,0,1,106,96.41Zm4.16.17v6a2.44,2.44,0,0,0,.52,1.69,2.06,2.06,0,0,0,1.61.56,2.61,2.61,0,0,0,2.12-.79,4,4,0,0,0,.68-2.61V96.58h1.4v9.26h-1.15l-.21-1.25h-.08a2.79,2.79,0,0,1-1.18,1.07,4.09,4.09,0,0,1-1.75.36,3.55,3.55,0,0,1-2.53-.8,3.41,3.41,0,0,1-.85-2.58V96.58Zm13,9.44a4,4,0,0,1-3.11-1.24,5.09,5.09,0,0,1-1.1-3.51,5.25,5.25,0,0,1,1.12-3.6,4,4,0,0,1,3.19-1.26,6.1,6.1,0,0,1,1.34.14,4,4,0,0,1,1,.34l-.42,1.19a6.2,6.2,0,0,0-1-.31,4.12,4.12,0,0,0-1-.13q-2.84,0-2.83,3.61a4.28,4.28,0,0,0,.69,2.62,2.4,2.4,0,0,0,2,.91,6.24,6.24,0,0,0,2.38-.5v1.25A5.09,5.09,0,0,1,123.21,106Zm7.55-1.16a5.55,5.55,0,0,0,.72,0,5.43,5.43,0,0,0,.55-.12v1.08a2.36,2.36,0,0,1-.68.17,4.7,4.7,0,0,1-.79.08c-1.79,0-2.69-1-2.69-2.85V97.66h-1.33V97l1.33-.57.59-2h.82v2.16H132v1.08h-2.68v5.46a1.93,1.93,0,0,0,.39,1.29A1.39,1.39,0,0,0,130.76,104.86Zm4.45-8.28v6a2.44,2.44,0,0,0,.51,1.69,2.07,2.07,0,0,0,1.61.56,2.64,2.64,0,0,0,2.13-.79,4.09,4.09,0,0,0,.67-2.61V96.58h1.4v9.26h-1.15l-.21-1.25h-.07a2.81,2.81,0,0,1-1.19,1.07,4.05,4.05,0,0,1-1.75.36,3.55,3.55,0,0,1-2.53-.8,3.45,3.45,0,0,1-.85-2.58V96.58Zm13.54-.17a6.23,6.23,0,0,1,1.11.09l-.19,1.31a4.58,4.58,0,0,0-1-.14,2.5,2.5,0,0,0-1.93.92,3.31,3.31,0,0,0-.8,2.28v5h-1.41V96.58h1.16l.17,1.7h.06a4.12,4.12,0,0,1,1.24-1.39A2.87,2.87,0,0,1,148.75,96.41Zm6.76,9.61a4.27,4.27,0,0,1-3.25-1.25,4.89,4.89,0,0,1-1.19-3.49,5.33,5.33,0,0,1,1.11-3.55,3.68,3.68,0,0,1,3-1.32,3.5,3.5,0,0,1,2.75,1.14,4.37,4.37,0,0,1,1,3v.89h-6.39a3.75,3.75,0,0,0,.83,2.47,2.87,2.87,0,0,0,2.21.84,7.59,7.59,0,0,0,3-.62v1.25a7.53,7.53,0,0,1-1.42.46A7.28,7.28,0,0,1,155.51,106Zm-.38-8.44a2.29,2.29,0,0,0-1.79.73,3.27,3.27,0,0,0-.77,2h4.84a3.05,3.05,0,0,0-.59-2A2.08,2.08,0,0,0,155.13,97.58Zm12.49,7h-.08a3.27,3.27,0,0,1-2.9,1.43,3.48,3.48,0,0,1-2.83-1.24,5.46,5.46,0,0,1-1-3.55,5.55,5.55,0,0,1,1-3.56,3.44,3.44,0,0,1,2.83-1.26,3.36,3.36,0,0,1,2.89,1.36h.11l0-.66-.05-.66V92.67H169v13.17h-1.14Zm-2.81.25a2.55,2.55,0,0,0,2.09-.78,4,4,0,0,0,.64-2.53v-.3a4.7,4.7,0,0,0-.65-2.81,2.51,2.51,0,0,0-2.1-.84,2.14,2.14,0,0,0-1.89,1,4.69,4.69,0,0,0-.65,2.7,4.57,4.57,0,0,0,.65,2.69A2.21,2.21,0,0,0,164.81,104.84Zm15.65,1H179V94.75H175.1V93.47h9.27v1.28h-3.91Zm9.48.18a4.27,4.27,0,0,1-3.25-1.25,4.85,4.85,0,0,1-1.19-3.49,5.33,5.33,0,0,1,1.11-3.55,3.68,3.68,0,0,1,3-1.32,3.51,3.51,0,0,1,2.75,1.14,4.42,4.42,0,0,1,1,3v.89H187a3.7,3.7,0,0,0,.83,2.47,2.86,2.86,0,0,0,2.2.84,7.64,7.64,0,0,0,3-.62v1.25a7.53,7.53,0,0,1-1.42.46A7.28,7.28,0,0,1,189.94,106Zm-.38-8.44a2.32,2.32,0,0,0-1.8.73,3.33,3.33,0,0,0-.76,2h4.84a3.11,3.11,0,0,0-.59-2A2.09,2.09,0,0,0,189.56,97.58Zm8.41,3.51-3.22-4.51h1.6l2.45,3.54,2.44-3.54h1.57l-3.21,4.51,3.39,4.75h-1.6l-2.59-3.75-2.63,3.75h-1.59Zm9.84,3.77a5.55,5.55,0,0,0,.72,0,5.43,5.43,0,0,0,.55-.12v1.08a2.37,2.37,0,0,1-.67.17,4.81,4.81,0,0,1-.8.08c-1.79,0-2.69-1-2.69-2.85V97.66H203.6V97l1.32-.57.6-2h.81v2.16H209v1.08h-2.69v5.46a1.93,1.93,0,0,0,.39,1.29A1.4,1.4,0,0,0,207.81,104.86Z"/></svg>
diff --git a/docs/api/reference.rst b/docs/api/reference.rst
new file mode 100644
index 0000000..9ea5898
--- /dev/null
+++ b/docs/api/reference.rst
@@ -0,0 +1,96 @@
+.. _api/main:
+
+==========
+Python API
+==========
+
+Source text parsers
+-------------------
+
+.. _api/docutils_parser:
+
+Docutils
+........
+
+.. autoclass:: myst_parser.docutils_.Parser
+    :members: parse
+    :undoc-members:
+    :member-order: bysource
+    :show-inheritance:
+
+.. _api/sphinx_parser:
+
+Sphinx
+......
+
+.. autoclass:: myst_parser.parsers.sphinx_.MystParser
+    :members: supported, parse
+    :undoc-members:
+    :member-order: bysource
+    :show-inheritance:
+    :exclude-members: __init__
+
+.. _api/renderers:
+
+Markdown-it to docutils
+-----------------------
+
+These renderers take the markdown-it parsed token stream and convert it to
+the docutils AST. The sphinx renderer is a subclass of the docutils one,
+with some additional methods only available *via* sphinx e.g. multi-document cross-referencing.
+
+
+Docutils
+........
+
+.. autoclass:: myst_parser.mdit_to_docutils.base.DocutilsRenderer
+    :special-members: __output__, __init__
+    :members: render, nested_render_text, add_line_and_source_path, current_node_context
+    :undoc-members:
+    :member-order: bysource
+    :show-inheritance:
+
+
+Sphinx
+......
+
+.. autoclass:: myst_parser.mdit_to_docutils.sphinx_.SphinxRenderer
+    :special-members: __output__
+    :members: render_internal_link, render_math_block_label
+    :undoc-members:
+    :member-order: alphabetical
+    :show-inheritance:
+
+.. _api/directive:
+
+Directive and role processing
+-----------------------------
+
+This module processes the content of a directive:
+
+.. automodule:: myst_parser.parsers.directives
+    :members:
+
+These classes are parsed to sphinx roles and directives,
+to mimic the original docutls rST specific parser elements,
+but instead run nested parsing with the markdown parser.
+
+.. autoclass:: myst_parser.mocking.MockInliner
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: myst_parser.mocking.MockState
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: myst_parser.mocking.MockStateMachine
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: myst_parser.mocking.MockIncludeDirective
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..199a32a
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,169 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from datetime import date
+
+from sphinx.application import Sphinx
+
+from myst_parser import __version__
+
+# -- Project information -----------------------------------------------------
+
+project = "MyST Parser"
+copyright = f"{date.today().year}, Executable Book Project"
+author = "Executable Book Project"
+version = __version__
+
+master_doc = "index"
+language = "en"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_design",
+    "sphinxext.rediraffe",
+    "sphinxcontrib.mermaid",
+    "sphinxext.opengraph",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_book_theme"
+html_logo = "_static/logo-wide.svg"
+html_favicon = "_static/logo-square.svg"
+html_title = ""
+html_theme_options = {
+    "home_page_in_toc": True,
+    "github_url": "https://github.com/executablebooks/MyST-Parser",
+    "repository_url": "https://github.com/executablebooks/MyST-Parser",
+    "repository_branch": "master",
+    "path_to_docs": "docs",
+    "use_repository_button": True,
+    "use_edit_page_button": True,
+}
+# OpenGraph metadata
+ogp_site_url = "https://myst-parser.readthedocs.io/en/latest"
+# This is the image that GitHub stores for our social media previews
+ogp_image = "https://repository-images.githubusercontent.com/240151150/316bc480-cc23-11eb-96fc-4ab2f981a65d"  # noqa: E501
+ogp_custom_meta_tags = [
+    '<meta name="twitter:card" content="summary_large_image">',
+]
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "deflist",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "colon_fence",
+    "smartquotes",
+    "replacements",
+    "linkify",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+    "attrs_image",
+]
+myst_number_code_blocks = ["typescript"]
+myst_heading_anchors = 2
+myst_footnote_transition = True
+myst_dmath_double_inline = True
+
+rediraffe_redirects = {
+    "using/intro.md": "sphinx/intro.md",
+    "sphinx/intro.md": "intro.md",
+    "using/use_api.md": "api/index.md",
+    "api/index.md": "api/reference.rst",
+    "using/syntax.md": "syntax/syntax.md",
+    "using/syntax-optional.md": "syntax/optional.md",
+    "using/reference.md": "syntax/reference.md",
+    "sphinx/reference.md": "configuration.md",
+    "sphinx/index.md": "faq/index.md",
+    "sphinx/use.md": "faq/index.md",
+    "sphinx/faq.md": "faq/index.md",
+    "explain/index.md": "develop/background.md",
+}
+
+suppress_warnings = ["myst.strikethrough"]
+
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.7", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+    "markdown_it": ("https://markdown-it-py.readthedocs.io/en/latest", None),
+}
+
+# autodoc_default_options = {
+#     "show-inheritance": True,
+#     "special-members": "__init__, __enter__, __exit__",
+#     "members": True,
+#     # 'exclude-members': '',
+#     "undoc-members": True,
+#     # 'inherited-members': True
+# }
+autodoc_member_order = "bysource"
+nitpicky = True
+nitpick_ignore = [
+    ("py:class", "docutils.nodes.document"),
+    ("py:class", "docutils.nodes.docinfo"),
+    ("py:class", "docutils.nodes.Element"),
+    ("py:class", "docutils.nodes.Node"),
+    ("py:class", "docutils.nodes.field_list"),
+    ("py:class", "docutils.nodes.problematic"),
+    ("py:class", "docutils.nodes.pending"),
+    ("py:class", "docutils.nodes.system_message"),
+    ("py:class", "docutils.statemachine.StringList"),
+    ("py:class", "docutils.parsers.rst.directives.misc.Include"),
+    ("py:class", "docutils.parsers.rst.Parser"),
+    ("py:class", "docutils.utils.Reporter"),
+    ("py:class", "nodes.Element"),
+    ("py:class", "nodes.Node"),
+    ("py:class", "nodes.system_message"),
+    ("py:class", "Directive"),
+    ("py:class", "Include"),
+    ("py:class", "StringList"),
+    ("py:class", "DocutilsRenderer"),
+    ("py:class", "MockStateMachine"),
+]
+
+
+def setup(app: Sphinx):
+    """Add functions to the Sphinx setup."""
+    from myst_parser._docs import (
+        DirectiveDoc,
+        DocutilsCliHelpDirective,
+        MystConfigDirective,
+    )
+
+    app.add_css_file("custom.css")
+    app.add_directive("myst-config", MystConfigDirective)
+    app.add_directive("docutils-cli-help", DocutilsCliHelpDirective)
+    app.add_directive("doc-directive", DirectiveDoc)
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..a87ce0b
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,106 @@
+(sphinx/config-options)=
+# Configuration
+
+MyST parsing can be configured at both the global and individual document level,
+with the most specific configuration taking precedence.
+
+## Global configuration
+
+Overriding the default configuration at the global level is achieved by specifying variables in the Sphinx `conf.py` file.
+All `myst_parser` global configuration variables are prefixed with `myst_`, e.g.
+
+```python
+myst_enable_extensions = ["deflist"]
+```
+
+:::{seealso}
+Configuration in Docutils, in the [](docutils.md) section.
+:::
+
+```{myst-config}
+:sphinx:
+:scope: global
+```
+
+### Extensions
+
+Configuration specific to syntax extensions:
+
+```{myst-config}
+:sphinx:
+:extensions:
+:scope: global
+```
+
+## Local configuration
+
+```{versionadded} 0.18
+```
+
+The following configuration variables are available at the document level.
+These can be set in the document [front matter](syntax/frontmatter), under the `myst` key, e.g.
+
+```yaml
+---
+myst:
+  enable_extensions: ["deflist"]
+---
+```
+
+```{myst-config}
+:sphinx:
+:scope: local
+```
+
+### Extensions
+
+Configuration specific to syntax extensions:
+
+```{myst-config}
+:sphinx:
+:extensions:
+:scope: local
+```
+
+## List of syntax extensions
+
+Full details in the [](syntax/extensions) section.
+
+amsmath
+: enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations
+
+colon_fence
+: Enable code fences using `:::` delimiters, [see here](syntax/colon_fence) for details
+
+deflist
+: Enable definition lists, [see here](syntax/definition-lists) for details
+
+dollarmath
+: Enable parsing of dollar `$` and `$$` encapsulated math
+
+fieldlist
+: Enable field lists, [see here](syntax/fieldlists) for details
+
+html_admonition
+: Convert `<div class="admonition">` elements to sphinx admonition nodes, see the [HTML admonition syntax](syntax/html-admonition) for details
+
+html_image
+: Convert HTML `<img>` elements to sphinx image nodes, [see here](syntax/images) for details
+
+linkify
+: Automatically identify "bare" web URLs and add hyperlinks
+
+replacements
+: Automatically convert some common typographic texts
+
+smartquotes
+: Automatically convert standard quotations to their opening/closing variants
+
+strikethrough
+: Enable strikethrough syntax, [see here](syntax/strikethrough) for details
+
+substitution
+: Substitute keys, [see here](syntax/substitutions) for details
+
+tasklist
+: Add check-boxes to the start of list items, [see here](syntax/tasklists) for details
diff --git a/docs/develop/_changelog.md b/docs/develop/_changelog.md
new file mode 100644
index 0000000..d24e7ac
--- /dev/null
+++ b/docs/develop/_changelog.md
@@ -0,0 +1,4 @@
+```{include} ../../CHANGELOG.md
+:relative-docs: docs/
+:relative-images:
+```
diff --git a/docs/develop/architecture.md b/docs/develop/architecture.md
new file mode 100644
index 0000000..f00cdae
--- /dev/null
+++ b/docs/develop/architecture.md
@@ -0,0 +1,27 @@
+# The MyST implementation architecture
+
+This page describes implementation details to help you understand the structure
+of the project.
+
+## A Renderer for markdown-it tokens
+
+At a high level, the MyST parser is an extension of th project. Markdown-It-Py
+is a well-structured Python parser for CommonMark text. It also defines an extension
+point to include more syntax in parsed files. The MyST parser uses this extension
+point to define its own syntax options (e.g., for Sphinx roles and directives).
+
+The result of this parser is a markdown-it token stream.
+
+## A docutils renderer
+
+The MyST parser also defines a docutils renderer for the markdown-it token stream.
+This allows us to convert parsed elements of a MyST markdown file into docutils.
+
+## A Sphinx parser
+
+Finally, the MyST parser provides a parser for Sphinx, the documentation generation
+system. This parser does the following:
+
+* Parse markdown files with the markdown-it parser, including MyST specific plugins
+* Convert these files into docutils objects using the MyST docutils renderer
+* Provide these to Sphinx in order to use in building your site.
diff --git a/docs/develop/background.md b/docs/develop/background.md
new file mode 100644
index 0000000..4be19e0
--- /dev/null
+++ b/docs/develop/background.md
@@ -0,0 +1,82 @@
+# Background
+
+These sections discuss high-level questions about the MyST ecosystem, and explain a few decisions made in the project.
+
+## Why did we create MyST markdown?
+
+While markdown is ubiquitous, it is not powerful enough for writing modern,
+fully-featured documentation. Some flavors of markdown support features needed for this,
+but there is no community standard around various syntactic choices for these features.
+
+Sphinx is a documentation generation framework written in Python. It heavily-utilizes
+reStructuredText syntax, which is another markup language for writing documents. In
+particular, Sphinx defines two extension points that are extremely useful:
+**{ref}`in-line roles<sphinx:rst-roles-alt>`** and **{ref}`block-level directives <sphinx:rst-directives>`**.
+
+**This project is an attempt at combining the simplicity and readability of Markdown
+with the power and flexibility of reStructuredText and the Sphinx platform.** It
+starts with the [CommonMark markdown specification][commonmark], and selectively adds a few extra
+syntax pieces to utilize the most powerful parts of reStructuredText.
+
+```{note}
+The CommonMark community has been discussing an "official" extension syntax for many
+years now (for example, see
+[this seven-year-old thread about directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) as well as
+[this more recent converstaion](https://talk.commonmark.org/t/support-for-extension-token/2771),
+and [this comment listing several more threads on this topic](https://talk.commonmark.org/t/extension-terminology-and-rules/1233)).
+
+We have chosen a "roles and directives" syntax that seems reasonable and follows other
+common conventions in Markdown flavors. However, if the CommonMark community ever
+decides on an "official" extension syntax, we will likely utilize this syntax for
+MyST.
+```
+
+## The relationship between MyST, reStructuredText, and Sphinx
+
+MyST markdown provides a markdown equivalent of the reStructuredText syntax,
+meaning that you can do anything in MyST that you can do with reStructuredText.
+
+The Sphinx documentation engine supports a number of different input types. By default,
+Sphinx reads **reStructuredText** (`.rst`) files. Sphinx uses a **parser** to parse input files
+into its own internal document model (which is provided by a core Python project,
+[docutils](https://docutils.sourceforge.io/)).
+
+Developers can *extend Sphinx* to support other kinds of input files. Any content file
+can be read into the Sphinx document structure, provided that somebody writes a
+**parser** for that file. Once a content file has been parsed into Sphinx, it behaves
+nearly the same way as any other content file, regardless of the language in which it
+was written.
+
+The MyST-parser is a Sphinx parser for the MyST markdown language.
+When you use it, Sphinx will know how to parse content files that contain MyST markdown (by default, Sphinx will assume any files ending in `.md` are written in MyST markdown). Once a document has been parsed into Sphinx, it behaves the same way regardless of whether it has been written in rST or MyST markdown.
+
+```
+myst markdown (.md) ------> myst parser ---+
+                                           |
+                                           +-->Sphinx document (docutils)
+                                           |
+reStructuredText (.rst) --> rst parser ----+
+```
+
+For example, here's how you'd write a `toctree` directive in MyST markdown:
+
+````
+```{toctree}
+My page name <page1>
+page2
+```
+````
+
+and here's the same in rST:
+
+```
+.. toctree::
+
+   My page name <page1>
+   page2
+```
+
+They will both behave the same in Sphinx.
+
+
+[commonmark]: https://commonmark.org/
diff --git a/docs/develop/contributing.md b/docs/develop/contributing.md
new file mode 100644
index 0000000..7f57052
--- /dev/null
+++ b/docs/develop/contributing.md
@@ -0,0 +1,85 @@
+# Contributing
+
+[![Github-CI][github-ci]][github-link]
+[![Coverage Status][codecov-badge]][codecov-link]
+[![Documentation Status][rtd-badge]][rtd-link]
+[![Code style: black][black-badge]][black-link]
+
+We welcome all contributions!
+See the [EBP Contributing Guide](https://executablebooks.org/en/latest/contributing.html) for general details, and below for guidance specific to MyST-Parser.
+
+## Install for development
+
+To install `myst-parser` for development, take the following steps:
+
+```bash
+git clone https://github.com/executablebooks/MyST-Parser
+cd MyST-Parser
+git checkout master
+pip install -e .[code_style,testing,rtd]
+```
+
+## Code Style
+
+Code style is tested using [flake8](http://flake8.pycqa.org),
+with the configuration set in `.flake8`,
+and code formatted with [black](https://github.com/ambv/black).
+
+Installing with `myst-parser[code_style]` makes the [pre-commit](https://pre-commit.com/)
+package available, which will ensure this style is met before commits are submitted, by reformatting the code
+and testing for lint errors.
+It can be setup by:
+
+```shell
+>> cd MyST-Parser
+>> pre-commit install
+```
+
+Optionally you can run `black` and `flake8` separately:
+
+```shell
+>> black .
+>> flake8 .
+```
+
+Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.
+
+All functions and class methods should be annotated with types and include a docstring. The preferred docstring format is outlined in `MyST-Parser/docstring.fmt.mustache` and can be used automatically with the
+[autodocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) VS Code extension.
+
+## Testing
+
+For code tests, myst-parser uses [pytest](https://docs.pytest.org):
+
+```shell
+>> cd MyST-Parser
+>> pytest
+```
+
+You can also use [tox](https://tox.readthedocs.io), to run the tests in multiple isolated environments (see the `tox.ini` file for available test environments):
+
+```shell
+>> cd MyST-Parser
+>> tox
+```
+
+For documentation build tests:
+
+```shell
+>> cd MyST-Parser/docs
+>> make clean
+>> make html-strict
+```
+
+```{seealso}
+{ref}`develop/testing`
+```
+
+[github-ci]: https://github.com/executablebooks/MyST-Parser/workflows/continuous-integration/badge.svg?branch=master
+[github-link]: https://github.com/executablebooks/MyST-Parser
+[codecov-badge]: https://codecov.io/gh/executablebooks/MyST-Parser/branch/master/graph/badge.svg
+[codecov-link]: https://codecov.io/gh/executablebooks/MyST-Parser
+[rtd-badge]: https://readthedocs.org/projects/myst-parser/badge/?version=latest
+[rtd-link]: https://myst-parser.readthedocs.io/en/latest/?badge=latest
+[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
+[black-link]: https://github.com/ambv/black
diff --git a/docs/develop/index.md b/docs/develop/index.md
new file mode 100644
index 0000000..f3a3f97
--- /dev/null
+++ b/docs/develop/index.md
@@ -0,0 +1,15 @@
+# Contribute
+
+This section covers documentation relevant to developing and maintaining the MyST
+codebase, and some guidelines for how you can contribute.
+
+```{toctree}
+contributing.md
+architecture.md
+test_infrastructure.md
+```
+
+## Code of Conduct
+
+The MyST-parser project follows the
+[Executable Book Project code of conduct](https://github.com/executablebooks/.github/blob/master/CODE_OF_CONDUCT.md).
diff --git a/docs/develop/test_infrastructure.md b/docs/develop/test_infrastructure.md
new file mode 100644
index 0000000..ebef011
--- /dev/null
+++ b/docs/develop/test_infrastructure.md
@@ -0,0 +1,53 @@
+(develop/testing)=
+
+# Testing Infrastructure
+
+Where possible, additions to the code should be carried out in a
+[test-driven development](https://en.wikipedia.org/wiki/Test-driven_development)
+manner:
+
+> **Write failing tests that the code should pass, then write code to pass the tests**.
+
+The tests are run using [pytest](https://docs.pytest.org)/[GitHub Actions](https://github.com/features/actions) for unit tests, and [readthedocs](https://readthedocs.org/) for documentation build tests.
+
+The tests are ordered in a hierarchical fashion:
+
+1. In `tests/test_commonmark` the [CommonMark](https://github.com/commonmark/CommonMark.git) test set is run to check that the parser is complying with the CommonMark specification.
+2. In `tests/test_renderers` are tests that check that the Markdown AST is being correctly converted to the docutils/sphinx AST. This includes testing that roles and directives are correctly parsed and run.
+3. In `tests/test_sphinx` are tests that check that minimal sphinx project builds are running correctly, to convert MyST markdown files to HTML.
+4. In `.circleci` the package documentation (written in MyST format) is built and tested for build errors/warnings.
+
+## Test tools
+
+[**pytest-regressions**](https://pytest-regressions.readthedocs.io) is a pytest plugin
+that is used in the test suite, to maintain tests that generate lots of data.
+In particular, they are used in the syntax testing to generate tests for AST trees
+which may change in the future due to changes/additions to the data captured by the parser.
+For example, after writing:
+
+```python
+def test_example_dict(data_regression):
+    data_regression.check({
+        "key1": "value1",
+        "key2": "value2",
+        "more": "data...",
+    })
+def test_example_str(file_regression):
+    file_regression.check("a very long string...")
+```
+
+Running the following will initially fail,
+but will also generate a file (per test) of expected output:
+
+```console
+$ pytest -k test_example
+```
+
+Subsequent times the tests are run, the tests output will now be validated against these stored files.
+
+After a change to the syntax parser, all failing tests can then be 'regenerated' with the new
+expected output, by running:
+
+```console
+$ pytest --force-regen
+```
diff --git a/docs/docutils.md b/docs/docutils.md
new file mode 100644
index 0000000..b4d0480
--- /dev/null
+++ b/docs/docutils.md
@@ -0,0 +1,82 @@
+(myst-docutils)=
+
+# Single Page Builds
+
+```{versionadded} 0.16.0
+```
+
+Sphinx, and thus MyST-Parser, is built on top of the [Docutils](https://docutils.sourceforge.io/docs/) package.
+MyST-Parser offers a renderer, parser and CLI-interface for working directly with Docutils, independent of Sphinx, as described below.
+
+:::{note}
+Since these tools are independent of Sphinx, this means they cannot parse any Sphinx or Sphinx extensions specific roles or directives.
+:::
+
+On installing MyST-Parser, the following CLI-commands are made available:
+
+- `myst-docutils-html`: converts MyST to HTML
+- `myst-docutils-html5`: converts MyST to HTML5
+- `myst-docutils-latex`: converts MyST to LaTeX
+- `myst-docutils-xml`: converts MyST to docutils-native XML
+- `myst-docutils-pseudoxml`: converts MyST to pseudo-XML (to visualise the AST structure)
+
+Each command can be piped stdin or take a file path as an argument:
+
+```console
+$ myst-docutils-html --help
+$ echo "Hello World" | myst-docutils-html
+$ myst-docutils-html hello-world.md
+```
+
+The commands are based on the [Docutils Front-End Tools](https://docutils.sourceforge.io/docs/user/tools.html), and so follow the same argument and options structure, included many of the MyST specific options detailed in [](sphinx/config-options).
+
+:::{dropdown}  Shared Docutils CLI Options
+```{docutils-cli-help}
+```
+:::
+
+The CLI commands can also utilise the [`docutils.conf` configuration file](https://docutils.sourceforge.io/docs/user/config.html) to configure the behaviour of the CLI commands. For example:
+
+```
+# These entries affect all processing:
+[general]
+myst-enable-extensions: deflist,linkify
+myst-footnote-transition: no
+
+# These entries affect specific HTML output:
+[html writers]
+embed-stylesheet: no
+
+[html5 writer]
+stylesheet-dirs: path/to/html5_polyglot/
+stylesheet-path: minimal.css, responsive.css
+```
+
+You can also use the {py:class}`myst_parser.docutils_.Parser` class programmatically with the [Docutils publisher API](https://docutils.sourceforge.io/docs/api/publisher.html):
+
+```python
+from docutils.core import publish_string
+from myst_parser.docutils_ import Parser
+
+source = "hallo world\n: Definition"
+output = publish_string(
+    source=source,
+    writer_name="html5",
+    settings_overrides={
+        "myst_enable_extensions": ["deflist"],
+        "embed_stylesheet": False,
+    },
+    parser=Parser(),
+)
+```
+
+Finally, you can include MyST Markdown files within a RestructuredText file, using the [`include` directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#include):
+
+```rst
+.. include:: include.md
+   :parser: myst_parser.docutils_
+```
+
+```{important}
+The `parser` option requires `docutils>=0.17`
+```
diff --git a/docs/faq/index.md b/docs/faq/index.md
new file mode 100644
index 0000000..e4d4581
--- /dev/null
+++ b/docs/faq/index.md
@@ -0,0 +1,267 @@
+(myst-sphinx)=
+
+# FAQ
+
+## How-tos
+
+These sections describe some common scenarios and use-cases for writing MyST with Sphinx.
+
+(howto/include-rst)=
+### Include rST files into a Markdown file
+
+As explained in [this section](syntax/directives/parsing), all MyST directives will parse their content as Markdown.
+Therefore, using the conventional `include` directive, will parse the file contents as Markdown:
+
+````md
+```{include} snippets/include-md.md
+```
+````
+
+```{include} snippets/include-md.md
+```
+
+To include rST, we must first "wrap" the directive in the [eval-rst directive](syntax/directives/parsing):
+
+````md
+```{eval-rst}
+.. include:: snippets/include-rst.rst
+```
+````
+
+```{eval-rst}
+.. include:: snippets/include-rst.rst
+```
+
+(howto/include-md)=
+### Include Markdown files into an rST file
+
+To include a MyST file within a ReStructuredText file, we can use the `parser` option of the `include` directive:
+
+```rst
+.. include:: include.md
+   :parser: myst_parser.sphinx_
+```
+
+```{important}
+The `parser` option requires `docutils>=0.17`
+```
+
+### Use MyST in Jupyter Notebooks
+
+The [MyST-NB](https://myst-nb.readthedocs.io) tool provides a Sphinx extension for parsing **Jupyter Notebooks written with MyST Markdown**. It includes features like automatically executing notebooks during documentation builds, storing notebook cell outputs in order to insert them elsewhere in your documentation, and more. See the [MyST-NB documentation](https://myst-nb.readthedocs.io) for more information.
+
+(howto/include-readme)=
+### Include a file from outside the docs folder (like README.md)
+
+You can include a file, including one from outside the project using e.g.:
+
+````md
+```{include} ../README.md
+```
+````
+
+**However**, including a file will not usually resolve local links correctly, like `![](my-image.png)`, since it treats the text as if it originated from the "including file".
+
+As of myst-parser version 0.12.7, a new, experimental feature has been added to resolve such links.
+You can now use for example:
+
+````md
+Source:
+```{literalinclude} ../../example.md
+:language: md
+```
+Included:
+```{include} ../../example.md
+:relative-docs: docs/
+:relative-images:
+```
+````
+
+Source:
+
+```{literalinclude} ../../example-include.md
+:language: md
+```
+
+Included:
+
+```{include} ../../example-include.md
+:relative-docs: docs/
+:relative-images:
+```
+
+The include here attempts to re-write local links, to reference them from the correct location!
+The `relative-docs` must be given the prefix of any links to re-write, to distinguish them from sphinx cross-references.
+
+:::{important}
+The current functionality only works for Markdown style images and links.
+
+If you encounter any issues with this feature, please don't hesitate to report it.
+:::
+
+(howto/autodoc)=
+### Use `sphinx.ext.autodoc` in Markdown files
+
+The [Sphinx extension `autodoc`](sphinx:sphinx.ext.autodoc), which pulls in code documentation from docstrings, is currently hard-coded to parse reStructuredText.
+It is therefore incompatible with MyST's Markdown parser.
+However, the special [`eval-rst` directive](syntax/directives/parsing) can be used to "wrap" `autodoc` directives:
+
+````md
+```{eval-rst}
+.. autoclass:: myst_parser.mocking.MockRSTParser
+    :show-inheritance:
+    :members: parse
+```
+````
+
+```{eval-rst}
+.. autoclass:: myst_parser.mocking.MockRSTParser
+    :show-inheritance:
+    :members: parse
+```
+
+As with other objects in MyST, this can then be referenced:
+
+- Using the role `` {py:class}`myst_parser.mocking.MockRSTParser` ``: {py:class}`myst_parser.mocking.MockRSTParser`
+- Using the Markdown syntax `[MockRSTParser](myst_parser.mocking.MockRSTParser)`: [MockRSTParser](myst_parser.mocking.MockRSTParser)
+
+```{warning}
+This expects docstrings to be written in reStructuredText.
+We hope to support Markdown in the future, see [GitHub issue #228](https://github.com/executablebooks/MyST-Parser/issues/228).
+```
+
+(howto/autosectionlabel)=
+### Automatically create targets for section headers
+
+:::{important}
+
+New in `v0.13.0` ✨, myst-parser now provides a separate implementation of `autosectionlabel`, which implements GitHub Markdown style bookmark anchors, like `[](file.md#header-anchor)`.
+
+See the [](syntax/header-anchors) section of extended syntaxes.
+
+:::
+
+If you'd like to *automatically* generate targets for each of your section headers,
+check out the [`autosectionlabel`](https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html)
+sphinx feature. You can activate it in your Sphinx site by adding the following to your
+`conf.py` file:
+
+```python
+extensions = [
+    'sphinx.ext.autosectionlabel',
+]
+
+# Prefix document path to section labels, to use:
+# `path/to/file:heading` instead of just `heading`
+autosectionlabel_prefix_document = True
+```
+
+So, if you have a page at `myfolder/mypage.md` (relative to your documentation root)
+with the following structure:
+
+```md
+# Title
+
+## My Subtitle
+```
+
+Then the `autosectionlabel` feature will allow you to reference the section headers
+like so:
+
+```md
+{ref}`path/to/file_1:My Subtitle`
+```
+
+(howto/warnings)=
+### Suppress warnings
+
+In general, if your build logs any warnings, you should either fix them or [raise an Issue](https://github.com/executablebooks/MyST-Parser/issues/new/choose) if you think the warning is erroneous.
+However, in some circumstances if you wish to suppress the warning you can use the [`suppress_warnings`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings) configuration option.
+All myst-parser warnings are prepended by their type, e.g. to suppress:
+
+```md
+# Title
+### Subtitle
+```
+
+```
+WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]
+```
+
+Add to your `conf.py`:
+
+```python
+suppress_warnings = ["myst.header"]
+```
+
+
+### Sphinx-specific page front matter
+
+Sphinx intercepts front matter and stores them within the global environment
+(as discussed [in the deflists documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html)).
+There are certain front-matter keys (or their translations) that are also recognised specifically by docutils and parsed to inline Markdown:
+
+- `author`
+- `authors`
+- `organization`
+- `address`
+- `contact`
+- `version`
+- `revision`
+- `status`
+- `date`
+- `copyright`
+- `dedication`
+- `abstract`
+
+A classic use-case is to specify 'orphan' documents, that are not specified in any toctrees.
+For example, inserting the following syntax at the top of a page will cause Sphinx to treat it as an orphan page:
+
+```md
+---
+orphan: true
+---
+
+This is an orphan document, not specified in any toctrees.
+```
+
+### Migrate pre-existing rST into MyST
+
+If you've already got some reStructuredText files that you'd like to convert into MyST Markdown, try the [`rst-to-myst`](https://github.com/executablebooks/rst-to-myst) tool, which allows you to convert single rST files to MyST markdown documents.
+
+## Disable Markdown syntax for the parser
+
+If you'd like to either enable or disable custom markdown syntax, use `myst_disable_syntax`.
+Anything in this list will no longer be parsed by the MyST parser.
+
+For example, to disable the `emphasis` in-line syntax, use this configuration:
+
+```python
+myst_disable_syntax = ["emphasis"]
+```
+
+emphasis syntax will now be disabled. For example, the following will be rendered
+*without* any italics:
+
+```md
+*emphasis is now disabled*
+```
+
+For a list of all the syntax elements you can disable, see the [markdown-it parser guide](markdown_it:using).
+
+## Common errors and questions
+
+These are common issues and gotchas that people may experience when using the MyST Sphinx extension.
+
+### What markup language should I use inside directives?
+
+If you need to parse content *inside* of another block of content (for example, the
+content inside a **note directive**), note that the MyST parser will be used for this
+nested parsing as well.
+
+### Why doesn't my role/directive recognize markdown link syntax?
+
+There are some roles/directives that _hard-code_ syntax into
+their behavior. For example, many roles allow you to supply titles for links like so:
+`` {role}`My title <myref>` ``. While this looks like reStructuredText, the role may
+be explicitly expecting the `My title <myref>` structure, and so MyST will behave the same way.
diff --git a/docs/faq/snippets/include-md.md b/docs/faq/snippets/include-md.md
new file mode 100644
index 0000000..296421a
--- /dev/null
+++ b/docs/faq/snippets/include-md.md
@@ -0,0 +1 @@
+Hallo I'm from a Markdown file, [with a reference](howto/autodoc).
diff --git a/docs/faq/snippets/include-rst.rst b/docs/faq/snippets/include-rst.rst
new file mode 100644
index 0000000..04ec485
--- /dev/null
+++ b/docs/faq/snippets/include-rst.rst
@@ -0,0 +1 @@
+Hallo I'm from an rST file, :ref:`with a reference <howto/autodoc>`.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..36c0cd0
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,160 @@
+---
+sd_hide_title: true
+---
+
+# Overview
+
+::::{grid}
+:reverse:
+:gutter: 3 4 4 4
+:margin: 1 2 1 2
+
+:::{grid-item}
+:columns: 12 4 4 4
+
+```{image} _static/logo-square.svg
+:width: 200px
+:class: sd-m-auto
+```
+
+:::
+
+:::{grid-item}
+:columns: 12 8 8 8
+:child-align: justify
+:class: sd-fs-5
+
+```{rubric} MyST - Markedly Structured Text - Parser
+```
+
+A Sphinx and Docutils extension to parse MyST,
+a rich and extensible flavour of Markdown for authoring technical and scientific documentation.
+
+```{button-ref} intro
+:ref-type: doc
+:color: primary
+:class: sd-rounded-pill
+
+Get Started
+```
+
+:::
+
+::::
+
+---
+
+::::{grid} 1 2 2 3
+:gutter: 1 1 1 2
+
+:::{grid-item-card} {octicon}`markdown;1.5em;sd-mr-1` CommonMark-plus
+:link: syntax/core
+:link-type: ref
+
+MyST extends the CommonMark syntax specification, to support technical authoring features such as tables and footnotes.
+
++++
+[Learn more »](syntax/core)
+:::
+
+:::{grid-item-card} {octicon}`plug;1.5em;sd-mr-1` Sphinx compatible
+:link: roles-directives
+:link-type: ref
+
+Use the MyST role and directive syntax to harness the full capability of Sphinx, such as admonitions and figures, and all existing Sphinx extensions.
+
++++
+[Learn more »](roles-directives)
+:::
+
+:::{grid-item-card} {octicon}`tools;1.5em;sd-mr-1` Highly configurable
+:link: configuration
+:link-type: doc
+
+MyST-parser can be configured at both the global and individual document level,
+to modify parsing behaviour and access extended syntax features.
+
++++
+[Learn more »](configuration)
+:::
+
+::::
+
+---
+
+```{rubric} Additional resources
+```
+
+[MyST-Markdown VS Code extension](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight)
+: For MyST extended syntax highlighting and authoring tools.
+
+[Convert existing ReStructuredText files to Markdown][rst-to-myst]
+: Use the [rst-to-myst] CLI or [the MySTyc interactive web interface](https://astrojuanlu.github.io/mystyc/).
+
+[MyST-NB](https://myst-nb.readthedocs.io)
+: A Sphinx and Docutils extension for compiling Jupyter Notebooks into high quality documentation formats, built on top of the MyST-Parser.
+
+[Jupyter Book](https://jupyterbook.org)
+: An open source project for building beautiful, publication-quality books and documents from computational material, built on top of the MyST-Parser and MyST-NB.
+
+[The Jupyter Book gallery](https://executablebooks.org/en/latest/gallery.html)
+: Examples of documents built with MyST.
+
+[Javascript MyST parser][mystjs]
+: The [mystjs] Javascript parser, allows you to parse MyST in websites.
+
+[markdown-it-py]
+: A CommonMark-compliant and extensible Markdown parser, used by MyST-Parser to parse source text to tokens.
+
+```{rubric} Acknowledgements
+```
+
+The MyST markdown language and MyST parser are both supported by the open community,
+[The Executable Book Project](https://executablebooks.org).
+
+```{toctree}
+:hidden:
+intro.md
+```
+
+```{toctree}
+:hidden:
+:caption: Guides
+
+syntax/syntax
+syntax/optional
+syntax/roles-and-directives.md
+configuration.md
+docutils.md
+faq/index.md
+develop/index.md
+```
+
+```{toctree}
+:hidden:
+:caption: Reference
+
+develop/_changelog.md
+syntax/reference
+develop/background.md
+api/reference.rst
+```
+
+[commonmark]: https://commonmark.org/
+[github-ci]: https://github.com/executablebooks/MyST-Parser/workflows/continuous-integration/badge.svg?branch=master
+[github-link]: https://github.com/executablebooks/MyST-Parser
+[codecov-badge]: https://codecov.io/gh/executablebooks/MyST-Parser/branch/master/graph/badge.svg
+[codecov-link]: https://codecov.io/gh/executablebooks/MyST-Parser
+[rtd-badge]: https://readthedocs.org/projects/myst-parser/badge/?version=latest
+[rtd-link]: https://myst-parser.readthedocs.io/en/latest/?badge=latest
+[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
+[pypi-badge]: https://img.shields.io/pypi/v/myst-parser.svg
+[pypi-link]: https://pypi.org/project/myst-parser
+[conda-badge]: https://anaconda.org/conda-forge/myst-parser/badges/version.svg
+[conda-link]: https://anaconda.org/conda-forge/myst-parser
+[black-link]: https://github.com/ambv/black
+[github-badge]: https://img.shields.io/github/stars/executablebooks/myst-parser?label=github
+[markdown-it-py]: https://markdown-it-py.readthedocs.io/
+[markdown-it]: https://markdown-it.github.io/
+[rst-to-myst]: https://rst-to-myst.readthedocs.io
+[mystjs]: https://github.com/executablebooks/mystjs
diff --git a/docs/intro.md b/docs/intro.md
new file mode 100644
index 0000000..dc65728
--- /dev/null
+++ b/docs/intro.md
@@ -0,0 +1,250 @@
+(intro/get-started)=
+# Get Started
+
+This page describes how to get started with the MyST parser, with a focus on enabling it in the Sphinx documentation engine.
+
+## Installation
+
+[![PyPI][pypi-badge]][pypi-link]
+[![Conda][conda-badge]][conda-link]
+
+To install use [pip](https://pip.pypa.io):
+
+```bash
+pip install myst-parser
+```
+
+or [Conda](https://docs.conda.io):
+
+```bash
+conda install -c conda-forge myst-parser
+```
+
+[pypi-badge]: https://img.shields.io/pypi/v/myst-parser.svg
+[pypi-link]: https://pypi.org/project/myst-parser
+[conda-badge]: https://anaconda.org/conda-forge/myst-parser/badges/version.svg
+[conda-link]: https://anaconda.org/conda-forge/myst-parser
+
+(intro/sphinx)=
+## Enable MyST in Sphinx
+
+To get started with Sphinx, see their [Quickstart Guide](https://www.sphinx-doc.org/en/master/usage/quickstart.html).
+
+To use the MyST parser in Sphinx, simply add the following to your `conf.py` file:
+
+```python
+extensions = ["myst_parser"]
+```
+
+This will activate the MyST Parser extension, causing all documents with the `.md` extension to be parsed as MyST.
+
+:::{tip}
+To parse single documents, see the [](docutils.md) section
+:::
+
+(intro/writing)=
+## Write a CommonMark document
+
+MyST is an extension of [CommonMark Markdown](https://commonmark.org/),
+that includes [additional syntax](../syntax/syntax.md) for technical authoring,
+which integrates with Docutils and Sphinx.
+
+To start off, create an empty file called `myfile.md` and give it a markdown title and text.
+
+```md
+# My nifty title
+
+Some **text**!
+```
+
+To parse to HTML, try the CLI:
+
+```html
+$ myst-docutils-html5 --stylesheet= myfile.md
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
+<title>My nifty title</title>
+
+</head>
+<body>
+<main id="my-nifty-title">
+<h1 class="title">My nifty title</h1>
+
+<p>Some <strong>text</strong>!</p>
+</main>
+</body>
+</html>
+```
+
+To include this document within a Sphinx project,
+include `myfile.md` in a [`toctree` directive](sphinx:toctree-directive) on an index page.
+
+## Extend CommonMark with roles and directives
+
+MyST allows any Sphinx role or directive to be used in a document.
+These are extensions points allowing for richer features, such as admonitions and figures.
+
+For example, add an `admonition` directive and `sup` role to your Markdown page, like so:
+
+````md
+# My nifty title
+
+Some **text**!
+
+```{admonition} Here's my title
+:class: tip
+
+Here's my admonition content.{sup}`1`
+```
+````
+
+Then convert to HTML:
+
+```html
+$ myst-docutils-html5 --stylesheet= myfile.md
+...
+<div class="admonition tip">
+<p class="admonition-title">Here's my title</p>
+<p>Here's my admonition content.<sup>1</sup></p>
+</div>
+...
+```
+
+:::{seealso}
+The full [](syntax/roles-and-directives.md) section
+:::
+
+(intro/reference)=
+## Cross-referencing
+
+MyST-Parser offers powerful cross-referencing features, to link to documents, headers, figures and more.
+
+For example, to add a section *reference target*, and reference it:
+
+```md
+(header-label)=
+# A header
+
+[My reference](header-label)
+```
+
+```html
+$ myst-docutils-html5 --stylesheet= myfile.md
+...
+<span id="header-label"></span>
+<h1 class="title">A header</h1>
+
+<p><a class="reference internal" href="#header-label">My reference</a></p>
+...
+```
+
+:::{seealso}
+The [](syntax/referencing) section,\
+and the [ReadTheDocs cross-referencing](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html) documentation
+:::
+
+## Configuring MyST-Parser
+
+The [](configuration.md) section contains a complete list of configuration options for the MyST-Parser.
+
+These can be applied globally, e.g. in the sphinx `conf.py`:
+
+```python
+myst_enable_extensions = [
+  "colon_fence",
+]
+```
+
+Or they can be applied to specific documents, at the top of the document:
+
+```yaml
+---
+myst:
+  enable_extensions: ["colon_fence"]
+---
+```
+
+## Extending Sphinx
+
+The other way to extend MyST in Sphinx is to install Sphinx extensions that define new roles, directives, etc.
+
+For example, let's install the `sphinxcontrib.mermaid` extension,
+which will allow us to generate [Mermaid diagrams](https://mermaid-js.github.io/mermaid/#/) with MyST.
+
+First, install `sphinxcontrib.mermaid`:
+
+```shell
+pip install sphinxcontrib-mermaid
+```
+
+Next, add it to your list of extensions in `conf.py`:
+
+```python
+extensions = [
+  "myst_parser",
+  "sphinxcontrib.mermaid",
+]
+```
+
+Now, add a **mermaid directive** to your markdown file.
+For example:
+
+````md
+# My nifty title
+
+Some **text**!
+
+```{admonition} Here's my title
+:class: warning
+
+Here's my admonition content
+```
+
+(section-two)=
+## Here's another section
+
+And some more content.
+
+% This comment won't make it into the outputs!
+And here's {ref}`a reference to this section <section-two>`.
+I can also reference the section {ref}`section-two` without specifying my title.
+
+:::{note}
+And here's a note with a colon fence!
+:::
+
+And finally, here's a cool mermaid diagram!
+
+```{mermaid}
+sequenceDiagram
+  participant Alice
+  participant Bob
+  Alice->John: Hello John, how are you?
+  loop Healthcheck
+      John->John: Fight against hypochondria
+  end
+  Note right of John: Rational thoughts <br/>prevail...
+  John-->Alice: Great!
+  John->Bob: How about you?
+  Bob-->John: Jolly good!
+```
+````
+
+When you build your documentation, you should see something like this:
+
+```{mermaid}
+sequenceDiagram
+  participant Alice
+  participant Bob
+  Alice->John: Hello John, how are you?
+  loop Healthcheck
+      John->John: Fight against hypochondria
+  end
+  Note right of John: Rational thoughts <br/>prevail...
+  John-->Alice: Great!
+  John->Bob: How about you?
+  Bob-->John: Jolly good!
+```
diff --git a/docs/syntax/example.txt b/docs/syntax/example.txt
new file mode 100644
index 0000000..e84df8e
--- /dev/null
+++ b/docs/syntax/example.txt
@@ -0,0 +1 @@
+Hallo!
diff --git a/docs/syntax/img/fun-fish.png b/docs/syntax/img/fun-fish.png
new file mode 100644
index 0000000..c9a4997
--- /dev/null
+++ b/docs/syntax/img/fun-fish.png
diff --git a/docs/syntax/optional.md b/docs/syntax/optional.md
new file mode 100644
index 0000000..c5ee44e
--- /dev/null
+++ b/docs/syntax/optional.md
@@ -0,0 +1,1002 @@
+---
+myst:
+  substitutions:
+    key1: I'm a **substitution**
+    key2: |
+      ```{note}
+      {{ key1 }}
+      ```
+    key3a: <img src="img/fun-fish.png" alt="fishy" width="200px">
+    key3: |
+      ```{image} img/fun-fish.png
+      :alt: fishy
+      :width: 200px
+      ```
+    key4: example
+---
+
+(syntax/extensions)=
+
+# Syntax Extensions
+
+MyST-Parser is highly configurable, utilising the inherent "plugability" of the [markdown-it-py](markdown_it:index) parser.
+The following syntaxes are optional (disabled by default) and can be enabled *via* the sphinx `conf.py` (see also [](sphinx/config-options)).
+Their goal is generally to add more *Markdown friendly* syntaxes; often enabling and rendering [markdown-it-py plugins](markdown_it:md/plugins) that extend the [CommonMark specification](https://commonmark.org/).
+
+To enable all the syntaxes explained below:
+
+```python
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
+```
+
+:::{important}
+`myst_enable_extensions` replaces previous configuration options:
+`admonition_enable`, `figure_enable`, `dmath_enable`, `amsmath_enable`, `deflist_enable`, `html_img_enable`
+:::
+
+(syntax/typography)=
+
+## Typography
+
+Adding `"smartquotes"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)) will automatically convert standard quotations to their opening/closing variants:
+
+- `'single quotes'`: 'single quotes'
+- `"double quotes"`: "double quotes"
+
+Adding `"replacements"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)) will automatically convert some common typographic texts
+
+text  | converted
+----- | ----------
+``(c)``, ``(C)`` | (c)
+``(tm)``, ``(TM)`` | (tm)
+``(r)``, ``(R)`` | (r)
+``(p)``, ``(P)`` | (p)
+``+-`` | +-
+``...`` | ...
+``?....`` | ?....
+``!....`` | !....
+``????????`` | ????????
+``!!!!!`` | !!!!!
+``,,,`` | ,,,
+``--`` | --
+``---`` | ---
+
+(syntax/strikethrough)=
+
+## Strikethrough
+
+```{versionadded} 0.17.0
+```
+
+The `strikethrough` extension allows text within `~~` delimiters to have a strikethrough (horizontal line) placed over it.
+For example, `~~strikethrough with *emphasis*~~` renders as: ~~strikethrough with *emphasis*~~.
+
+:::{warning}
+This extension is currently only supported for HTML output,
+and you will need to suppress the `myst.strikethrough` warning
+(see [](howto/warnings))
+:::
+
+(syntax/math)=
+## Math shortcuts
+
+Math is parsed by adding to the `myst_enable_extensions` list option, in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html) one or both of:
+
+- `"dollarmath"` for parsing of dollar `$` and `$$` encapsulated math.
+- `"amsmath"` for direct parsing of [amsmath LaTeX environments](https://ctan.org/pkg/amsmath).
+
+These options enable their respective Markdown parser plugins, as detailed in the [markdown-it plugin guide](markdown_it:md/plugins).
+
+:::{important}
+`myst_dmath_enable=True` and `myst_amsmath_enable=True` are deprecated, and replaced by `myst_enable_extensions = ["dollarmath", "amsmath"]`
+:::
+
+### Dollar delimited math
+
+Enabling `dollarmath` will parse the following syntax:
+
+- Inline math: `$...$`
+- Display (block) math: `$$...$$`
+
+Additionally if `myst_dmath_allow_labels=True` is set (the default):
+
+- Display (block) math with equation label: `$$...$$ (1)`
+
+For example, `$x_{hey}=it+is^{math}$` renders as $x_{hey}=it+is^{math}$.
+This is equivalent to writing:
+
+```md
+{math}`x_{hey}=it+is^{math}`
+```
+
+:::{admonition} Escaping Dollars
+:class: tip
+
+Math can be escaped (negated) by adding a `\` before the first symbol, e.g. `\$a$` renders as \$a\$.
+Escaping can also be used inside math, e.g. `$a=\$3$` renders as $a=\$3$.
+
+Conversely `\\` will negate the escaping, so `\\$a$` renders as \\$a$.
+:::
+
+Block-level math can be specified with `$$` signs that wrap the math block you'd like to parse.
+For example:
+
+```latex
+$$
+   \begin{eqnarray}
+      y    & = & ax^2 + bx + c \\
+      f(x) & = & x^2 + 2xy + y^2
+   \end{eqnarray}
+$$
+```
+
+becomes
+
+$$
+   \begin{eqnarray}
+      y    & = & ax^2 + bx + c \\
+      f(x) & = & x^2 + 2xy + y^2
+   \end{eqnarray}
+$$
+
+This is equivalent to the following directive:
+
+````md
+```{math}
+   \begin{eqnarray}
+      y    & = & ax^2 + bx + c \\
+      f(x) & = & x^2 + 2xy + y^2
+   \end{eqnarray}
+```
+````
+
+You can also add labels to block equations:
+
+```latex
+$$
+e = mc^2
+$$ (eqn:best)
+
+This is the best equation {eq}`eqn:best`
+```
+
+$$
+e = mc^2
+$$ (eqn:best)
+
+This is the best equation {eq}`eqn:best`
+
+There are a few other options available to control dollar math parsing:
+
+`myst_dmath_allow_space=False`, will cause inline math to only be parsed if there are no initial / final spaces, e.g. `$a$` but not `$ a$` or `$a $`.
+
+`myst_dmath_allow_digits=False`, will cause inline math to only be parsed if there are no initial / final digits, e.g. `$a$` but not `1$a$` or `$a$2`.
+
+These options can both be useful if you also wish to use `$` as a unit of currency.
+
+```{versionadded} 0.14.0
+`myst_dmath_double_inline` option
+```
+
+To allow display math (i.e. `$$`) within an inline context, set `myst_dmath_double_inline = True` (`False` by default).
+This allows for example:
+
+```latex
+Hence, for $\alpha \in (0, 1)$,
+$$
+  \mathbb P (\alpha \bar{X} \ge \mu) \le \alpha;
+$$
+i.e., $[\alpha \bar{X}, \infty)$ is a lower 1-sided $1-\alpha$ confidence bound for $\mu$.
+```
+
+Hence, for $\alpha \in (0, 1)$,
+$$
+  \mathbb P (\alpha \bar{X} \ge \mu) \le \alpha;
+$$
+i.e., $[\alpha \bar{X}, \infty)$ is a lower 1-sided $1-\alpha$ confidence bound for $\mu$.
+
+### Math in other block elements
+
+Math will also work when nested in other block elements, like lists or quotes:
+
+```md
+- A list
+- $$ a = 1 $$
+
+> A block quote
+> $$ a = 1 $$
+```
+
+- A list
+- $$ a = 1 $$
+
+> A block quote
+> $$ a = 1 $$
+
+### Direct LaTeX Math
+
+Want to use [amsmath](https://ctan.org/pkg/amsmath) LaTeX directly, with no dollars?
+See [the extended syntax option](syntax/amsmath).
+
+(syntax/mathjax)=
+### Mathjax and math parsing
+
+When building HTML using the [sphinx.ext.mathjax](https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax) extension (enabled by default),
+If `dollarmath` is enabled, Myst-Parser injects the `tex2jax_ignore` (MathJax v2) and  `mathjax_ignore` (MathJax v3) classes in to the top-level section of each MyST document, and adds the following default MathJax configuration:
+
+MathJax version 2 (see [the tex2jax preprocessor](https://docs.mathjax.org/en/v2.7-latest/options/preprocessors/tex2jax.html#configure-tex2jax):
+
+```javascript
+MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})
+```
+
+MathJax version 3 (see [the document options](https://docs.mathjax.org/en/latest/options/document.html?highlight=ignoreHtmlClass#the-configuration-block)):
+
+```javascript
+window.MathJax = {"options": {"processHtmlClass": "tex2jax_process|mathjax_process|math|output_area"}}
+```
+
+This ensurea that MathJax processes only math, identified by the `dollarmath` and `amsmath` extensions, or specified in `math` directives.
+
+To change this behaviour, set a custom regex, for identifying HTML classes to process, like `myst_mathjax_classes="math|myclass"`, or set `myst_update_mathjax=False` to inhibit this override and process all HTML elements.
+
+(syntax/linkify)=
+## Linkify
+
+Adding `"linkify"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)) will automatically identify "bare" web URLs and add hyperlinks:
+
+`www.example.com` -> www.example.com
+
+To only match URLs that start with schema, such as `http://example.com`, set `myst_linkify_fuzzy_links=False`.
+
+:::{important}
+This extension requires that [linkify-it-py](https://github.com/tsutsu3/linkify-it-py) is installed.
+Either directly; `pip install linkify-it-py` or *via* `pip install myst-parser[linkify]`.
+:::
+
+(syntax/substitutions)=
+
+## Substitutions (with Jinja2)
+
+Adding `"substitution"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)) will allow you to add substitutions, added in either the `conf.py` using `myst_substitutions`:
+
+```python
+myst_substitutions = {
+  "key1": "I'm a **substitution**"
+}
+```
+
+or at the top of the file, in the front-matter section (see [this section](syntax/frontmatter)):
+
+````yaml
+---
+myst:
+  substitutions:
+    key1: "I'm a **substitution**"
+    key2: |
+      ```{note}
+      {{ key1 }}
+      ```
+    key3: |
+      ```{image} img/fun-fish.png
+      :alt: fishy
+      :width: 200px
+      ```
+    key4: example
+---
+````
+
+:::{important}
+Keys in the front-matter will override ones in the `conf.py`.
+:::
+
+You can use these substitutions inline or as blocks, and you can even nest substitutions in other substitutions (but circular references are prohibited):
+
+::::{tab-set}
+:::{tab-item} Markdown Input
+
+```md
+Inline: {{ key1 }}
+
+Block level:
+
+{{ key2 }}
+
+| col1     | col2     |
+| -------- | -------- |
+| {{key2}} | {{key3}} |
+
+```
+
+:::
+
+:::{tab-item} Rendered Output
+Inline: {{ key1 }}
+
+Block level:
+
+{{ key2 }}
+
+| col1     | col2     |
+| -------- | -------- |
+| {{key2}} | {{key3}} |
+
+:::
+::::
+
+:::{important}
+
+Substitutions will only be assessed where you would normally use Markdown, e.g. not in code blocks:
+
+````
+```
+{{ key1 }}
+```
+````
+
+```
+{{ key1 }}
+```
+
+One should also be wary of using unsuitable directives for inline substitutions.
+This may lead to unexpected outcomes.
+
+:::
+
+Substitution references are assessed as [Jinja2 expressions](http://jinja.palletsprojects.com) which can use [filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-builtin-filters), and also contains the [Sphinx Environment](https://www.sphinx-doc.org/en/master/extdev/envapi.html) in the context (as `env`).
+Therefore you can do things like:
+
+```md
+- version: {{ env.config.version }}
+- docname: {{ env.docname | upper }}
+- {{ "a" + "b" }}
+```
+
+- version: {{ env.config.version }}
+- docname: {{ env.docname | upper }}
+- {{ "a" + "b" }}
+
+You can also change the delimiter if necessary, for example setting in the `conf.py`:
+
+```python
+myst_sub_delimiters = ["|", "|"]
+```
+
+Will parse: `|| "a" + "b" ||`.
+This should be changed with care though, so as not to affect other syntaxes.
+
+The exact logic for handling substitutions is:
+
+1. Combine global substitutions (specified in `conf.py`) with front-matter substitutions, to create a variable context (front-matter takes priority)
+2. Add the sphinx `env` to the variable context
+3. Create the string content to render using Jinja2 (passing it the variable context)
+4. If the substitution is inline and not a directive, render ignoring block syntaxes (like lists or block-quotes), otherwise render with all syntax rules.
+
+### Substitutions and URLs
+
+Substitutions cannot be directly used in URLs, such as `[a link](https://{{key4}}.com)` or `<https://{{key4}}.com>`.
+However, since Jinja2 substitutions allow for Python methods to be used, you can use string formatting or replacements:
+
+```md
+{{ '[a link](https://{}.com)'.format(key4) }}
+
+{{ '<https://myst-parser.readthedocs.io/en/latest/REPLACE.html>'.replace('REPLACE', env.docname) }}
+```
+
+{{ '[a link](https://{}.com)'.format(key4) }}
+
+{{ '<https://myst-parser.readthedocs.io/en/latest/REPLACE.html>'.replace('REPLACE', env.docname) }}
+
+(syntax/colon_fence)=
+
+## Code fences using colons
+
+By adding `"colon_fence"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+you can also use `:::` delimiters to denote code fences, instead of ```` ``` ````.
+
+Using colons instead of back-ticks has the benefit of allowing the content to be rendered correctly, when you are working in any standard Markdown editor.
+It is ideal for admonition type directives (as documented in [Directives](syntax/directives)) or tables with titles, for example:
+
+::::::{tab-set}
+:::::{tab-item} Markdown Input
+```md
+:::{note}
+This text is **standard** _Markdown_
+:::
+
+:::{table} This is a **standard** _Markdown_ title
+:align: center
+:widths: grid
+
+abc | mnp | xyz
+--- | --- | ---
+123 | 456 | 789
+:::
+```
+
+:::::
+
+:::::{tab-item} Rendered Output
+
+:::{note}
+This text is **standard** _Markdown_
+:::
+
+:::{table} This is a **standard** _Markdown_ title
+:align: center
+:widths: grid
+
+abc | mnp | xyz
+--- | --- | ---
+123 | 456 | 789
+:::
+
+:::::
+::::::
+
+Similar to normal directives, these directives can also be nested:
+
+```md
+::::{important}
+:::{note}
+This text is **standard** _Markdown_
+:::
+::::
+```
+
+::::{important}
+:::{note}
+This text is **standard** _Markdown_
+:::
+::::
+
+and also parameter options can be used:
+
+```md
+:::{admonition} This *is* also **Markdown**
+:class: warning
+
+This text is **standard** _Markdown_
+:::
+```
+
+:::{admonition} This *is* also **Markdown**
+:class: warning
+
+This text is **standard** _Markdown_
+:::
+
+(syntax/admonitions)=
+
+## Admonition directives
+
+:::{important}
+`myst_admonition_enable` is deprecated and replaced by `myst_enable_extensions = ["colon_fence"]` (see above).
+Also, classes should now be set with the `:class: myclass` option.
+
+Also see [](syntax/html-admonition).
+:::
+
+(syntax/header-anchors)=
+
+## Auto-generated header anchors
+
+The MyST Parser can automatically generate label "slugs" for header anchors so that you can reference them from markdown links.
+For example, you can use header bookmark links, locally; `[](#header-anchor)`, or cross-file `[](path/to/file.md#header-anchor)`.
+To achieve this, use the `myst_heading_anchors = DEPTH` configuration option, where `DEPTH` is the depth of header levels for which you wish to generate links.
+
+For example, the following configuration in `conf.py` tells the `myst_parser` to generate labels for heading anchors for `h1`, `h2`, and `h3` level headings (corresponding to `#`, `##`, and `###` in markdown).
+
+```python
+myst_heading_anchors = 3
+```
+
+You can then insert markdown links directly to anchors that are generated from your header titles in your documentation.
+For example `[](#auto-generated-header-anchors)`: [](#auto-generated-header-anchors).
+
+The paths to other files should be relative to the current file, for example
+`[**link text**](./syntax.md#core-syntax)`: [**link text**](./syntax.md#core-syntax).
+
+
+### Anchor slug structure
+
+The anchor "slugs" created aim to follow the [GitHub implementation](https://github.com/Flet/github-slugger):
+
+- lower-case text
+- remove punctuation
+- replace spaces with `-`
+- enforce uniqueness *via* suffix enumeration `-1`
+
+To change the slug generation function, set `myst_heading_slug_func` in your `conf.py` to a function that accepts a string and returns a string.
+
+### Inspect the links that will be created
+
+You can inspect the links that will be created using the command-line tool:
+
+```console
+$ myst-anchors -l 2 docs/syntax/optional.md
+<h1 id="optional-myst-syntaxes"></h1>
+<h2 id="admonition-directives"></h2>
+<h2 id="auto-generated-header-anchors"></h2>
+<h2 id="definition-lists"></h2>
+<h2 id="images"></h2>
+<h2 id="markdown-figures"></h2>
+<h2 id="direct-latex-math"></h2>
+```
+
+(syntax/definition-lists)=
+
+## Definition Lists
+
+By adding `"deflist"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+you will be able to utilise definition lists.
+Definition lists utilise the [markdown-it-py deflist plugin](markdown_it:md/plugins), which itself is based on the [Pandoc definition list specification](http://johnmacfarlane.net/pandoc/README.html#definition-lists).
+
+This syntax can be useful, for example, as an alternative to nested bullet-lists:
+
+- Term 1
+  - Definition
+- Term 2
+  - Definition
+
+Using instead:
+
+```md
+Term 1
+: Definition
+
+Term 2
+: Definition
+```
+
+Term 1
+: Definition
+
+Term 2
+: Definition
+
+From the Pandoc documentation:
+
+> Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions.
+> A definition begins with a colon or tilde, which may be indented one or two spaces.
+
+> A term may have multiple definitions, and each definition may consist of one or more block elements (paragraph, code block, list, etc.)
+
+Here is a more complex example, demonstrating some of these features:
+
+Term *with Markdown*
+: Definition [with reference](syntax/definition-lists)
+
+  A second paragraph
+: A second definition
+
+Term 2
+  ~ Definition 2a
+  ~ Definition 2b
+
+Term 3
+:     A code block
+: > A quote
+: A final definition, that can even include images:
+
+  <img src="img/fun-fish.png" alt="fishy" width="200px">
+
+This was created from:
+
+```md
+Term *with Markdown*
+: Definition [with reference](syntax/definition-lists)
+
+  A second paragraph
+: A second definition
+
+Term 2
+  ~ Definition 2a
+  ~ Definition 2b
+
+Term 3
+:     A code block
+
+: > A quote
+
+: A final definition, that can even include images:
+
+  <img src="img/fun-fish.png" alt="fishy" width="200px">
+```
+
+(syntax/tasklists)=
+## Task Lists
+
+By adding `"tasklist"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+you will be able to utilise task lists.
+Task lists utilise the [markdown-it-py tasklists plugin](markdown_it:md/plugins),
+and are applied to markdown list items starting with `[ ]` or `[x]`:
+
+```markdown
+- [ ] An item that needs doing
+- [x] An item that is complete
+```
+
+- [ ] An item that needs doing
+- [x] An item that is complete
+
+(syntax/fieldlists)=
+## Field Lists
+
+```{versionadded} 0.16.0
+```
+
+Field lists are mappings from field names to field bodies,
+based on the [reStructureText syntax](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists).
+
+````md
+:name only:
+:name: body
+:*Nested syntax*: Both name and body may contain **nested syntax**.
+:Paragraphs: Since the field marker may be quite long, the second
+   and subsequent lines of a paragraph do not have to line up
+   with the first line.
+:Alignment 1: If the field body starts on the first line...
+
+              Then the entire field body must be indented the same.
+:Alignment 2:
+  If the field body starts on a subsequent line...
+
+  Then the indentation is always two spaces.
+:Blocks:
+
+  As well as paragraphs, any block syntaxes may be used in a field body:
+
+  - Me
+  - Myself
+  - I
+
+  ```python
+  print("Hello, world!")
+  ```
+````
+
+:name only:
+:name: body
+:*Nested syntax*: Both name and body may contain **nested syntax**.
+:Paragraphs: Since the field marker may be quite long, the second
+   and subsequent lines of a paragraph do not have to line up
+   with the first line.
+:Alignment 1: If the field body starts on the first line...
+
+              Then the entire field body must be indented the same.
+:Alignment 2:
+  If the field body starts on a subsequent line...
+
+  Then the indentation is always two spaces.
+:Blocks:
+
+  As well as paragraphs, any block syntaxes may be used in a field body:
+
+  - Me
+  - Myself
+  - I
+
+  ```python
+  print("Hello, world!")
+  ```
+
+A prominent use case of field lists is for use in API docstrings, as used in [Sphinx's docstring renderers](sphinx:python-domain):
+
+````md
+```{py:function} send_message(sender, priority)
+
+Send a message to a recipient
+
+:param str sender: The person sending the message
+:param priority: The priority of the message, can be a number 1-5
+:type priority: int
+:return: the message id
+:rtype: int
+:raises ValueError: if the message_body exceeds 160 characters
+```
+````
+
+```{py:function} send_message(sender, priority)
+
+Send a message to a recipient
+
+:param str sender: The person sending the message
+:param priority: The priority of the message, can be a number 1-5
+:type priority: int
+:return: the message id
+:rtype: int
+:raises ValueError: if the message_body exceeds 160 characters
+```
+
+:::{note}
+Currently `sphinx.ext.autodoc` does not support MyST, see [](howto/autodoc).
+:::
+
+(syntax/images)=
+
+## Images
+
+MyST provides a few different syntaxes for including images in your documentation, as explained below.
+
+The first is the standard Markdown syntax:
+
+```md
+![fishy](img/fun-fish.png)
+```
+
+![fishy](img/fun-fish.png)
+
+This will correctly copy the image to the build folder and will render it in all output formats (HTML, TeX, etc).
+However, it is limited in the configuration that can be applied, for example setting a width.
+
+As discussed [above](syntax/directives), MyST allow for directives to be used such as `image` and `figure` (see {ref}`the sphinx documentation <sphinx:rst-primer>`):
+
+````md
+```{image} img/fun-fish.png
+:alt: fishy
+:class: bg-primary
+:width: 200px
+:align: center
+```
+````
+
+```{image} img/fun-fish.png
+:alt: fishy
+:class: bg-primary mb-1
+:width: 200px
+```
+
+Additional options can now be set, however, in contrast to the Markdown syntax, this syntax will not show the image in common Markdown viewers (for example when the files are viewed on GitHub).
+
+The final option is directly using HTML, which is also parsed by MyST.
+This is usually a bad option, because the HTML is treated as raw text during the build process and so sphinx will not recognise that the image file is to be copied, and will not output the HTML into non-HTML output formats.
+
+HTML parsing to the rescue!
+
+By adding `"html_image"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+MySt-Parser will attempt to convert any isolated `img` tags (i.e. not wrapped in any other HTML) to the internal representation used in sphinx.
+
+```html
+<img src="img/fun-fish.png" alt="fishy" width="200px">
+<img src="img/fun-fish.png" alt="fishy" width="200px" class="bg-primary">
+```
+
+<img src="img/fun-fish.png" alt="fishy" width="200px">
+<img src="img/fun-fish.png" alt="fishy" width="200px" class="bg-primary">
+
+Allowed attributes are equivalent to the `image` directive: src, alt, class, width, height and name.
+Any other attributes will be dropped.
+
+HTML image can also be used inline!
+
+I'm an inline image: <img src="img/fun-fish.png" height="20px">
+
+### Inline attributes
+
+:::{warning}
+This extension is currently experimental, and may change in future versions.
+:::
+
+By adding `"attrs_image"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+you can enable parsing of inline attributes for images.
+
+For example, the following Markdown:
+
+```md
+![image attrs](img/fun-fish.png){#imgattr .bg-primary width="100px" align=center}
+
+{ref}`a reference to the image <imgattr>`
+```
+
+will be parsed as:
+
+![image attrs](img/fun-fish.png){#imgattr .bg-primary width="100px" align=center}
+
+{ref}`a reference to the image <imgattr>`
+
+Inside the curly braces, the following syntax is possible:
+
+- `.foo` specifies `foo` as a class.
+  Multiple classes may be given in this way; they will be combined.
+- `#foo` specifies `foo` as an identifier.
+  An element may have only one identifier;
+  if multiple identifiers are given, the last one is used.
+- `key="value"` or `key=value` specifies a key-value attribute.
+    Quotes are not needed when the value consists entirely of
+    ASCII alphanumeric characters or `_` or `:` or `-`.
+    Backslash escapes may be used inside quoted values.
+- `%` begins a comment, which ends with the next `%` or the end of the attribute (`}`).
+
+(syntax/figures)=
+
+## Markdown Figures
+
+By adding `"colon_fence"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+we can combine the above two extended syntaxes,
+to create a fully Markdown compliant version of the `figure` directive named `figure-md`.
+
+:::{important}
+`myst_figure_enable` with the `figure` directive is deprecated and replaced by `myst_enable_extensions = ["colon_fence"]` and `figure-md`.
+:::
+
+The figure block must contain **only** two components; an image, in either Markdown or HTML syntax, and a single paragraph for the caption.
+
+The title is optional and taken as the reference target of the figure:
+
+```md
+:::{figure-md} fig-target
+:class: myclass
+
+<img src="img/fun-fish.png" alt="fishy" class="bg-primary mb-1" width="200px">
+
+This is a caption in **Markdown**
+:::
+```
+
+:::{figure-md} fig-target
+:class: myclass
+
+<img src="img/fun-fish.png" alt="fishy" class="bg-primary mb-1" width="200px">
+
+This is a caption in **Markdown**
+:::
+
+As we see here, the target we set can be referenced:
+
+```md
+[Go to the fish!](fig-target)
+```
+
+[Go to the fish!](fig-target)
+
+(syntax/html-admonition)=
+
+## HTML Admonitions
+
+By adding `"html_admonition"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+you can enable parsing of `<div class="admonition">` HTML blocks.
+These blocks will be converted internally to Sphinx admonition directives, and so will work correctly for all output formats.
+This is helpful when you care about viewing the "source" Markdown, such as in Jupyter Notebooks.
+
+If the first element within the `div` is `<div class="title">` or `<p class="title">`, then this will be set as the admonition title.
+All internal text (and the title) will be parsed as MyST-Markdown and all classes and an optional name will be passed to the admonition:
+
+```html
+<div class="admonition note" name="html-admonition" style="background: lightgreen; padding: 10px">
+<p class="title">This is the **title**</p>
+This is the *content*
+</div>
+```
+
+<div class="admonition note" name="html-admonition" style="background: lightgreen; padding: 10px">
+<div class="title">This is the **title**</div>
+This is the *content*
+</div>
+
+During the Sphinx render, both the `class` and `name` attributes will be used by Sphinx, but any other attributes like `style` will be discarded.
+
+:::{warning}
+There can be no empty lines in the block, otherwise they will be read as two separate blocks.
+If you want to use multiple paragraphs then they can be enclosed in `<p>`:
+
+```html
+<div class="admonition note">
+<p>Paragraph 1</p>
+<p>Paragraph 2</p>
+</div>
+```
+
+<div class="admonition note">
+<p>Paragraph 1</p>
+<p>Paragraph 2</p>
+</div>
+
+:::
+
+You can also nest HTML admonitions:
+
+```html
+<div class="admonition">
+<p>Some **content**</p>
+  <div class="admonition tip">
+  <div class="title">A *title*</div>
+  <p>Paragraph 1</p>
+  <p>Paragraph 2</p>
+  </div>
+</div>
+```
+
+<div class="admonition">
+<p>Some **content**</p>
+  <div class="admonition tip">
+  <div class="title">A *title*</div>
+  <p>Paragraph 1</p>
+  <p>Paragraph 2</p>
+  </div>
+</div>
+
+(syntax/amsmath)=
+
+## Direct LaTeX Math
+
+By adding `"amsmath"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+you can enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations.
+These top-level math environments will then be directly parsed:
+
+> equation, multline, gather, align, alignat, flalign, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, eqnarray.
+
+As expected, environments ending in `*` will not be numbered, for example:
+
+```latex
+\begin{gather*}
+a_1=b_1+c_1\\
+a_2=b_2+c_2-d_2+e_2
+\end{gather*}
+
+\begin{align}
+a_{11}& =b_{11}&
+  a_{12}& =b_{12}\\
+a_{21}& =b_{21}&
+  a_{22}& =b_{22}+c_{22}
+\end{align}
+```
+
+\begin{gather*}
+a_1=b_1+c_1\\
+a_2=b_2+c_2-d_2+e_2
+\end{gather*}
+
+\begin{align}
+a_{11}& =b_{11}&
+  a_{12}& =b_{12}\\
+a_{21}& =b_{21}&
+  a_{22}& =b_{22}+c_{22}
+\end{align}
+
+:::{note}
+`\labels` inside the environment are not currently identified, and so cannot be referenced.
+We hope to implement this in a future update (see [executablebooks/MyST-Parser#202](https://github.com/executablebooks/MyST-Parser/issues/202))!
+:::
+
+:::{important}
+See also [how Mathjax is configured with MyST-Parser](syntax/mathjax).
+:::
+
+This syntax will also work when nested in other block elements, like lists or quotes:
+
+```md
+- A list
+- \begin{gather*}
+  a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
+  \end{gather*}
+
+> A block quote
+> \begin{gather*}
+  a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
+  \end{gather*}
+```
+
+- A list
+- \begin{gather*}
+  a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
+  \end{gather*}
+
+> A block quote
+> \begin{gather*}
+  a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
+  \end{gather*}
diff --git a/docs/syntax/reference.md b/docs/syntax/reference.md
new file mode 100644
index 0000000..1e53b43
--- /dev/null
+++ b/docs/syntax/reference.md
@@ -0,0 +1,261 @@
+(syntax-tokens)=
+# Syntax tokens
+
+This page serves as a reference for the syntax that makes of MyST Markdown.
+
+:::{seealso}
+For more description and explanation of MyST syntax, see the [syntax guide](syntax.md).
+:::
+
+## Block (Multi-line) Tokens
+
+Block tokens span multiple lines of content. They are broken down into two sections:
+
+- {ref}`extended-block-tokens` contains *extra* tokens that are not in CommonMark.
+- {ref}`commonmark-block-tokens` contains CommonMark tokens that also work, for reference.
+
+:::{note}
+Because MyST markdown was inspired by functionality that exists in reStructuredText,
+we have shown equivalent rST syntax for many MyST markdown features below.
+:::
+
+(extended-block-tokens)=
+### Extended block tokens
+
+`````{list-table}
+:header-rows: 1
+:widths: 10 20 20
+
+* - Token
+  - Description
+  - Example
+* - FrontMatter
+  - A YAML block at the start of the document enclosed by `---`
+  - ```yaml
+    ---
+    key: value
+    ---
+    ```
+* - Directives
+  - enclosed in 3 or more backticks followed by the directive name wrapped
+  in curly brackets `{}`. See {ref}`syntax/directives` for more details.
+  - ````md
+    ```{directive}
+    :option: value
+
+    content
+    ```
+    ````
+* - Math
+  - `$$` (default) or `\[`...`\]` characters wrapping multi-line math, or even direct [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations (optional).
+  See {ref}`syntax/math` for more information.
+  - ```latex
+    $$
+    a=1
+    $$
+    ```
+* - Table
+  - Standard markdown table style, with pipe separation.
+  - ```md
+    | a    | b    |
+    | :--- | ---: |
+    | c    | d    |
+    ```
+* - LineComment
+  - A commented line. See {ref}`syntax/comments` for more information.
+  - ```latex
+    % this is a comment
+    ```
+* - BlockBreak
+  - Define blocks of text. See {ref}`syntax/blockbreaks` for more information.
+  - ```md
+    +++ {"meta": "data"}
+    ```
+* - Footnote
+  - A definition for a referencing footnote, that is placed at the bottom of the document.
+   See {ref}`syntax/footnotes` for more details.
+  - ```md
+    [^ref]: Some footnote text
+    ```
+* - Admonitions (optional)
+  - An alternative approach for admonition style directives only, which has the benefit of allowing the content to be rendered in standard markdown editors.
+    See [admonition directives](syntax/admonitions) for more details.
+  - ````md
+    :::{note}
+    *content*
+    :::
+    ````
+`````
+
+(commonmark-block-tokens)=
+### CommonMark tokens
+
+`````{list-table}
+:header-rows: 1
+:widths: 10 20 20
+
+* - Token
+  - Description
+  - Example
+* - HTMLBlock
+  - Any valid HTML (rendered in HTML output only)
+  - ```html
+    <p>some text</p>
+    ```
+* - BlockCode
+  - indented text (4 spaces or a tab)
+  - ```md
+        included as literal *text*
+    ```
+* - Heading
+  - Level 1-6 headings, denoted by number of `#`
+  - ```md
+    ### Heading level 3
+    ```
+* - SetextHeading
+  - Underlined header (using multiple `=` or `-`)
+  - ```md
+    Header
+    ======
+    ```
+* - Quote
+  - Quoted text
+  - ```md
+    > this is a quote
+    ```
+* - CodeFence
+  - Enclosed in 3 or more `` ` `` or `~` with an optional language name.
+    See {ref}`syntax/code-blocks` for more information.
+  - ````md
+    ```python
+    print('this is python')
+    ```
+    ````
+* - ThematicBreak
+  - Creates a horizontal line in the output
+  - ```md
+    ---
+    ```
+* - List
+  - bullet points or enumerated.
+  - ```md
+    - item
+      - nested item
+    1. numbered item
+    ```
+* - LinkDefinition
+  -  A substitution for an inline link, which can have a reference target (no spaces), and an optional title (in `"`)
+  - ```md
+    [key]: https://www.google.com "a title"
+    ```
+* - Paragraph
+  - General inline text
+  - ```md
+    any *text*
+    ```
+`````
+
+## Span (Inline) Tokens
+
+Span (or inline) tokens are defined on a single line of content. They are broken down into two
+sections below:
+
+- {ref}`extended-span-tokens` contains *extra* tokens that are not in CommonMark.
+- {ref}`commonmark-span-tokens` contains CommonMark tokens that also work, for reference.
+
+(extended-span-tokens)=
+### Extended inline tokens
+
+`````{list-table}
+:header-rows: 1
+:widths: 10 20 20
+
+* - Token
+  - Description
+  - Example
+* - Role
+  - See {ref}`syntax/roles` for more information.
+  - ```md
+    {rolename}`interpreted text`
+    ```
+* - Target
+  - Precedes element to target, e.g. header. See
+  {ref}`syntax/targets` for more information.
+  - ```md
+    (target)=
+    ```
+* - Math
+  - `$` (default) or `\(`...`\)` enclosed math. See
+  {ref}`syntax/math` for more information.
+  - ```latex
+    $a=1$ or $$a=1$$
+    ```
+* - FootReference
+  - Reference a footnote. See {ref}`syntax/footnotes` for more details.
+  - ```md
+    [^abc]
+    ```
+`````
+
+(commonmark-span-tokens)=
+### CommonMark inline tokens
+
+`````{list-table}
+:header-rows: 1
+:widths: 10 20 20
+
+* - Token
+  - Description
+  - Example
+* - HTMLSpan
+  - Any valid HTML (rendered in HTML output only)
+  - ```html
+    <p>some text</p>
+    ```
+* - EscapeSequence
+  - Escaped symbols (to avoid them being interpreted as other syntax elements)
+  - ```md
+    \*
+    ```
+* - AutoLink
+  - Link that is shown in final output
+  - ```md
+    <http://www.google.com>
+    ```
+* - InlineCode
+  - Literal text
+  - ```md
+    `a=1`
+    ```
+* - LineBreak
+  - Soft or hard (ends with spaces or backslash)
+  - ```md
+    A hard break\
+    ```
+* - Image
+  - Link to an image.
+    You can also use HTML syntax, to include image size etc, [see here](syntax/images) for details
+  - ```md
+    ![alt](src "title")
+    ```
+* - Link
+  - Reference `LinkDefinitions`. See {ref}`syntax/referencing` for more details.
+  - ```md
+    [text](target "title") or [text][key]
+    ```
+* - Strong
+  - Bold text
+  - ```md
+    **strong**
+    ```
+* - Emphasis
+  - Italic text
+  - ```md
+    *emphasis*
+    ```
+* - RawText
+  - Any text
+  - ```md
+    any text
+    ```
+`````
diff --git a/docs/syntax/roles-and-directives.md b/docs/syntax/roles-and-directives.md
new file mode 100644
index 0000000..4b3d80a
--- /dev/null
+++ b/docs/syntax/roles-and-directives.md
@@ -0,0 +1,421 @@
+(roles-directives)=
+
+# Roles and Directives
+
+Roles and directives provide a way to extend the syntax of MyST in an unbound manner,
+by interpreting a chuck of text as a specific type of markup, according to its name.
+
+Mostly all [docutils roles](https://docutils.sourceforge.io/docs/ref/rst/roles.html), [docutils directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html), [sphinx roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html), or [sphinx directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) can be used in MyST.
+
+## Syntax
+
+(syntax/directives)=
+
+### Directives - a block-level extension point
+
+Directives syntax is defined with triple-backticks and curly-brackets.
+It is effectively a Markdown code fence with curly brackets around the language, and a directive name in place of a language name.
+Here is the basic structure:
+
+`````{list-table}
+---
+header-rows: 1
+---
+* - MyST
+  - reStructuredText
+* - ````md
+    ```{directivename} arguments
+    ---
+    key1: val1
+    key2: val2
+    ---
+    This is
+    directive content
+    ```
+    ````
+  - ```rst
+    .. directivename:: arguments
+       :key1: val1
+       :key2: val2
+
+       This is
+       directive content
+    ```
+`````
+
+For example, the following code:
+
+````md
+```{admonition} This is my admonition
+This is my note
+```
+````
+
+Will generate this admonition:
+
+```{admonition} This is my admonition
+This is my note
+```
+
+#### Parameterizing directives
+
+For directives that take parameters as input, there are two ways to parameterize them.
+In each case, the options themselves are given as `key: value` pairs. An example of
+each is shown below:
+
+**Using YAML frontmatter**. A block of YAML front-matter just after the
+first line of the directive will be parsed as options for the directive. This needs to be
+surrounded by `---` lines. Everything in between will be parsed by YAML and
+passed as keyword arguments to your directive. For example:
+
+````md
+```{code-block} python
+---
+lineno-start: 10
+emphasize-lines: 1, 3
+caption: |
+    This is my
+    multi-line caption. It is *pretty nifty* ;-)
+---
+a = 2
+print('my 1st line')
+print(f'my {a}nd line')
+```
+````
+
+```{code-block} python
+---
+lineno-start: 10
+emphasize-lines: 1, 3
+caption: |
+    This is my
+    multi-line caption. It is *pretty nifty* ;-)
+---
+a = 2
+print('my 1st line')
+print(f'my {a}nd line')
+```
+
+**Short-hand options with `:` characters**. If you only need one or two options for your
+directive and wish to save lines, you may also specify directive options as a collection
+of lines just after the first line of the directive, each preceding with `:`. Then the
+leading `:` is removed from each line, and the rest is parsed as YAML.
+
+For example:
+
+````md
+```{code-block} python
+:lineno-start: 10
+:emphasize-lines: 1, 3
+
+a = 2
+print('my 1st line')
+print(f'my {a}nd line')
+```
+````
+
+(syntax/directives/parsing)=
+
+#### How directives parse content
+
+Some directives parse the content that is in their content block.
+MyST parses this content **as Markdown**.
+
+This means that MyST markdown can be written in the content areas of any directives written in MyST markdown. For example:
+
+````md
+```{admonition} My markdown link
+Here is [markdown link syntax](https://jupyter.org)
+```
+````
+
+```{admonition} My markdown link
+Here is [markdown link syntax](https://jupyter.org)
+```
+
+As a short-hand for directives that require no arguments, and when no parameter options are used (see below),
+you may start the content directly after the directive name.
+
+````md
+```{note} Notes require **no** arguments, so content can start here.
+```
+````
+
+```{note} Notes require **no** arguments, so content can start here.
+```
+
+For special cases, MySt also offers the `eval-rst` directive.
+This will parse the content **as ReStructuredText**:
+
+````md
+```{eval-rst}
+.. figure:: img/fun-fish.png
+  :width: 100px
+  :name: rst-fun-fish
+
+  Party time!
+
+A reference from inside: :ref:`rst-fun-fish`
+
+A reference from outside: :ref:`syntax/directives/parsing`
+```
+````
+
+```{eval-rst}
+.. figure:: img/fun-fish.png
+  :width: 100px
+  :name: rst-fun-fish
+
+  Party time!
+
+A reference from inside: :ref:`rst-fun-fish`
+
+A reference from outside: :ref:`syntax/directives/parsing`
+```
+
+Note how the text is integrated into the rest of the document, so we can also reference [party fish](rst-fun-fish) anywhere else in the documentation.
+
+#### Nesting directives
+
+You can nest directives by ensuring that the tick-lines corresponding to the
+outermost directive are longer than the tick-lines for the inner directives.
+For example, nest a warning inside a note block like so:
+
+`````md
+````{note}
+The next info should be nested
+```{warning}
+Here's my warning
+```
+````
+`````
+
+Here's how it looks rendered:
+
+````{note}
+The next info should be nested
+```{warning}
+Here's my warning
+```
+````
+
+You can indent inner-code fences, so long as they aren't indented by more than 3 spaces.
+Otherwise, they will be rendered as "raw code" blocks:
+
+`````md
+````{note}
+The warning block will be properly-parsed
+
+   ```{warning}
+   Here's my warning
+   ```
+
+But the next block will be parsed as raw text
+
+    ```{warning}
+    Here's my raw text warning that isn't parsed...
+    ```
+````
+`````
+
+````{note}
+The warning block will be properly-parsed
+
+   ```{warning}
+   Here's my warning
+   ```
+
+But the next block will be parsed as raw text
+
+    ```{warning}
+    Here's my raw text warning that isn't parsed...
+    ```
+````
+
+This can really be abused if you'd like ;-)
+
+``````{note}
+The next info should be nested
+`````{warning}
+Here's my warning
+````{admonition} Yep another admonition
+```python
+# All this fuss was about this boring python?!
+print('yep!')
+```
+````
+`````
+``````
+
+#### Markdown-friendly directives
+
+Want to use syntax that renders correctly in standard Markdown editors?
+See [the extended syntax option](syntax/colon_fence).
+
+```md
+:::{note}
+This text is **standard** *Markdown*
+:::
+```
+
+:::{note}
+This text is **standard** *Markdown*
+:::
+
+(syntax/roles)=
+
+### Roles - an in-line extension point
+
+Roles are similar to directives - they allow you to define arbitrary new functionality, but they are used *in-line*.
+To define an in-line role, use the following form:
+
+````{list-table}
+---
+header-rows: 1
+---
+* - MyST
+  - reStructuredText
+* - ````md
+    {role-name}`role content`
+    ````
+  - ```rst
+    :role-name:`role content`
+    ```
+````
+
+For example, the following code:
+
+```md
+Since Pythagoras, we know that {math}`a^2 + b^2 = c^2`
+```
+
+Becomes:
+
+Since Pythagoras, we know that {math}`a^2 + b^2 = c^2`
+
+You can use roles to do things like reference equations and other items in
+your book. For example:
+
+````md
+```{math} e^{i\pi} + 1 = 0
+---
+label: euler
+---
+```
+
+Euler's identity, equation {math:numref}`euler`, was elected one of the
+most beautiful mathematical formulas.
+````
+
+Becomes:
+
+```{math} e^{i\pi} + 1 = 0
+---
+label: euler
+---
+```
+
+Euler's identity, equation {math:numref}`euler`, was elected one of the
+most beautiful mathematical formulas.
+
+#### How roles parse content
+
+The content of roles is parsed differently depending on the role that you've used.
+Some roles expect inputs that will be used to change functionality. For example,
+the `ref` role will assume that input content is a reference to some other part of the
+site. However, other roles may use the MyST parser to parse the input as content.
+
+Some roles also **extend their functionality** depending on the content that you pass.
+For example, following the `ref` example above, if you pass a string like this:
+`Content to display <myref>`, then the `ref` will display `Content to display` and use
+`myref` as the reference to look up.
+
+How roles parse this content depends on the author that created the role.
+
+## Common roles and directives
+
+:::{admonition} {material-regular}`engineering;1.5rem;sd-mr-1` Currently Under Construction
+:class: no-icon
+Check back for more...
+:::
+
+### ToC Trees
+
+```{doc-directive} contents
+Insert a table of contents tree of the documents headings.
+```
+
+```{doc-directive} toctree
+Inserts a Sphinx "Table of Contents" tree, containing a list of (relative) child document paths.
+```
+
+### Admonitions
+
+```{doc-directive} admonition
+Create a generic "callout" box, containing the content.
+```
+
+```{doc-directive} note
+Create a "callout" box, specific to notes, containing the content.
+```
+
+Other admonitions (same structure as `note`): `attention`, `caution`, `danger`, `error`, `hint`, `important`, `tip`, `warning`.
+
+Sphinx only: `deprecated`, `versionadded`, `versionchanged`.
+
+### Images and Figures
+
+```{doc-directive} image
+Insert an image, from a (relative) path or URL.
+```
+
+```{doc-directive} figure
+Insert an image, from a (relative) path or URL,
+with a caption (first paragraph), and optional legend (subsequent content).
+```
+
+```{doc-directive} table
+Insert a (MyST) table with a caption.
+```
+
+### Tables
+
+```{doc-directive} list-table
+Create a table from data in a uniform two-level bullet list.
+```
+
+```{doc-directive} csv-table
+Create a table from CSV (comma-separated values) data.
+```
+
+### Code
+
+```{doc-directive} code-block
+Syntax highlight a block of code, according to the language.
+```
+
+(syntax/roles/special)=
+
+### MyST only
+
+This section contains information about special roles and directives that come bundled with the MyST Parser Sphinx extension.
+
+#### Insert the date and reading time
+
+```{versionadded} 0.14.0
+The `sub-ref` role and word counting.
+```
+
+You may insert the "last updated" date and estimated reading time into your document via substitution definitions, which can be accessed *via* the `sub-ref` role.
+
+For example:
+
+```markdown
+> {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
+```
+
+> {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
+
+`today` is replaced by either the date on which the document is parsed, with the format set by [`today_fmt`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-today_fmt), or the `today` variable if set in the configuration file.
+
+The reading speed is computed using the `myst_words_per_minute` configuration (see the [Sphinx configuration options](sphinx/config-options)).
diff --git a/docs/syntax/syntax.md b/docs/syntax/syntax.md
new file mode 100644
index 0000000..31c7f8d
--- /dev/null
+++ b/docs/syntax/syntax.md
@@ -0,0 +1,491 @@
+(syntax/core)=
+
+# Core Syntax
+
+## Introduction
+
+MyST is a strict superset of the [CommonMark syntax specification](https://spec.commonmark.org/).
+It adds features focussed on scientific and technical documentation authoring, as detailed below.
+
+In addition, the roles and directives syntax provide inline/block-level extension points for plugins.
+This is detailed further in the [Roles and Directives](roles-directives) section.
+
+:::{seealso}
+The [syntax token reference tables](syntax-tokens)
+:::
+
+(syntax/commonmark)=
+
+## CommonMark
+
+The [CommonMark syntax specification](https://spec.commonmark.org/) details the full set of syntax rules.
+Here we provide a summary of most features:
+
+Element         | Syntax
+--------------- | -------------------------------------------
+Heading         | `# H1` to `###### H6`
+Bold            | `**bold**`
+Italic          | `*italic*`
+Inline Code     | `` `code` ``
+Autolink        | `<https://www.example.com>`
+URL Link        | `[title](https://www.example.com)`
+Image           | `![alt](https://www.example.com/image.png)`
+Reference Link  | `[title][link]`
+Link Definition | `[link]: https://www.example.com`
+Thematic break  | `---`
+Blockquote      | `> quote`
+Ordered List    | `1. item`
+Unordered List  | `- item`
+Code Fence      | opening ```` ```lang ```` to closing ```` ``` ````
+
+(syntax/frontmatter)=
+
+## Front Matter
+
+This is a [YAML](https://en.wikipedia.org/wiki/YAML) block at the start of the document, as used for example in [jekyll](https://jekyllrb.com/docs/front-matter/).
+The document should start with three or more `---` markers, and YAML is parsed until a closing `---` marker is found:
+
+```yaml
+---
+key1: value
+key2: [value1, value2]
+key3:
+  subkey1: value
+---
+```
+
+:::{seealso}
+Top-matter is also used for the [substitution syntax extension](syntax/substitutions),
+and can be used to store information for blog posting (see [ablog's myst-parser support](https://ablog.readthedocs.io/en/latest/manual/markdown/)).
+:::
+
+### Setting a title
+
+```{versionadded} 0.17.0
+```
+
+If `myst_title_to_header` is set to `True`, and a `title` key is present in the front matter,
+then the title will be used as the document's header (parsed as Markdown).
+For example:
+
+```md
+---
+title: My Title with *emphasis*
+---
+```
+
+would be equivalent to:
+
+```md
+# My Title with *emphasis*
+```
+
+(syntax/html_meta)=
+
+### Setting HTML Metadata
+
+The front-matter can contain the special key `html_meta`; a dict with data to add to the generated HTML as [`<meta>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta).
+This is equivalent to using the [RST `meta` directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#html-metadata).
+
+HTML metadata can also be added globally in the `conf.py` *via* the `myst_html_meta` variable, in which case it will be added to all MyST documents.
+For each document, the `myst_html_meta` dict will be updated by the document level front-matter `html_meta`, with the front-matter taking precedence.
+
+::::{tab-set}
+:::{tab-item} Sphinx Configuration
+
+```python
+language = "en"
+myst_html_meta = {
+    "description lang=en": "metadata description",
+    "description lang=fr": "description des métadonnées",
+    "keywords": "Sphinx, MyST",
+    "property=og:locale":  "en_US"
+}
+```
+
+:::
+
+:::{tab-item} MyST Front-Matter
+
+```yaml
+---
+myst:
+  html_meta:
+    "description lang=en": "metadata description"
+    "description lang=fr": "description des métadonnées"
+    "keywords": "Sphinx, MyST"
+    "property=og:locale": "en_US"
+---
+```
+
+:::
+
+:::{tab-item} RestructuredText
+
+```restructuredtext
+.. meta::
+   :description lang=en: metadata description
+   :description lang=fr: description des métadonnées
+   :keywords: Sphinx, MyST
+   :property=og:locale: en_US
+```
+
+:::
+
+:::{tab-item} HTML Output
+
+```html
+<html lang="en">
+  <head>
+    <meta content="metadata description" lang="en" name="description" xml:lang="en" />
+    <meta content="description des métadonnées" lang="fr" name="description" xml:lang="fr" />
+    <meta name="keywords" content="Sphinx, MyST">
+    <meta content="en_US" property="og:locale" />
+```
+
+:::
+::::
+
+(syntax/comments)=
+
+## Comments
+
+You may add comments by putting the `%` character at the beginning of a line. This will
+prevent the line from being parsed into the output document.
+
+For example, this code:
+
+```md
+% my comment
+```
+
+Is below, but it won't be parsed into the document.
+
+% my comment
+
+````{important}
+Since comments are a block-level entity, they will terminate the previous block.
+In practical terms, this means that the following lines
+will be broken up into two paragraphs, resulting in a new line between them:
+
+```
+a line
+% a comment
+another line
+```
+
+a line
+% a comment
+another line
+````
+
+:::{tip}
+Comments are equivalent to the RST syntax: `.. my comment`.
+:::
+
+(syntax/blockbreaks)=
+
+## Block Breaks
+
+You may add a block break by putting `+++` at the beginning of a line.
+This constuct's intended use case is for mapping to cell based document formats,
+like [jupyter notebooks](https://jupyter.org/),
+to indicate a new text cell. It will not show up in the rendered text,
+but is stored in the internal document structure for use by developers.
+
+For example, this code:
+
+```md
++++ some text
+```
+
+Is below, but it won't be parsed into the document.
+
++++
+
+(syntax/referencing)=
+
+## Markdown Links and Referencing
+
+Markdown links are of the form: `[text](link)`.
+
+If you set the configuration `myst_all_links_external = True` (`False` by default),
+then all links will be treated simply as "external" links.
+For example, in HTML outputs, `[text](link)` will be rendered as `<a href="link">text</a>`.
+
+Otherwise, links will only be treated as "external" links if they are prefixed with a scheme,
+configured with `myst_url_schemes` (by default, `http`, `https`, `ftp`, or `mailto`).
+For example, `[example.com](https://example.com)` becomes [example.com](https://example.com).
+
+:::{note}
+The `text` will be parsed as nested Markdown, for example `[here's some *emphasised text*](https://example.com)` will be parsed as [here's some *emphasised text*](https://example.com).
+:::
+
+For "internal" links, myst-parser in Sphinx will attempt to resolve the reference to either a relative document path, or a cross-reference to a target (see [](syntax/targets)):
+
+- `[this doc](syntax.md)` will link to a rendered source document: [this doc](syntax.md)
+  - This is similar to `` {doc}`this doc <syntax>` ``; {doc}`this doc <syntax>`, but allows for document extensions, and parses nested Markdown text.
+- `[example text](example.txt)` will link to a non-source (downloadable) file: [example text](example.txt)
+  - The linked document itself will be copied to the build directory.
+  - This is similar to `` {download}`example text <example.txt>` ``; {download}`example text <example.txt>`, but parses nested Markdown text.
+- `[reference](syntax/referencing)` will link to an internal cross-reference: [reference](syntax/referencing)
+  - This is similar to `` {any}`reference <syntax/referencing>` ``; {any}`reference <syntax/referencing>`, but parses nested Markdown text.
+  - You can limit the scope of the cross-reference to specific [sphinx domains](sphinx:domain), by using the `myst_ref_domains` configuration.
+    For example, `myst_ref_domains = ("std", "py")` will only allow cross-references to `std` and `py` domains.
+
+Additionally, only if [](syntax/header-anchors) are enabled, then internal links to document headers can be used.
+For example `[a header](syntax.md#markdown-links-and-referencing)` will link to a header anchor: [a header](syntax.md#markdown-links-and-referencing).
+
+(syntax/targets)=
+
+## Targets and Cross-Referencing
+
+Targets are used to define custom anchors that you can refer to elsewhere in your
+documentation. They generally go before section titles so that you can easily refer
+to them.
+
+:::{tip}
+
+If you'd like to *automatically* generate targets for each of your section headers,
+check out the [](syntax/header-anchors) section of extended syntaxes.
+
+:::
+
+Target headers are defined with this syntax:
+
+```md
+(header_target)=
+```
+
+They can then be referred to with the [ref inline role](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref):
+
+```md
+{ref}`header_target`
+```
+
+By default, the reference will use the text of the target (such as the section title), but also you can directly specify the text:
+
+```md
+{ref}`my text <header_target>`
+```
+
+For example, see this ref: {ref}`syntax/targets`, and here's a ref back to the top of this page: {ref}`my text <syntax/core>`.
+
+Alternatively using the markdown syntax:
+
+```md
+[my text](header_target)
+```
+
+is equivalent to using the [any inline role](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-any):
+
+```md
+{any}`my text <header_target>`
+```
+
+but can also accept "nested" syntax (like bold text) and will recognise document paths that include extensions (e.g. `syntax/syntax` or `syntax/syntax.md`)
+
+Using the same example, see this ref: [](syntax/targets), here is a reference back to the top of
+this page: [my text with **nested** $\alpha$ syntax](syntax/core), and here is a reference to another page (`[](../intro.md)`): [](../intro.md).
+
+```{note}
+If you wish to have the target's title inserted into your text, you can
+leave the "text" section of the markdown link empty. For example, this
+markdown: `[](syntax.md)` will result in: [](syntax.md).
+```
+
+(syntax/code-blocks)=
+## Code syntax highlighting
+
+Code blocks contain a language identifier, which is used to determine the language of the code.
+This language is used to determine the syntax highlighting, using an available [pygments lexer](https://pygments.org/docs/lexers/).
+
+````markdown
+```python
+from a import b
+c = "string"
+```
+````
+
+```python
+from a import b
+c = "string"
+```
+
+You can create and register your own lexer, using the [`pygments.lexers` entry point](https://pygments.org/docs/plugins/#register-plugins),
+or within a sphinx extension, with the [`app.add_lexer` method](sphinx:sphinx.application.Sphinx.add_lexer).
+
+Using the `myst_number_code_blocks` configuration option, you can also control whether code blocks are numbered by line.
+For example, using `myst_number_code_blocks = ["typescript"]`:
+
+```typescript
+type MyBool = true | false;
+
+interface User {
+  name: string;
+  id: number;
+}
+```
+
+### Show backticks inside raw markdown blocks
+
+If you'd like to show backticks inside of your markdown, you can do so by nesting them
+in backticks of a greater length. Markdown will treat the outer-most backticks as the
+edges of the "raw" block and everything inside will show up. For example:
+
+``` `` `hi` `` ```  will be rendered as: `` `hi` ``
+
+and
+
+`````
+````
+```
+hi
+```
+````
+`````
+
+will be rendered as:
+
+````
+```
+hi
+```
+````
+
+## Tables
+
+Tables can be written using the standard [Github Flavoured Markdown syntax](https://github.github.com/gfm/#tables-extension-):
+
+```md
+| foo | bar |
+| --- | --- |
+| baz | bim |
+```
+
+| foo | bar |
+| --- | --- |
+| baz | bim |
+
+Cells in a column can be aligned using the `:` character:
+
+```md
+| left | center | right |
+| :--- | :----: | ----: |
+| a    | b      | c     |
+```
+
+| left | center | right |
+| :--- | :----: | ----: |
+| a    | b      | c     |
+
+:::{note}
+
+Text is aligned by assigning `text-left`, `text-center`, or `text-right` to the cell.
+It is then necessary for the theme you are using to include the appropriate css styling.
+
+```html
+<table class="colwidths-auto table">
+  <thead>
+    <tr><th class="text-left head"><p>left</p></th></tr>
+  </thead>
+  <tbody>
+    <tr><td class="text-left"><p>a</p></td></tr>
+  </tbody>
+</table>
+```
+
+:::
+
+## Images
+
+MyST provides a few different syntaxes for including images in your documentation.
+
+The standard Markdown syntax is:
+
+```md
+![fishy](img/fun-fish.png)
+```
+
+![fishy](img/fun-fish.png)
+
+But you can also enable extended image syntaxes, to control attributes like width and captions.
+See the [extended image syntax guide](syntax/images).
+
+(syntax/footnotes)=
+## Footnotes
+
+Footnotes use the [pandoc specification](https://pandoc.org/MANUAL.html#footnotes).
+Their labels **start with `^`** and can then be any alphanumeric string (no spaces), which is case-insensitive.
+
+- If the label is an integer, then it will always use that integer for the rendered label (i.e. they are manually numbered).
+- For any other labels, they will be auto-numbered in the order which they are referenced, skipping any manually numbered labels.
+
+All footnote definitions are collected, and displayed at the bottom of the page (in the order they are referenced).
+Note that un-referenced footnote definitions will not be displayed.
+
+```md
+- This is a manually-numbered footnote reference.[^3]
+- This is an auto-numbered footnote reference.[^myref]
+
+[^myref]: This is an auto-numbered footnote definition.
+[^3]: This is a manually-numbered footnote definition.
+```
+
+- This is a manually-numbered footnote reference.[^3]
+- This is an auto-numbered footnote reference.[^myref]
+
+[^myref]: This is an auto-numbered footnote definition.
+[^3]: This is a manually-numbered footnote definition.
+
+Any preceding text after a footnote definitions, which is
+indented by four or more spaces, will also be included in the footnote definition, and the text is rendered as MyST Markdown, e.g.
+
+```md
+A longer footnote definition.[^mylongdef]
+
+[^mylongdef]: This is the _**footnote definition**_.
+
+    That continues for all indented lines
+
+    - even other block elements
+
+    Plus any preceding unindented lines,
+that are not separated by a blank line
+
+This is not part of the footnote.
+```
+
+A longer footnote definition.[^mylongdef]
+
+[^mylongdef]: This is the _**footnote definition**_.
+
+    That continues for all indented lines
+
+    - even other block elements
+
+    Plus any subsequent unindented lines,
+that are not separated by a blank line
+
+This is not part of the footnote.
+
+````{important}
+Although footnote references can be used just fine within directives, e.g.[^myref],
+it is recommended that footnote definitions are not set within directives,
+unless they will only be referenced within that same directive:
+
+```md
+[^other]
+
+[^other]: A definition within a directive
+```
+
+[^other]
+
+[^other]: A definition within a directive
+
+This is because, in the current implementation, they may not be available to reference in text above that particular directive.
+````
+
+By default, a transition line (with a `footnotes` class) will be placed before any footnotes.
+This can be turned off by adding `myst_footnote_transition = False` to the config file.