From 8f3d5a713aa00f110f56a644df592a5f7ac76e6d Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Mon, 10 Aug 2020 23:14:27 +0100
Subject: [PATCH 01/12] =?UTF-8?q?=E2=80=BC=EF=B8=8F=20BREAKING:=20Refactor?=
 =?UTF-8?q?=20parser=20config=20options?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Parser configuration options are now set as separate variables, rather than a single dict
---
 myst_parser/__init__.py                       | 26 ++++++++++++++++-
 myst_parser/sphinx_parser.py                  | 28 ++++---------------
 tests/test_renderers/test_myst_refs.py        |  8 +++---
 .../sourcedirs/conf_values/conf.py            |  3 +-
 4 files changed, 36 insertions(+), 29 deletions(-)

diff --git a/myst_parser/__init__.py b/myst_parser/__init__.py
index 103ac15e..e854f833 100644
--- a/myst_parser/__init__.py
+++ b/myst_parser/__init__.py
@@ -8,7 +8,31 @@ def setup(app):
 
     app.add_source_suffix(".md", "markdown")
     app.add_source_parser(MystParser)
-    app.add_config_value("myst_config", {}, "env")
     app.add_post_transform(MystReferenceResolver)
 
+    app.add_config_value("myst_math_delimiters", "dollars", "env")
+    app.add_config_value("myst_disable_syntax", (), "env")
+
+    app.connect("config-inited", validate_config)
+
     return {"version": __version__, "parallel_read_safe": True}
+
+
+def validate_config(app, config):
+    from sphinx.util import logging
+
+    logger = logging.getLogger(__name__)
+
+    # TODO raise errors or log error with sphinx?
+    try:
+        for s in config.myst_disable_syntax:
+            assert isinstance(s, str)
+    except (AssertionError, TypeError):
+        logger.error("myst_disable_syntax config option not of type List[str]")
+
+    allowed_delimiters = ["brackets", "kramdown", "dollars", "julia"]
+    if config.myst_math_delimiters not in allowed_delimiters:
+        logger.error(
+            "myst_math_delimiters config option not an allowed name: "
+            + f"{allowed_delimiters}"
+        )
diff --git a/myst_parser/sphinx_parser.py b/myst_parser/sphinx_parser.py
index 20b49918..feadf54b 100644
--- a/myst_parser/sphinx_parser.py
+++ b/myst_parser/sphinx_parser.py
@@ -16,15 +16,13 @@
 
 
 class MystParser(Parser):
-    """Docutils parser for CommonMark + Math + Tables + RST Extensions """
+    """Docutils parser for Markedly Structured Text (MyST)."""
 
     supported = ("md", "markdown", "myst")
     translate_section_name = None
 
     default_config = {
         "known_url_schemes": None,
-        "disable_syntax": (),
-        "math_delimiters": "dollars",
     }
 
     # these specs are copied verbatim from the docutils RST parser
@@ -181,31 +179,15 @@ def parse(self, inputstring: str, document: nodes.document):
         :param document: The root docutils node to add AST elements to
         """
         self.config = self.default_config.copy()
-        try:
-            new_cfg = document.settings.env.config.myst_config
-            self.config.update(new_cfg)
-        except AttributeError:
-            pass
-
-        # TODO raise errors or log error with sphinx?
-        try:
-            for s in self.config["disable_syntax"]:
-                assert isinstance(s, str)
-        except (AssertionError, TypeError):
-            raise TypeError("disable_syntax not of type List[str]")
-
-        allowed_delimiters = ["brackets", "kramdown", "dollars", "julia"]
-        if not self.config["math_delimiters"] in allowed_delimiters:
-            raise ValueError(
-                f"math_delimiters config not an allowed name: {allowed_delimiters}"
-            )
+        # note myst sphinx config values are validated at config-inited
+        sphinx_config = document.settings.env.app.config
 
         to_docutils(
             inputstring,
             options=self.config,
             document=document,
-            disable_syntax=self.config["disable_syntax"] or [],
-            math_delimiters=self.config["math_delimiters"],
+            disable_syntax=sphinx_config.myst_disable_syntax,
+            math_delimiters=sphinx_config.myst_math_delimiters,
         )
 
 
diff --git a/tests/test_renderers/test_myst_refs.py b/tests/test_renderers/test_myst_refs.py
index 615f6e34..9e64af90 100644
--- a/tests/test_renderers/test_myst_refs.py
+++ b/tests/test_renderers/test_myst_refs.py
@@ -2,7 +2,6 @@
 from sphinx.errors import SphinxWarning
 
 from myst_parser.sphinx_renderer import mock_sphinx_env
-from myst_parser.myst_refs import MystReferenceResolver
 from myst_parser.sphinx_parser import parse
 
 import pytest
@@ -24,10 +23,11 @@
 def test_parse(test_name, text, should_warn, file_regression):
 
     with mock_sphinx_env(
-        srcdir="root", with_builder=True, raise_on_warning=True
+        conf={"extensions": ["myst_parser"]},
+        srcdir="root",
+        with_builder=True,
+        raise_on_warning=True,
     ) as app:  # type: Sphinx
-        app.add_post_transform(MystReferenceResolver)
-        app.add_source_suffix(".md", "markdown")
         document = parse(app, text, docname="index")
         if should_warn:
             with pytest.raises(SphinxWarning):
diff --git a/tests/test_sphinx/sourcedirs/conf_values/conf.py b/tests/test_sphinx/sourcedirs/conf_values/conf.py
index 1a66017a..d2b0874e 100644
--- a/tests/test_sphinx/sourcedirs/conf_values/conf.py
+++ b/tests/test_sphinx/sourcedirs/conf_values/conf.py
@@ -1,3 +1,4 @@
 extensions = ["myst_parser"]
 exclude_patterns = ["_build"]
-myst_config = {"disable_syntax": ["emphasis"], "math_delimiters": "brackets"}
+myst_disable_syntax = ("emphasis",)
+myst_math_delimiters = "brackets"

From 498b55143a9e4f23615c4512e132df2cf6496929 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 02:36:39 +0100
Subject: [PATCH 02/12] =?UTF-8?q?=E2=9C=A8NEW:=20amsmath=20integration?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Use `myst_amsmath_enable = True` in the conf.py to directly parse [amsmath](https://ctan.org/pkg/amsmath) LaTeX
---
 myst_parser/__init__.py                       |  7 ++++
 myst_parser/docutils_renderer.py              | 11 ++++++
 myst_parser/main.py                           |  9 ++++-
 myst_parser/myst_amsmath.py                   | 24 ++++++++++++
 myst_parser/sphinx_parser.py                  |  1 +
 tests/test_renderers/fixtures/amsmath.md      | 39 +++++++++++++++++++
 tests/test_renderers/test_fixtures.py         | 13 +++++++
 .../sourcedirs/conf_values/conf.py            |  1 +
 .../sourcedirs/conf_values/index.md           | 12 ++++++
 tests/test_sphinx/test_sphinx_builds.py       |  8 +++-
 .../test_sphinx_builds/test_conf_values.html  | 33 ++++++++++++++++
 .../test_sphinx_builds/test_conf_values.xml   | 11 ++++++
 12 files changed, 167 insertions(+), 2 deletions(-)
 create mode 100644 myst_parser/myst_amsmath.py
 create mode 100644 tests/test_renderers/fixtures/amsmath.md
 create mode 100644 tests/test_sphinx/test_sphinx_builds/test_conf_values.html

diff --git a/myst_parser/__init__.py b/myst_parser/__init__.py
index e854f833..71e75c85 100644
--- a/myst_parser/__init__.py
+++ b/myst_parser/__init__.py
@@ -5,13 +5,17 @@ def setup(app):
     """Initialize Sphinx extension."""
     from myst_parser.sphinx_parser import MystParser
     from myst_parser.myst_refs import MystReferenceResolver
+    from myst_parser.myst_amsmath import MystAmsMathTransform
 
     app.add_source_suffix(".md", "markdown")
     app.add_source_parser(MystParser)
     app.add_post_transform(MystReferenceResolver)
+    app.add_post_transform(MystAmsMathTransform)
 
     app.add_config_value("myst_math_delimiters", "dollars", "env")
     app.add_config_value("myst_disable_syntax", (), "env")
+    app.add_config_value("myst_amsmath_enable", False, "env")
+    app.add_config_value("myst_amsmath_html", [r"\[", r"\]"], "html")
 
     app.connect("config-inited", validate_config)
 
@@ -36,3 +40,6 @@ def validate_config(app, config):
             "myst_math_delimiters config option not an allowed name: "
             + f"{allowed_delimiters}"
         )
+
+    if not isinstance(config.myst_amsmath_enable, bool):
+        logger.error("myst_disable_syntax config option not of type boolean")
diff --git a/myst_parser/docutils_renderer.py b/myst_parser/docutils_renderer.py
index 2f56dba4..d9754eba 100644
--- a/myst_parser/docutils_renderer.py
+++ b/myst_parser/docutils_renderer.py
@@ -557,6 +557,17 @@ def render_math_block(self, token):
         self.add_line_and_source_path(node, token)
         self.current_node.append(node)
 
+    def render_amsmath(self, token):
+        # TODO how to parse and reference labels?
+        # environment = token.meta["environment"]
+        # numbered = token.meta["numbered"]
+        content = token.content
+        node = nodes.math_block(
+            content, content, nowrap=True, number=None, classes=["amsmath"]
+        )
+        self.add_line_and_source_path(node, token)
+        self.current_node.append(node)
+
     def render_footnote_ref(self, token):
         """Footnote references are added as auto-numbered,
         .i.e. `[^a]` is read as rST `[#a]_`
diff --git a/myst_parser/main.py b/myst_parser/main.py
index e7424b26..e938db37 100644
--- a/myst_parser/main.py
+++ b/myst_parser/main.py
@@ -7,12 +7,16 @@
 from markdown_it.extensions.myst_role import myst_role_plugin
 from markdown_it.extensions.texmath import texmath_plugin
 from markdown_it.extensions.footnote import footnote_plugin
+from markdown_it.extensions.amsmath import amsmath_plugin
 
 from . import __version__  # noqa: F401
 
 
 def default_parser(
-    renderer="sphinx", disable_syntax=(), math_delimiters="dollars"
+    renderer="sphinx",
+    disable_syntax=(),
+    math_delimiters: str = "dollars",
+    enable_amsmath: bool = True,
 ) -> MarkdownIt:
     """Return the default parser configuration for MyST"""
     if renderer == "sphinx":
@@ -45,6 +49,8 @@ def default_parser(
     )
     for name in disable_syntax:
         md.disable(name, True)
+    if enable_amsmath:
+        md.use(amsmath_plugin)
     return md
 
 
@@ -53,6 +59,7 @@ def to_docutils(
     options=None,
     env=None,
     disable_syntax: List[str] = (),
+    enable_amsmath: bool = False,
     math_delimiters: str = "dollars",
     renderer="sphinx",
     document=None,
diff --git a/myst_parser/myst_amsmath.py b/myst_parser/myst_amsmath.py
new file mode 100644
index 00000000..4641a45e
--- /dev/null
+++ b/myst_parser/myst_amsmath.py
@@ -0,0 +1,24 @@
+from typing import Any
+
+from docutils import nodes
+
+from sphinx.transforms.post_transforms import SphinxPostTransform
+from sphinx.util.nodes import NodeMatcher
+
+
+class MystAmsMathTransform(SphinxPostTransform):
+    """For the default mathjax renderer,
+    math_blocks are normally wrapped in a prefix/suffix defined by mathjax_display
+    However, this is not the case if the math_block is set as nowrap,
+    as set for amsmath.
+    Therefore, we need to do this independently.
+    """
+
+    default_priority = 400
+    builders = ("html",)
+
+    def run(self, **kwargs: Any) -> None:
+        matcher = NodeMatcher(nodes.math_block, classes=["amsmath"])
+        for node in self.document.traverse(matcher):  # type: nodes.math_block
+            prefix, suffix = self.config.myst_amsmath_html
+            node.children[0] = nodes.Text(prefix + str(node.children[0]) + suffix)
diff --git a/myst_parser/sphinx_parser.py b/myst_parser/sphinx_parser.py
index feadf54b..ffc3a38d 100644
--- a/myst_parser/sphinx_parser.py
+++ b/myst_parser/sphinx_parser.py
@@ -188,6 +188,7 @@ def parse(self, inputstring: str, document: nodes.document):
             document=document,
             disable_syntax=sphinx_config.myst_disable_syntax,
             math_delimiters=sphinx_config.myst_math_delimiters,
+            enable_amsmath=sphinx_config.myst_amsmath_enable,
         )
 
 
diff --git a/tests/test_renderers/fixtures/amsmath.md b/tests/test_renderers/fixtures/amsmath.md
new file mode 100644
index 00000000..8e738c54
--- /dev/null
+++ b/tests/test_renderers/fixtures/amsmath.md
@@ -0,0 +1,39 @@
+--------------------------------
+Single Line:
+.
+\begin{equation} a \end{equation}
+.
+<document source="notset">
+    <math_block classes="amsmath" nowrap="True" number="True" xml:space="preserve">
+        \begin{equation} a \end{equation}
+.
+
+--------------------------------
+Multi Line:
+.
+\begin{equation}
+a
+\end{equation}
+.
+<document source="notset">
+    <math_block classes="amsmath" nowrap="True" number="True" xml:space="preserve">
+        \begin{equation}
+        a
+        \end{equation}
+.
+
+--------------------------------
+In list:
+.
+- \begin{equation}
+  a = 1
+  \end{equation}
+.
+<document source="notset">
+    <bullet_list>
+        <list_item>
+            <math_block classes="amsmath" nowrap="True" number="True" xml:space="preserve">
+                \begin{equation}
+                  a = 1
+                  \end{equation}
+.
diff --git a/tests/test_renderers/test_fixtures.py b/tests/test_renderers/test_fixtures.py
index 64e2772d..e82de312 100644
--- a/tests/test_renderers/test_fixtures.py
+++ b/tests/test_renderers/test_fixtures.py
@@ -115,3 +115,16 @@ def test_sphinx_roles(line, title, input, expected):
     # sphinx 3 adds a parent key
     _actual = re.sub('cpp:parent_key="[^"]*"', 'cpp:parent_key=""', _actual)
     assert _actual == _expected
+
+
+@pytest.mark.parametrize(
+    "line,title,input,expected", read_fixture_file(FIXTURE_PATH.joinpath("amsmath.md")),
+)
+def test_amsmath(line, title, input, expected):
+    document = to_docutils(input, in_sphinx_env=True)
+    print(document.pformat())
+    _actual, _expected = [
+        "\n".join([ll.rstrip() for ll in text.splitlines()])
+        for text in (document.pformat(), expected)
+    ]
+    assert _actual == _expected
diff --git a/tests/test_sphinx/sourcedirs/conf_values/conf.py b/tests/test_sphinx/sourcedirs/conf_values/conf.py
index d2b0874e..0e913e5a 100644
--- a/tests/test_sphinx/sourcedirs/conf_values/conf.py
+++ b/tests/test_sphinx/sourcedirs/conf_values/conf.py
@@ -2,3 +2,4 @@
 exclude_patterns = ["_build"]
 myst_disable_syntax = ("emphasis",)
 myst_math_delimiters = "brackets"
+myst_amsmath_enable = True
diff --git a/tests/test_sphinx/sourcedirs/conf_values/index.md b/tests/test_sphinx/sourcedirs/conf_values/index.md
index ee3150e2..7ff235e4 100644
--- a/tests/test_sphinx/sourcedirs/conf_values/index.md
+++ b/tests/test_sphinx/sourcedirs/conf_values/index.md
@@ -2,4 +2,16 @@
 
 *disabled*
 
+\(a=1\)
+
 \[a=1\]
+
+\begin{equation}
+b=2
+\end{equation}
+
+```{math}
+c=3
+
+d=4
+```
diff --git a/tests/test_sphinx/test_sphinx_builds.py b/tests/test_sphinx/test_sphinx_builds.py
index cc39a8a9..49b5ce63 100644
--- a/tests/test_sphinx/test_sphinx_builds.py
+++ b/tests/test_sphinx/test_sphinx_builds.py
@@ -60,7 +60,12 @@ def test_references(
     buildername="html", srcdir=os.path.join(SOURCE_DIR, "conf_values"), freshenv=True
 )
 def test_conf_values(
-    app, status, warning, get_sphinx_app_doctree, remove_sphinx_builds
+    app,
+    status,
+    warning,
+    get_sphinx_app_doctree,
+    get_sphinx_app_output,
+    remove_sphinx_builds,
 ):
     """basic test."""
     app.build()
@@ -70,6 +75,7 @@ def test_conf_values(
     assert warnings == ""
 
     get_sphinx_app_doctree(app, docname="index", regress=True)
+    get_sphinx_app_output(app, filename="index.html", regress_html=True)
 
 
 @pytest.mark.sphinx(
diff --git a/tests/test_sphinx/test_sphinx_builds/test_conf_values.html b/tests/test_sphinx/test_sphinx_builds/test_conf_values.html
new file mode 100644
index 00000000..054d9a6c
--- /dev/null
+++ b/tests/test_sphinx/test_sphinx_builds/test_conf_values.html
@@ -0,0 +1,33 @@
+<div class="documentwrapper">
+ <div class="bodywrapper">
+  <div class="body" role="main">
+   <div class="section" id="test">
+    <h1>
+     Test
+     <a class="headerlink" href="#test" title="Permalink to this headline">
+      ¶
+     </a>
+    </h1>
+    <p>
+     *disabled*
+    </p>
+    <p>
+     <span class="math notranslate nohighlight">
+      \(a=1\)
+     </span>
+    </p>
+    <div class="math notranslate nohighlight">
+     \[a=1\]
+    </div>
+    <div class="amsmath math notranslate nohighlight">
+     \[\begin{equation}
+b=2
+\end{equation}\]
+    </div>
+    <div class="math notranslate nohighlight">
+     \[ \begin{align}\begin{aligned}c=3\\d=4\end{aligned}\end{align} \]
+    </div>
+   </div>
+  </div>
+ </div>
+</div>
diff --git a/tests/test_sphinx/test_sphinx_builds/test_conf_values.xml b/tests/test_sphinx/test_sphinx_builds/test_conf_values.xml
index 699ce205..d80ac9f0 100644
--- a/tests/test_sphinx/test_sphinx_builds/test_conf_values.xml
+++ b/tests/test_sphinx/test_sphinx_builds/test_conf_values.xml
@@ -4,5 +4,16 @@
             Test
         <paragraph>
             *disabled*
+        <paragraph>
+            <math>
+                a=1
         <math_block nowrap="False" number="True" xml:space="preserve">
             a=1
+        <math_block classes="amsmath" nowrap="True" number="True" xml:space="preserve">
+            \begin{equation}
+            b=2
+            \end{equation}
+        <math_block docname="index" label="True" nowrap="False" number="True" xml:space="preserve">
+            c=3
+            
+            d=4

From 1e002d69cb8e8b6fd3cc51dcad6b0561f35e15f4 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 04:55:25 +0100
Subject: [PATCH 03/12] Add documentation

---
 docs/conf.py                                  |  2 +
 docs/using/syntax.md                          | 71 +++++++++++++++++--
 myst_parser/__init__.py                       |  1 -
 myst_parser/docutils_renderer.py              | 11 ---
 myst_parser/myst_amsmath.py                   | 39 +++++++++-
 myst_parser/sphinx_renderer.py                | 31 ++++++++
 tests/test_renderers/fixtures/amsmath.md      | 23 +++++-
 tests/test_renderers/test_fixtures.py         |  5 +-
 tests/test_sphinx/test_sphinx_builds.py       |  5 +-
 .../test_sphinx_builds/test_conf_values.html  |  7 +-
 .../test_sphinx_builds/test_conf_values.xml   |  3 +-
 11 files changed, 170 insertions(+), 28 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index b4d2d0cb..50f95ca2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -65,6 +65,8 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+myst_amsmath_enable = True
+
 
 def run_apidoc(app):
     """ generate apidoc
diff --git a/docs/using/syntax.md b/docs/using/syntax.md
index 87dbf3f3..f48b366f 100644
--- a/docs/using/syntax.md
+++ b/docs/using/syntax.md
@@ -69,7 +69,8 @@ we have shown equivalent rST syntax for many MyST markdown features below.
     ```
     ````
 * - Math
-  - Two `$` characters wrapping multi-line 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
@@ -200,7 +201,8 @@ In addition to these summaries of inline syntax, see {ref}`extra-markdown-syntax
     (target)=
     ```
 * - Math
-  - dollar enclosed math
+  - `$` (default) or `\(`...`\)` enclosed math. See
+  {ref}`syntax/math` for more information.
   - ```latex
     $a=1$ or $$a=1$$
     ```
@@ -584,9 +586,22 @@ header-rows: 1
   - `.. _mytarget:`
 ````
 
+(syntax/math)=
+
 ### Math shortcuts
 
-Math can be called in-line with single `$` characters around your math.
+The style of math parsing is governed by the `myst_math_delimiters` option set in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html).
+The two common settings are:
+
+- `myst_math_delimiters = "dollars"` (default)
+  - inline: `$...$` or `$$...$$`
+  - display: `$$...$$`
+  - display + equation label: `$$...$$ (1)`
+- `myst_math_delimiters = "brackets"`
+  - inline: `\(...\)`
+  - display: `\[...\]`
+  - display + equation label: `\[...\] (1)`
+
 For example, `$x_{hey}=it+is^{math}$` renders as $x_{hey}=it+is^{math}$.
 This is equivalent to writing:
 
@@ -594,8 +609,12 @@ This is equivalent to writing:
 {math}`x_{hey}=it+is^{math}`
 ```
 
-Block-level math can be provided with `$$` signs that wrap the math block you'd like
-to parse. For example:
+```{tip}
+Math can be escaped (negated) by adding a `\` before the first symbol, e.g. `\$a$` renders as \$a$.
+```
+
+Block-level math can then be provided with `$$` signs that wrap the math block you'd like to parse.
+For example:
 
 ```latex
 $$
@@ -642,6 +661,48 @@ $$ (eqn:best)
 
 This is the best equation {eq}`eqn:best`
 
+(syntax/amsmath)=
+
+### Direct LaTeX Math (optional)
+
+You can enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations by setting `myst_amsmath_enable = True` in your sphinx `conf.py`.
+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` are not currently identified, 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))!
+```
+
 (syntax/frontmatter)=
 
 ### Front Matter
diff --git a/myst_parser/__init__.py b/myst_parser/__init__.py
index 71e75c85..8b1b713b 100644
--- a/myst_parser/__init__.py
+++ b/myst_parser/__init__.py
@@ -15,7 +15,6 @@ def setup(app):
     app.add_config_value("myst_math_delimiters", "dollars", "env")
     app.add_config_value("myst_disable_syntax", (), "env")
     app.add_config_value("myst_amsmath_enable", False, "env")
-    app.add_config_value("myst_amsmath_html", [r"\[", r"\]"], "html")
 
     app.connect("config-inited", validate_config)
 
diff --git a/myst_parser/docutils_renderer.py b/myst_parser/docutils_renderer.py
index d9754eba..2f56dba4 100644
--- a/myst_parser/docutils_renderer.py
+++ b/myst_parser/docutils_renderer.py
@@ -557,17 +557,6 @@ def render_math_block(self, token):
         self.add_line_and_source_path(node, token)
         self.current_node.append(node)
 
-    def render_amsmath(self, token):
-        # TODO how to parse and reference labels?
-        # environment = token.meta["environment"]
-        # numbered = token.meta["numbered"]
-        content = token.content
-        node = nodes.math_block(
-            content, content, nowrap=True, number=None, classes=["amsmath"]
-        )
-        self.add_line_and_source_path(node, token)
-        self.current_node.append(node)
-
     def render_footnote_ref(self, token):
         """Footnote references are added as auto-numbered,
         .i.e. `[^a]` is read as rST `[#a]_`
diff --git a/myst_parser/myst_amsmath.py b/myst_parser/myst_amsmath.py
index 4641a45e..7465c30b 100644
--- a/myst_parser/myst_amsmath.py
+++ b/myst_parser/myst_amsmath.py
@@ -8,17 +8,50 @@
 
 class MystAmsMathTransform(SphinxPostTransform):
     """For the default mathjax renderer,
-    math_blocks are normally wrapped in a prefix/suffix defined by mathjax_display
+    math_blocks are normally wrapped in a prefix/suffix defined by mathjax_display,
+    and labeled nodes are numbered.
     However, this is not the case if the math_block is set as nowrap,
     as set for amsmath.
     Therefore, we need to do this independently.
     """
 
     default_priority = 400
-    builders = ("html",)
 
     def run(self, **kwargs: Any) -> None:
+        if "html" not in self.app.builder.name:
+            return
+        if self.app.builder.math_renderer_name != "mathjax":
+            return
         matcher = NodeMatcher(nodes.math_block, classes=["amsmath"])
         for node in self.document.traverse(matcher):  # type: nodes.math_block
-            prefix, suffix = self.config.myst_amsmath_html
+            prefix, suffix = self.config.mathjax_display
             node.children[0] = nodes.Text(prefix + str(node.children[0]) + suffix)
+            replace = []
+            if node["number"]:
+                number = get_node_equation_number(self, node)
+                replace.append(
+                    nodes.raw(
+                        "", f'<span class="eqno">({number})</span>', format="html"
+                    )
+                )
+            # TODO add permalink (see sphinx/ext/mathjax.py)
+            # self.add_permalink_ref(node, _('Permalink to this equation'))
+            replace.append(node)
+            node.replace_self(replace)
+
+
+def get_node_equation_number(tr: SphinxPostTransform, node: nodes.math_block) -> str:
+    """Adapted from sphinx/util/math.py"""
+    if tr.config.math_numfig and tr.config.numfig:
+        figtype = "displaymath"
+        if tr.app.builder.name == "singlehtml":
+            # TODO is this the right docname?
+            key = "%s/%s" % (tr.app.env.docname, figtype)
+        else:
+            key = figtype
+
+        id = node["ids"][0]
+        number = tr.app.builder.fignumbers.get(key, {}).get(id, ())
+        return ".".join(map(str, number))
+    else:
+        return node["number"]
diff --git a/myst_parser/sphinx_renderer.py b/myst_parser/sphinx_renderer.py
index 691776e4..1a789ca8 100644
--- a/myst_parser/sphinx_renderer.py
+++ b/myst_parser/sphinx_renderer.py
@@ -4,6 +4,7 @@
 import tempfile
 from typing import cast
 from urllib.parse import unquote
+from uuid import uuid4
 
 from docutils import nodes
 from docutils.parsers.rst import directives, roles
@@ -62,6 +63,36 @@ def render_math_block_eqno(self, token):
         self.add_line_and_source_path(node, token)
         self.current_node.append(node)
 
+    def _random_label(self):
+        return str(uuid4())
+
+    def render_amsmath(self, token):
+        # environment = token.meta["environment"]
+        content = token.content
+
+        if token.meta["numbered"] != "*":
+            # TODO how to parse and reference labels within environment?
+            # for now we give create a unique hash, so the equation will be numbered
+            # but there will be no reference clashes
+            label = self._random_label()
+            node = nodes.math_block(
+                content,
+                content,
+                nowrap=True,
+                number=None,
+                classes=["amsmath"],
+                label=label,
+            )
+            target = self.add_math_target(node)
+            self.add_line_and_source_path(target, token)
+            self.current_node.append(target)
+        else:
+            node = nodes.math_block(
+                content, content, nowrap=True, number=None, classes=["amsmath"]
+            )
+        self.add_line_and_source_path(node, token)
+        self.current_node.append(node)
+
     def add_math_target(self, node):
         # Code mainly copied from sphinx.directives.patches.MathDirective
         env = self.document.settings.env
diff --git a/tests/test_renderers/fixtures/amsmath.md b/tests/test_renderers/fixtures/amsmath.md
index 8e738c54..b57a7ce5 100644
--- a/tests/test_renderers/fixtures/amsmath.md
+++ b/tests/test_renderers/fixtures/amsmath.md
@@ -4,7 +4,8 @@ Single Line:
 \begin{equation} a \end{equation}
 .
 <document source="notset">
-    <math_block classes="amsmath" nowrap="True" number="True" xml:space="preserve">
+    <target ids="equation-mock-uuid">
+    <math_block classes="amsmath" docname="mock_docname" label="mock-uuid" nowrap="True" number="1" xml:space="preserve">
         \begin{equation} a \end{equation}
 .
 
@@ -16,12 +17,27 @@ a
 \end{equation}
 .
 <document source="notset">
-    <math_block classes="amsmath" nowrap="True" number="True" xml:space="preserve">
+    <target ids="equation-mock-uuid">
+    <math_block classes="amsmath" docname="mock_docname" label="mock-uuid" nowrap="True" number="1" xml:space="preserve">
         \begin{equation}
         a
         \end{equation}
 .
 
+--------------------------------
+Multi Line no number:
+.
+\begin{equation*}
+a
+\end{equation*}
+.
+<document source="notset">
+    <math_block classes="amsmath" nowrap="True" number="True" xml:space="preserve">
+        \begin{equation*}
+        a
+        \end{equation*}
+.
+
 --------------------------------
 In list:
 .
@@ -32,7 +48,8 @@ In list:
 <document source="notset">
     <bullet_list>
         <list_item>
-            <math_block classes="amsmath" nowrap="True" number="True" xml:space="preserve">
+            <target ids="equation-mock-uuid">
+            <math_block classes="amsmath" docname="mock_docname" label="mock-uuid" nowrap="True" number="1" xml:space="preserve">
                 \begin{equation}
                   a = 1
                   \end{equation}
diff --git a/tests/test_renderers/test_fixtures.py b/tests/test_renderers/test_fixtures.py
index e82de312..365f0e3f 100644
--- a/tests/test_renderers/test_fixtures.py
+++ b/tests/test_renderers/test_fixtures.py
@@ -6,7 +6,7 @@
 
 from markdown_it.utils import read_fixture_file
 from myst_parser.main import to_docutils
-from myst_parser.sphinx_renderer import mock_sphinx_env
+from myst_parser.sphinx_renderer import mock_sphinx_env, SphinxRenderer
 
 FIXTURE_PATH = Path(__file__).parent.joinpath("fixtures")
 
@@ -120,7 +120,8 @@ def test_sphinx_roles(line, title, input, expected):
 @pytest.mark.parametrize(
     "line,title,input,expected", read_fixture_file(FIXTURE_PATH.joinpath("amsmath.md")),
 )
-def test_amsmath(line, title, input, expected):
+def test_amsmath(line, title, input, expected, monkeypatch):
+    monkeypatch.setattr(SphinxRenderer, "_random_label", lambda self: "mock-uuid")
     document = to_docutils(input, in_sphinx_env=True)
     print(document.pformat())
     _actual, _expected = [
diff --git a/tests/test_sphinx/test_sphinx_builds.py b/tests/test_sphinx/test_sphinx_builds.py
index 49b5ce63..004ac056 100644
--- a/tests/test_sphinx/test_sphinx_builds.py
+++ b/tests/test_sphinx/test_sphinx_builds.py
@@ -66,10 +66,13 @@ def test_conf_values(
     get_sphinx_app_doctree,
     get_sphinx_app_output,
     remove_sphinx_builds,
+    monkeypatch,
 ):
     """basic test."""
-    app.build()
+    from myst_parser.sphinx_renderer import SphinxRenderer
 
+    monkeypatch.setattr(SphinxRenderer, "_random_label", lambda self: "mock-uuid")
+    app.build()
     assert "build succeeded" in status.getvalue()  # Build succeeded
     warnings = warning.getvalue().strip()
     assert warnings == ""
diff --git a/tests/test_sphinx/test_sphinx_builds/test_conf_values.html b/tests/test_sphinx/test_sphinx_builds/test_conf_values.html
index 054d9a6c..d9b87be5 100644
--- a/tests/test_sphinx/test_sphinx_builds/test_conf_values.html
+++ b/tests/test_sphinx/test_sphinx_builds/test_conf_values.html
@@ -19,7 +19,12 @@ <h1>
     <div class="math notranslate nohighlight">
      \[a=1\]
     </div>
-    <div class="amsmath math notranslate nohighlight">
+    <div class="amsmath" id="equation-mock-uuid">
+     <span class="eqno">
+      (1)
+     </span>
+    </div>
+    <div class="amsmath math notranslate nohighlight" id="equation-mock-uuid">
      \[\begin{equation}
 b=2
 \end{equation}\]
diff --git a/tests/test_sphinx/test_sphinx_builds/test_conf_values.xml b/tests/test_sphinx/test_sphinx_builds/test_conf_values.xml
index d80ac9f0..acec202e 100644
--- a/tests/test_sphinx/test_sphinx_builds/test_conf_values.xml
+++ b/tests/test_sphinx/test_sphinx_builds/test_conf_values.xml
@@ -9,7 +9,8 @@
                 a=1
         <math_block nowrap="False" number="True" xml:space="preserve">
             a=1
-        <math_block classes="amsmath" nowrap="True" number="True" xml:space="preserve">
+        <target refid="equation-mock-uuid">
+        <math_block classes="amsmath" docname="index" ids="equation-mock-uuid" label="mock-uuid" nowrap="True" number="1" xml:space="preserve">
             \begin{equation}
             b=2
             \end{equation}

From c9b4d55600f78421615a2c94e24e41c685a5b7f6 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 04:57:24 +0100
Subject: [PATCH 04/12] Update syntax.md

---
 docs/using/syntax.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/using/syntax.md b/docs/using/syntax.md
index f48b366f..fef0e622 100644
--- a/docs/using/syntax.md
+++ b/docs/using/syntax.md
@@ -699,7 +699,9 @@ a_{21}& =b_{21}&
 \end{align}
 
 ```{note}
-`\labels` are not currently identified, so cannot be referenced.
+This is a new feature, so please report any bugs observed 🙏.
+
+Also `\labels` 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))!
 ```
 

From a1245198ce0d37d43b7d39ce338a4209e7e0dbd9 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 05:03:08 +0100
Subject: [PATCH 05/12] fix for RTD?

---
 myst_parser/myst_amsmath.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/myst_parser/myst_amsmath.py b/myst_parser/myst_amsmath.py
index 7465c30b..6100cc70 100644
--- a/myst_parser/myst_amsmath.py
+++ b/myst_parser/myst_amsmath.py
@@ -18,7 +18,9 @@ class MystAmsMathTransform(SphinxPostTransform):
     default_priority = 400
 
     def run(self, **kwargs: Any) -> None:
-        if "html" not in self.app.builder.name:
+        if "html" not in self.app.builder.name and self.app.builder.name not in (
+            "readthedocs",
+        ):
             return
         if self.app.builder.math_renderer_name != "mathjax":
             return

From b69c32ff85cfb1ddc4769554d46aab5a6c1b7e62 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 05:21:00 +0100
Subject: [PATCH 06/12] Update syntax.md

---
 docs/using/syntax.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/docs/using/syntax.md b/docs/using/syntax.md
index fef0e622..6ebca051 100644
--- a/docs/using/syntax.md
+++ b/docs/using/syntax.md
@@ -699,9 +699,7 @@ a_{21}& =b_{21}&
 \end{align}
 
 ```{note}
-This is a new feature, so please report any bugs observed 🙏.
-
-Also `\labels` are not currently identified, and so cannot be referenced.
+`\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))!
 ```
 

From f5d84f27a6cfcc5633b7c7d070782fe31906cfbe Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 07:11:10 +0100
Subject: [PATCH 07/12] =?UTF-8?q?=F0=9F=94=A7=20MAINTAIN:=20trigger=20work?=
 =?UTF-8?q?flow=20on=20tags?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/tests.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 89b16dfb..eb351173 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -3,6 +3,8 @@ name: continuous-integration
 on:
   push:
     branches: [master]
+    tags:
+      - 'v*'
   pull_request:
 
 jobs:

From fe06608c6debc1fcb9836a38c416d3e951560e83 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 14:33:57 +0100
Subject: [PATCH 08/12] Make RTD fail on warnings

---
 .readthedocs.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 123a4730..ceac323e 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -8,3 +8,7 @@ python:
         extra_requirements:
           - sphinx
           - rtd
+
+sphinx:
+  builder: html
+  fail_on_warning: true

From 09e0f5e1da487bb32c4e10e145b48e63c5e28c3c Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 14:45:26 +0100
Subject: [PATCH 09/12] fix typo

---
 myst_parser/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/myst_parser/__init__.py b/myst_parser/__init__.py
index 8b1b713b..159f1eb7 100644
--- a/myst_parser/__init__.py
+++ b/myst_parser/__init__.py
@@ -41,4 +41,4 @@ def validate_config(app, config):
         )
 
     if not isinstance(config.myst_amsmath_enable, bool):
-        logger.error("myst_disable_syntax config option not of type boolean")
+        logger.error("myst_amsmath_enable config option not of type boolean")

From a6e4ed58966e9690e3c922438a2f782721a8b2aa Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 14:52:22 +0100
Subject: [PATCH 10/12] fix option propagation

---
 myst_parser/main.py                   | 3 ++-
 tests/test_renderers/test_fixtures.py | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/myst_parser/main.py b/myst_parser/main.py
index e938db37..d777b3dd 100644
--- a/myst_parser/main.py
+++ b/myst_parser/main.py
@@ -16,7 +16,7 @@ def default_parser(
     renderer="sphinx",
     disable_syntax=(),
     math_delimiters: str = "dollars",
-    enable_amsmath: bool = True,
+    enable_amsmath: bool = False,
 ) -> MarkdownIt:
     """Return the default parser configuration for MyST"""
     if renderer == "sphinx":
@@ -87,6 +87,7 @@ def to_docutils(
         renderer=renderer,
         disable_syntax=disable_syntax,
         math_delimiters=math_delimiters,
+        enable_amsmath=enable_amsmath,
     )
     if options:
         md.options.update(options)
diff --git a/tests/test_renderers/test_fixtures.py b/tests/test_renderers/test_fixtures.py
index 365f0e3f..a9914e08 100644
--- a/tests/test_renderers/test_fixtures.py
+++ b/tests/test_renderers/test_fixtures.py
@@ -122,7 +122,7 @@ def test_sphinx_roles(line, title, input, expected):
 )
 def test_amsmath(line, title, input, expected, monkeypatch):
     monkeypatch.setattr(SphinxRenderer, "_random_label", lambda self: "mock-uuid")
-    document = to_docutils(input, in_sphinx_env=True)
+    document = to_docutils(input, in_sphinx_env=True, enable_amsmath=True)
     print(document.pformat())
     _actual, _expected = [
         "\n".join([ll.rstrip() for ll in text.splitlines()])

From 1b2ffbea40efc12391fb07d05175b4c147f847ea Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 17:55:29 +0100
Subject: [PATCH 11/12] Add admonition container rendering

---
 docs/conf.py                                |  1 +
 docs/using/syntax.md                        | 59 +++++++++++++++++++++
 myst_parser/__init__.py                     |  4 ++
 myst_parser/docutils_renderer.py            | 47 ++++++++++++++++
 myst_parser/main.py                         | 14 +++++
 myst_parser/sphinx_parser.py                |  1 +
 tests/test_renderers/fixtures/containers.md | 30 +++++++++++
 tests/test_renderers/test_fixtures.py       | 15 ++++++
 8 files changed, 171 insertions(+)
 create mode 100644 tests/test_renderers/fixtures/containers.md

diff --git a/docs/conf.py b/docs/conf.py
index 50f95ca2..44ecff3f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -66,6 +66,7 @@
 html_static_path = ["_static"]
 
 myst_amsmath_enable = True
+myst_admonition_enable = True
 
 
 def run_apidoc(app):
diff --git a/docs/using/syntax.md b/docs/using/syntax.md
index 6ebca051..997d0861 100644
--- a/docs/using/syntax.md
+++ b/docs/using/syntax.md
@@ -99,6 +99,14 @@ we have shown equivalent rST syntax for many MyST markdown features below.
   - ```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 {ref}`syntax/admonitions` for more details.
+  - ````md
+    :::{note}
+    *content*
+    :::
+    ````
 `````
 
 (commonmark-block-tokens)=
@@ -479,6 +487,57 @@ print('yep!')
 `````
 ``````
 
+(syntax/admonitions)=
+
+### Admonition directives special syntax (optional)
+
+A special syntax for admonitions can optionally be enabled by setting `myst_admonition_enable = True` in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html).
+
+The key differences are that, instead of backticks, colons are used, and **the content will be parsed as regular Markdown**.
+This has the benefit of allowing the content to be rendered correctly when you are working in any standard markdown editors.
+For example:
+
+```md
+:::{note}
+This text is **standard** _Markdown_
+:::
+```
+
+:::{note}
+This text is **standard** _Markdown_
+:::
+
+Similar to normal directives, these admonitions can also be nested:
+
+```md
+::::{important}
+:::{note}
+This text is **standard** _Markdown_
+:::
+::::
+```
+
+::::{important}
+:::{note}
+This text is **standard** _Markdown_
+:::
+::::
+
+The supported directives are: attention, caution, danger, error, important, hint, note, tip and warning.
+
+These directives do **not** currently allow for parameters to be set, but you can add additional CSS classes to the admonition as comma-delimited arguments after the directive name.
+For example:
+
+```md
+:::{note,bg-success}
+This text is **standard** _Markdown_
+:::
+```
+
+:::{note,bg-success}
+This text is **standard** _Markdown_
+:::
+
 (syntax/roles)=
 
 ## Roles - an in-line extension point
diff --git a/myst_parser/__init__.py b/myst_parser/__init__.py
index 159f1eb7..00957420 100644
--- a/myst_parser/__init__.py
+++ b/myst_parser/__init__.py
@@ -15,6 +15,7 @@ def setup(app):
     app.add_config_value("myst_math_delimiters", "dollars", "env")
     app.add_config_value("myst_disable_syntax", (), "env")
     app.add_config_value("myst_amsmath_enable", False, "env")
+    app.add_config_value("myst_admonition_enable", False, "env")
 
     app.connect("config-inited", validate_config)
 
@@ -42,3 +43,6 @@ def validate_config(app, config):
 
     if not isinstance(config.myst_amsmath_enable, bool):
         logger.error("myst_amsmath_enable config option not of type boolean")
+
+    if not isinstance(config.myst_admonition_enable, bool):
+        logger.error("myst_admonition_enable config option not of type boolean")
diff --git a/myst_parser/docutils_renderer.py b/myst_parser/docutils_renderer.py
index 2f56dba4..819d8ff6 100644
--- a/myst_parser/docutils_renderer.py
+++ b/myst_parser/docutils_renderer.py
@@ -4,6 +4,7 @@
 import inspect
 import json
 from os.path import splitext
+import re
 from typing import List
 from urllib.parse import urlparse
 
@@ -40,6 +41,12 @@ def make_document(source_path="notset") -> nodes.document:
     return new_document(source_path, settings=settings)
 
 
+# CSS class regex taken from https://www.w3.org/TR/CSS21/syndata.html#characters
+REGEX_ADMONTION = re.compile(
+    r"\{(?P<name>[a-zA-Z]+)(?P<classes>(?:\,-?[_a-zA-Z]+[_a-zA-Z0-9-]*)*)\}(?P<title>.*)"  # noqa: E501
+)
+
+
 class DocutilsRenderer:
     __output__ = "docutils"
 
@@ -622,6 +629,46 @@ def render_myst_role(self, token):
             problematic = inliner.problematic(text, rawsource, message)
             self.current_node += problematic
 
+    def get_admonition(self, line, name, classes, title):
+        node_cls = {
+            "attention": nodes.attention,
+            "caution": nodes.caution,
+            "danger": nodes.danger,
+            "error": nodes.error,
+            "important": nodes.important,
+            "hint": nodes.hint,
+            "note": nodes.note,
+            "tip": nodes.tip,
+            "warning": nodes.warning,
+            # seealso in addnodes (i.e. sphinx only)
+        }.get(name, None)
+        if node_cls is None:
+            self.current_node.append(
+                self.reporter.warning(
+                    f"admonition name not recognised, defaulting to note: {name}",
+                    line=line,
+                )
+            )
+            node_cls = nodes.note
+        return node_cls(title, classes=classes[1:].split(","))
+
+    def render_container_admonition_open(self, token):
+        match = REGEX_ADMONTION.match(token.info.strip())
+        if not match:
+            self.current_node.append(
+                self.reporter.warning(
+                    "admonition argument did not match required regex, "
+                    f"defaulting to note: {token.info}",
+                    line=token.map[0],
+                )
+            )
+            admonition = nodes.note("")
+        else:
+            admonition = self.get_admonition(token.map[0], **match.groupdict())
+        self.add_line_and_source_path(admonition, token)
+        with self.current_node_context(admonition, append=True):
+            self.render_children(token)
+
     def render_directive(self, token: Token):
         """Render special fenced code blocks as directives."""
         first_line = token.info.split(maxsplit=1)
diff --git a/myst_parser/main.py b/myst_parser/main.py
index d777b3dd..1cd5c740 100644
--- a/myst_parser/main.py
+++ b/myst_parser/main.py
@@ -8,6 +8,7 @@
 from markdown_it.extensions.texmath import texmath_plugin
 from markdown_it.extensions.footnote import footnote_plugin
 from markdown_it.extensions.amsmath import amsmath_plugin
+from markdown_it.extensions.container import container_plugin
 
 from . import __version__  # noqa: F401
 
@@ -17,6 +18,7 @@ def default_parser(
     disable_syntax=(),
     math_delimiters: str = "dollars",
     enable_amsmath: bool = False,
+    enable_admonitions: bool = False,
 ) -> MarkdownIt:
     """Return the default parser configuration for MyST"""
     if renderer == "sphinx":
@@ -49,6 +51,8 @@ def default_parser(
     )
     for name in disable_syntax:
         md.disable(name, True)
+    if enable_admonitions:
+        md.use(container_plugin, "admonition", validate=validate_admonition)
     if enable_amsmath:
         md.use(amsmath_plugin)
     return md
@@ -60,6 +64,7 @@ def to_docutils(
     env=None,
     disable_syntax: List[str] = (),
     enable_amsmath: bool = False,
+    enable_admonitions: bool = False,
     math_delimiters: str = "dollars",
     renderer="sphinx",
     document=None,
@@ -88,6 +93,7 @@ def to_docutils(
         disable_syntax=disable_syntax,
         math_delimiters=math_delimiters,
         enable_amsmath=enable_amsmath,
+        enable_admonitions=enable_admonitions,
     )
     if options:
         md.options.update(options)
@@ -109,3 +115,11 @@ def to_html(text: str, env=None):
 def to_tokens(text: str, env=None):
     md = default_parser("html")
     return md.parse(text, env)
+
+
+def validate_admonition(params: str, *args):
+    # NOTE with containers you can selectively only parse those that have a particular
+    # argument string
+    # However, this reduces the amount of feedback since, if you made an error
+    # in the argument string, it would just ignore it rather than logging a warning
+    return True
diff --git a/myst_parser/sphinx_parser.py b/myst_parser/sphinx_parser.py
index ffc3a38d..6e4578e3 100644
--- a/myst_parser/sphinx_parser.py
+++ b/myst_parser/sphinx_parser.py
@@ -189,6 +189,7 @@ def parse(self, inputstring: str, document: nodes.document):
             disable_syntax=sphinx_config.myst_disable_syntax,
             math_delimiters=sphinx_config.myst_math_delimiters,
             enable_amsmath=sphinx_config.myst_amsmath_enable,
+            enable_admonitions=sphinx_config.myst_admonition_enable,
         )
 
 
diff --git a/tests/test_renderers/fixtures/containers.md b/tests/test_renderers/fixtures/containers.md
new file mode 100644
index 00000000..38219d46
--- /dev/null
+++ b/tests/test_renderers/fixtures/containers.md
@@ -0,0 +1,30 @@
+--------------------------------
+Basic note:
+.
+::: {note}
+*hallo*
+:::
+.
+<document source="notset">
+    <note classes="">
+        <paragraph>
+            <emphasis>
+                hallo
+.
+
+--------------------------------
+Nested notes:
+.
+:::: {important}
+::: {note,other}
+*hallo*
+:::
+::::
+.
+<document source="notset">
+    <important classes="">
+        <note classes="other">
+            <paragraph>
+                <emphasis>
+                    hallo
+.
diff --git a/tests/test_renderers/test_fixtures.py b/tests/test_renderers/test_fixtures.py
index a9914e08..6e79e396 100644
--- a/tests/test_renderers/test_fixtures.py
+++ b/tests/test_renderers/test_fixtures.py
@@ -129,3 +129,18 @@ def test_amsmath(line, title, input, expected, monkeypatch):
         for text in (document.pformat(), expected)
     ]
     assert _actual == _expected
+
+
+@pytest.mark.parametrize(
+    "line,title,input,expected",
+    read_fixture_file(FIXTURE_PATH.joinpath("containers.md")),
+)
+def test_containers(line, title, input, expected, monkeypatch):
+    monkeypatch.setattr(SphinxRenderer, "_random_label", lambda self: "mock-uuid")
+    document = to_docutils(input, in_sphinx_env=True, enable_admonitions=True)
+    print(document.pformat())
+    _actual, _expected = [
+        "\n".join([ll.rstrip() for ll in text.splitlines()])
+        for text in (document.pformat(), expected)
+    ]
+    assert _actual == _expected

From 11510f0e37f41b6ce100451df331f1c96994c6d1 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Tue, 11 Aug 2020 19:53:21 +0100
Subject: [PATCH 12/12] Add parsing of admonition titles

---
 docs/using/syntax.md                        |  8 ++++----
 myst_parser/docutils_renderer.py            | 19 +++++++++++++++++--
 tests/test_renderers/fixtures/containers.md | 18 ++++++++++++++++++
 3 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/docs/using/syntax.md b/docs/using/syntax.md
index 997d0861..dc8dc116 100644
--- a/docs/using/syntax.md
+++ b/docs/using/syntax.md
@@ -523,18 +523,18 @@ This text is **standard** _Markdown_
 :::
 ::::
 
-The supported directives are: attention, caution, danger, error, important, hint, note, tip and warning.
+The supported directives are: admonition, attention, caution, danger, error, important, hint, note, tip and warning.
 
-These directives do **not** currently allow for parameters to be set, but you can add additional CSS classes to the admonition as comma-delimited arguments after the directive name.
+These directives do **not** currently allow for parameters to be set, but you can add additional CSS classes to the admonition as comma-delimited arguments after the directive name. Also `admonition` can have a custom title.
 For example:
 
 ```md
-:::{note,bg-success}
+:::{admonition,bg-success} This *is* also **Markdown**
 This text is **standard** _Markdown_
 :::
 ```
 
-:::{note,bg-success}
+:::{admonition,bg-success} This *is* also **Markdown**
 This text is **standard** _Markdown_
 :::
 
diff --git a/myst_parser/docutils_renderer.py b/myst_parser/docutils_renderer.py
index 819d8ff6..7a53b05f 100644
--- a/myst_parser/docutils_renderer.py
+++ b/myst_parser/docutils_renderer.py
@@ -629,7 +629,22 @@ def render_myst_role(self, token):
             problematic = inliner.problematic(text, rawsource, message)
             self.current_node += problematic
 
-    def get_admonition(self, line, name, classes, title):
+    def get_admonition(self, token, name, classes, title):
+
+        line = token.map[0]
+
+        if name == "admonition":
+            # parse title
+            node = nodes.admonition(title, classes=classes[1:].split(","))
+            state_machine = MockStateMachine(self, line)
+            state = MockState(self, state_machine, line)
+            textnodes, messages = state.inline_text(title, line)
+            title_node = nodes.title(title, "", *textnodes)
+            self.add_line_and_source_path(title_node, token)
+            node += title_node
+            node += messages
+            return node
+
         node_cls = {
             "attention": nodes.attention,
             "caution": nodes.caution,
@@ -664,7 +679,7 @@ def render_container_admonition_open(self, token):
             )
             admonition = nodes.note("")
         else:
-            admonition = self.get_admonition(token.map[0], **match.groupdict())
+            admonition = self.get_admonition(token, **match.groupdict())
         self.add_line_and_source_path(admonition, token)
         with self.current_node_context(admonition, append=True):
             self.render_children(token)
diff --git a/tests/test_renderers/fixtures/containers.md b/tests/test_renderers/fixtures/containers.md
index 38219d46..1522e006 100644
--- a/tests/test_renderers/fixtures/containers.md
+++ b/tests/test_renderers/fixtures/containers.md
@@ -28,3 +28,21 @@ Nested notes:
                 <emphasis>
                     hallo
 .
+
+--------------------------------
+Admonition with title:
+.
+::: {admonition,other} A **title**
+*hallo*
+:::
+.
+<document source="notset">
+    <admonition classes="other">
+        <title>
+             A 
+            <strong>
+                title
+        <paragraph>
+            <emphasis>
+                hallo
+.