Long captions break table directive (in HTML output by Sphinx)

[n8willis]

What version of myst-parser are you using?

4.0.1

What version dependencies are you using?

Currently, the requirements are set to

alabaster==1.0.0
importlib-metadata>=5.0.0
myst-parser>=0.18.1
pip>=22.1.2
pyparsing>=3.0.9
pyspelling>=2.12.1
pytz>=2022.4
setuptools>=62.6.0
Sphinx==8.1.3
sphinx_external_toc>=1.0.1
sphinx-inline-svg>=0.2.0
sphinx-multitoc-numbering==0.1.3
svg-stack>=0.1.0

This is in a GitHub workflow, which ends up installing this set:
Jinja2-3.1.6 MarkupSafe-3.0.3 Pygments-2.19.2 Sphinx-8.1.3 alabaster-1.0.0 babel-2.18.0 beautifulsoup4-4.14.3 bracex-2.6 certifi-2026.1.4 charset_normalizer-3.4.4 click-8.3.1 docutils-0.21.2 html5lib-1.1 idna-3.11 imagesize-1.4.1 importlib-metadata-8.7.1 lxml-6.0.2 markdown-3.10.1 markdown-it-py-3.0.0 mdit-py-plugins-0.5.0 mdurl-0.1.2 myst-parser-4.0.1 packaging-26.0 pyparsing-3.3.2 pyspelling-2.12.1 pytz-2025.2 pyyaml-6.0.3 requests-2.32.5 six-1.17.0 snowballstemmer-3.0.1 soupsieve-2.8.3 sphinx-inline-svg-0.2.0 sphinx-multitoc-numbering-0.1.3 sphinx_external_toc-1.1.0 sphinxcontrib-applehelp-2.0.0 sphinxcontrib-devhelp-2.0.0 sphinxcontrib-htmlhelp-2.1.0 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-2.0.0 sphinxcontrib-serializinghtml-2.0.0 svg-stack-0.1.0 tomli-2.4.0 typing-extensions-4.15.0 urllib3-2.6.3 wcmatch-10.1 webencodings-0.5.1 zipp-3.23.0

What operating system are you using?

Linux

Describe the Bug

Long captions on a {table} directive get split into two lines, and thus the table fails to be built in HTML output.

Encountering this in a GitHub Action, using https://github.com/rickstaa/action-sphinx-composite on ubuntu-latest. The source of one file contains a long caption on a table directive:

:::{table} Mid-syllable marks that must be tagged for sorting with above-base consonants

| Codepoint | Sorting Position        | Glyph                  |
|:----------|:------------------------|:-----------------------|

... followed by the rest of the table, naturally.

In the workflow runs, the long caption like gets a hard break injected after "with". When it encounters that break, the [table} directive then fails:

/home/runner/work/opentype-shaping-documents/opentype-shaping-documents/opentype-shaping-khmer.md:801: ERROR: Error parsing content block for the "table" directive: exactly one table expected.

above-base consonants

| Codepoint | Sorting Position        | Glyph                  |

(link)

and that table is dropped from the output. AFAICT, if you have a long caption, there is no way to fix this in the file set, because adding the line break manually triggers the same trip-up on the {table} directive. I don't see anything indicating that there's a way to do a line continuation, and the couple of attempts I made (e.g., indentation on the second line) still caused the table directive to fail.

Having a table left out, but the rest of the build succeeding, is a significant issue. Either being able to wrap the caption onto a second line, or having the caption line not get broken, would resolve it.

At this point, I'm not 100% sure if MyST-Parser is where the issue is happening, versus, say markdown-it-py. If it's elsewhere I'm certainly willing to move the issue to where it belongs.

Oddly enough, I do not encounter the line-breaking and do not get the table-directive-failure when building on my local virtualenv, which has a slightly different set of dependencies. But I'm trying to not rely on that, and define it more rigorously. But if it would be informative to add that info, I can.

Expected Behavior

In case it helps to see a visualization, it should look like this:

and it comes out like this:

To Reproduce

Have a table directive with a caption that is longer than the allowed line-length.