From a691485a955154f721af115df3ec34afe67a5f56 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?V=C3=A1clav=20=C5=A0milauer?= <eu@doxos.eu>
Date: Thu, 26 Sep 2024 23:03:31 +0200
Subject: [PATCH] Document workaround fror #3

---
 docs/index.rst | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/index.rst b/docs/index.rst
index 437b5db..96f2325 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -141,6 +141,38 @@ Warning messages are displayed in the Sphinx build output, for problematic input
 Since is difficult / impossible to map the source line numbers, from the template to the Jinja rendered content,
 problems with the parsing of the rendered content always refer to the first line number either of the ``jinja`` directive, or the template file (when using the ``file`` option).
 
+Known issues
+-------------
+
+* [#3](https://github.com/sphinx-extensions2/sphinx-jinja2/issues/3): template output is fed back into the RST parser. When the source uses `MyST parser <https://myst-parser.readthedocs.io/en/latest/index.html>`__, this will trigger an error::
+
+       Directive 'jinja' cannot be mocked: MockingError: MockStateMachine has not yet implemented 'insert_input'.
+
+
+   The workaround is to wrap the `jinja` directive inside `rst-eval`
+
+   .. code-block:: rst
+
+      ```{rst-eval}
+      .. jinja::
+         :ctx: {"foo":"bar"}
+
+         Baz.
+      ```
+
+   rather than using it directly:
+
+   .. code-block:: markdown
+
+      ```{jinja}
+      :ctx: {"foo":"bar"}
+
+      Baz.
+      ```
+
+
+
+
 Configuration
 -------------