From 05df1a3343e3a68309dbe6816cd0ccbd86cdbd83 Mon Sep 17 00:00:00 2001
From: "Matthias C. M. Troffaes" <matthias.troffaes@gmail.com>
Date: Mon, 22 Aug 2022 14:00:33 +0100
Subject: [PATCH] Document markdown syntax for myst (#311)

Closes #310.
---
 CHANGELOG.rst |  2 ++
 doc/usage.rst | 15 +++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 24b169c0..c9dd8fd1 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -17,6 +17,8 @@
 * Suppress LaTeX url commands in tooltips (see issue #305, reported by
   1kastner).
 
+* Document Markdown syntax for MyST (suggested by jacopok, see issue #310).
+
 2.4.2 (10 April 2022)
 ---------------------
 
diff --git a/doc/usage.rst b/doc/usage.rst
index f2af02e7..35cf453a 100644
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -364,6 +364,21 @@ Roles and Directives
    created for references that do not yet have a footnote earlier in the
    document.
 
+Markdown Syntax Using MyST
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you use the MyST parser, all roles and directives are also available in
+Markdown syntax. For example:
+
+.. code-block:: markdown
+
+   See {cite:p}`1987:nelson` for an introduction to non-standard analysis.
+
+   ```{bibliography} references.bib
+   ```
+
+.. seealso:: https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html
+
 Advanced Features
 -----------------