Skip to content

WebVTT inline formatting emits Markdown whose emphasis does not render #4352

Open

Description

@abo3losh1

Bug

WebVTT cue text that uses inline markup produces Markdown whose emphasis does not render. The span's boundary whitespace stays inside the formatted text item, and the inline-group serializer adds its own separator on top, so the output gets both a doubled space and, where spans are nested, an asterisk with a space inside it.

A closing * preceded by whitespace is not a right-flanking delimiter in CommonMark, so it cannot close emphasis. The markup is emitted but silently fails to render.

This is visible in the repository's own checked-in ground truth, tests/data/webvtt/groundtruth/webvtt_example_04.vtt.md:

The waiter offered a  *steaming bowl of * *paella*  that instantly transported the diners to a sunny Mediterranean coast.
The dessert's  ***unexpected*** * * *arcobaleno* * of flavors*  left everyone in awe.

Rendered through a CommonMark renderer, the italics are lost and the asterisks show up as literal text:

<p>The waiter offered a  *steaming bowl of * <em>paella</em>  that arrived.</p>
<p>The dessert's  <em><strong>unexpected</strong></em> * * <em>arcobaleno</em> * of flavors*  left everyone in awe.</p>

Steps to reproduce

import io
from docling.document_converter import DocumentConverter
from docling.datamodel.base_models import InputFormat, DocumentStream

vtt = (
    "WEBVTT\n\n00:00:01.000 --> 00:00:04.000\n"
    "The waiter offered a <i>steaming bowl of paella</i> that arrived.\n"
)

converter = DocumentConverter(allowed_formats=[InputFormat.VTT])
result = converter.convert(DocumentStream(name="t.vtt", stream=io.BytesIO(vtt.encode())))
print(repr(result.document.export_to_markdown()))

Actual:

'The waiter offered a  *steaming bowl of paella*  that arrived.'

Expected:

'The waiter offered a *steaming bowl of paella* that arrived.'

The single-span case above only produces the doubled space. Nesting a span inside another, as webvtt_example_04.vtt does with <i>steaming bowl of <lang es-ES>paella</lang></i>, is what moves a space inside the emphasis markers and breaks the rendering.

Notes

This looks like the same class of problem as #2745 (docx adds an extra space after bold characters) and #4314. PR #3891 reworks the InlineGroup whitespace contract for the html, md, msword, opendocument and jats backends, but it does not touch webvtt_backend.py, so this backend would still be affected after it lands. Flagging it so it can be picked up with that work rather than fixed in a way that collides with it.

Docling version

2.129.0 (main @ 890dd42)

Python version

3.12.13

Activity

  1. added
    bugSomething isn't working
    vttissues related to the WebVTT backend
    on Sep 22, 2026
  2. ceberam commented on Sep 22, 2026

    @ceberam
    Member

    Thanks @abo3losh1 for reporting this issue.
    You made an accurate analysis of the issue. The rendering issue is indeed due to a bad management of the extra spaces in the serialization of DoclingDocument inline groups. The PR #3891 is still under our radar for fixing the issue. Thanks for the heads-up to consider the WebVTT backend too in that PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingvttissues related to the WebVTT backend

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions