From 1b6868afc54c773f261d1d3828953dd5bdc68298 Mon Sep 17 00:00:00 2001 From: Srinivas Chippagiri Date: Sun, 8 Nov 2026 18:24:04 -0800 Subject: [PATCH] docs: say that subdocs need the paragraph tag Signed-off-by: Srinivas Chippagiri --- docs/index.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index 46cf69f..b5bc526 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -310,6 +310,11 @@ variable `{{p mysubdoc }}`. See `tests/merge_docx.py` for full code. +A subdoc is made of paragraphs, so it has to be inserted with the paragraph tag ``{{p mysubdoc }}``, alone in its paragraph. +With a plain ``{{ mysubdoc }}`` the paragraphs end up inside the text of the paragraph that holds the tag: an empty paragraph is left behind +and, if the paragraph also has other content such as a bookmark or formatted text, the generated document may be corrupted and refused by Word. +The same goes for subdocs inserted in a loop: put the tag in its own ``{%p for ... %}`` block and use ``{{p item }}`` inside it. + .. _Escaping: Escaping