feat: add opt-in sparse table record serializer

docling/.agents/skills/docling/SKILL.md

@@ -79,5 +79,5 @@ uvx --from docling docling report.pdf --to md --output /tmp/
 
 - Always report the conversion status and (for PDFs) the page count.
 - If the user does not specify a format, ask whether they want **Markdown** (readable) or **JSON / DoclingDocument** (structured, lossless).
-- For tables, prefer `export_to_markdown()` / `export_to_dataframe()` on the table item (Python) — see [references/python-sdk.md](references/python-sdk.md).
+- For tables, prefer `export_to_markdown()` / `export_to_dataframe()` on the table item (Python) — see [references/python-sdk.md](references/python-sdk.md). For sparse tables in document Markdown, use `--markdown-table-format records` or `export_to_record_markdown(doc)`; neither changes default output.
 - If a converted PDF comes back near-empty, repeated, or full of `�`, the source is likely scanned or complex layout — retry with OCR or `--pipeline vlm` (see [references/cli.md](references/cli.md)).

docling/.agents/skills/docling/references/cli.md

@@ -30,6 +30,17 @@ docling report.pdf --to md --to json --output /tmp/    # both at once
 docling report.pdf --to dclx --output-file /tmp/named-result.dclx
 ```
 
+For Markdown tables, opt in to labeled records rather than pipe tables:
+
+```bash
+docling report.pdf --to md --markdown-table-format records --output /tmp/
+```
+
+`--markdown-table-format default` is the default. It changes only Markdown
+output. The same option works with `docling convert-remote`; it changes the
+local export, not the remote service request. Record text labels actual cells
+by row and column. It is not a Markdown pipe table.
+
 Supported input formats include: `pdf`, `docx`/`doc`, `pptx`/`ppt`, `xlsx`/`xls`,
 `html`, `md`, `asciidoc`, `csv`, `odt`/`ods`/`odp`, images, `audio`, and several
 XML flavors. Restrict/force detection with `--from` (repeatable), e.g.

docling/.agents/skills/docling/references/python-sdk.md

@@ -18,6 +18,13 @@ print(doc.export_to_markdown())
 data = doc.export_to_dict()                 # structured / lossless
 ```
 
+For Markdown tables as labeled source-cell records, use
+`export_to_record_markdown(doc)` from `docling.utils.table_records`. It is an
+opt-in export. The default `doc.export_to_markdown()` does not change. Use
+`save_as_record_markdown(doc, "out.md", image_mode=ImageRefMode.REFERENCED)`
+to save a file and its referenced images. For other Markdown settings, pass
+`params=MarkdownParams(...)` to `export_to_record_markdown`.
+
 `result.status` reports success/failure; `result.document` is always a
 `DoclingDocument`.
 

docling/cli/main.py

@@ -142,6 +142,10 @@
 from docling.datamodel.pipeline_options_asr_model import InlineAsrOptions
 from docling.datamodel.settings import DEFAULT_PAGE_RANGE, settings
 from docling.utils.profiling import ProfilingItem
+from docling.utils.table_records import (
+    MarkdownTableFormat,
+    _save_markdown_with_table_format,
+)
 
 # The local model stack (scipy, torch, …) is absent on lightweight installs
 # (docling-slim[service-client] / docling-client).  Guard these imports so the
@@ -529,6 +533,7 @@ def export_documents(
     chunk_tokenizer: str = "sentence-transformers/all-MiniLM-L6-v2",
     debug_vlm_native_output: bool = False,
     output_file: Path | None = None,
+    markdown_table_format: MarkdownTableFormat = MarkdownTableFormat.DEFAULT,
 ):
     success_count = 0
     failure_count = 0
@@ -629,8 +634,11 @@ def export_documents(
             if export_md:
                 fname = output_file or output_dir / f"{doc_filename}.md"
                 _log.info(f"writing Markdown output to {fname}")
-                conv_res.document.save_as_markdown(
-                    filename=fname, image_mode=image_export_mode
+                _save_markdown_with_table_format(
+                    conv_res.document,
+                    fname,
+                    image_mode=image_export_mode,
+                    table_format=markdown_table_format,
                 )
                 if _is_empty_output(fname):
                     error_message = (
@@ -809,6 +817,11 @@ def convert(  # noqa: C901
     to_formats: list[OutputFormat] = typer.Option(
         None, "--to", help="Specify output formats. Defaults to Markdown."
     ),
+    markdown_table_format: MarkdownTableFormat = typer.Option(
+        MarkdownTableFormat.DEFAULT,
+        "--markdown-table-format",
+        help="Table output in Markdown: default pipe tables or labeled cell records.",
+    ),
     chunker_type: ChunkerType = typer.Option(
         ChunkerType.HYBRID,
         "--chunks-type",
@@ -1857,6 +1870,7 @@ def _resolve_pdf_backend() -> tuple[type[PdfDocumentBackend], PdfBackendOptions]
             print_timings=profiling,
             export_timings=save_profiling,
             image_export_mode=image_export_mode,
+            markdown_table_format=markdown_table_format,
             chunker_type=chunker_type,
             chunk_max_tokens=chunk_max_tokens,
             chunk_tokenizer=chunk_tokenizer,

docling/cli/remote.py

@@ -37,6 +37,7 @@
     StatusWatcherKind,
 )
 from docling.utils.ocr_language import OcrLanguageResolver
+from docling.utils.table_records import MarkdownTableFormat
 
 _log = logging.getLogger(__name__)
 
@@ -173,6 +174,13 @@ def convert_remote(
             help="Output formats to produce and write locally. Defaults to Markdown.",
         ),
     ] = None,
+    markdown_table_format: Annotated[
+        MarkdownTableFormat,
+        typer.Option(
+            "--markdown-table-format",
+            help="Table output in local Markdown: default pipe tables or labeled cell records.",
+        ),
+    ] = MarkdownTableFormat.DEFAULT,
     chunker_type: ChunkerType = typer.Option(
         ChunkerType.HYBRID,
         "--chunks-type",
@@ -390,6 +398,7 @@ def convert_remote(
                 print_timings=False,
                 export_timings=False,
                 image_export_mode=resolved_image_mode,
+                markdown_table_format=markdown_table_format,
                 chunker_type=chunker_type,
                 chunk_max_tokens=chunk_max_tokens,
                 chunk_tokenizer=chunk_tokenizer,