docmd-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{docmd_cli-0.1.0 → docmd_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docmd-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Convert PDFs, DOCX, and PPTX to clean, structure-preserving Markdown.
 Project-URL: Homepage, https://github.com/taherzribi/docmd
 Project-URL: Issues, https://github.com/taherzribi/docmd/issues
@@ -107,12 +107,46 @@ native Pango/GObject/Cairo libraries, which `pip` cannot install for you:
 # macOS
 brew install pango
 
-# Debian/Ubuntu
+# Debian/Ubuntu (24.04 and older)
 sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
+
+# Debian trixie (13) and newer: libgdk-pixbuf2.0-0 was renamed
+sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 libffi-dev shared-mime-info
 ```
 
 PDF conversion (the base install) does not need this.
 
+## Image handling
+
+Images default to a text placeholder (`*[... omitted]*`) - no binary data, nothing to
+resolve, safe for RAG chunking:
+
+```python
+markdown = convert("report.pdf")  # image_mode="placeholder" by default
+```
+
+To keep real image links instead, use `image_mode="alt-text"` and pass `output_dir` so
+the image files actually get saved somewhere the links can resolve to:
+
+```python
+from docmd import convert_document
+from docmd.config import ConvertConfig
+
+result = convert_document(
+    "report.pdf",
+    config=ConvertConfig(image_mode="alt-text"),
+    output_dir="output/",
+)
+```
+
+From the CLI, `--image-dir` defaults to the output file's directory when `-o` is given:
+
+```bash
+docmd convert report.pdf -o output/report.md --image-mode alt-text
+```
+
+`image_mode="skip"` drops images entirely - no placeholder, no files.
+
 ## How it works
 
 `docmd` wraps [Marker](https://github.com/datalab-to/marker) with sane defaults and a

{docmd_cli-0.1.0 → docmd_cli-0.1.1}/README.md

@@ -80,12 +80,46 @@ native Pango/GObject/Cairo libraries, which `pip` cannot install for you:
 # macOS
 brew install pango
 
-# Debian/Ubuntu
+# Debian/Ubuntu (24.04 and older)
 sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
+
+# Debian trixie (13) and newer: libgdk-pixbuf2.0-0 was renamed
+sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 libffi-dev shared-mime-info
 ```
 
 PDF conversion (the base install) does not need this.
 
+## Image handling
+
+Images default to a text placeholder (`*[... omitted]*`) - no binary data, nothing to
+resolve, safe for RAG chunking:
+
+```python
+markdown = convert("report.pdf")  # image_mode="placeholder" by default
+```
+
+To keep real image links instead, use `image_mode="alt-text"` and pass `output_dir` so
+the image files actually get saved somewhere the links can resolve to:
+
+```python
+from docmd import convert_document
+from docmd.config import ConvertConfig
+
+result = convert_document(
+    "report.pdf",
+    config=ConvertConfig(image_mode="alt-text"),
+    output_dir="output/",
+)
+```
+
+From the CLI, `--image-dir` defaults to the output file's directory when `-o` is given:
+
+```bash
+docmd convert report.pdf -o output/report.md --image-mode alt-text
+```
+
+`image_mode="skip"` drops images entirely - no placeholder, no files.
+
 ## How it works
 
 `docmd` wraps [Marker](https://github.com/datalab-to/marker) with sane defaults and a

{docmd_cli-0.1.0 → docmd_cli-0.1.1}/docmd/__init__.py

@@ -18,7 +18,7 @@ from docmd.postprocess.image_handling import apply_image_handling
 from docmd.postprocess.table_cleanup import clean_tables
 
 __all__ = ["convert", "convert_document", "ConvertConfig", "ConversionResult"]
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 
 def convert_document(
@@ -26,6 +26,7 @@ def convert_document(
     *,
     filename: str | None = None,
     config: ConvertConfig | None = None,
+    output_dir: str | Path | None = None,
 ) -> ConversionResult:
     """Convert `source` and return the full result (markdown + page count +
     metadata), after docmd's post-processing pass has run.
@@ -33,6 +34,14 @@ def convert_document(
     `source` is either a path to a file, or raw bytes - in which case
     `filename` is required so docmd knows the format (its extension is used
     to pick a converter; the content itself is what gets converted).
+
+    `output_dir`: only meaningful with `config.image_mode == "alt-text"`,
+    which keeps real image links in the output Markdown - those links only
+    resolve if the image files actually exist somewhere, so pass the
+    directory to save them into (typically wherever the output .md file is
+    going). Without it, `alt-text` mode's links point to image filenames
+    that were never written anywhere. `placeholder` (the default) and
+    `skip` modes ignore this - they never reference image files at all.
     """
     config = config or ConvertConfig()
 
@@ -44,11 +53,11 @@ def convert_document(
         try:
             with os.fdopen(fd, "wb") as tmp:
                 tmp.write(source)
-            result = _convert_path(tmp_path, config)
+            result = _convert_path(tmp_path, config, output_dir)
         finally:
             os.unlink(tmp_path)
     else:
-        result = _convert_path(str(source), config)
+        result = _convert_path(str(source), config, output_dir)
 
     return result
 
@@ -58,13 +67,16 @@ def convert(
     *,
     filename: str | None = None,
     config: ConvertConfig | None = None,
+    output_dir: str | Path | None = None,
 ) -> str:
     """Convert `source` (a file path, or bytes + filename) and return the
-    resulting Markdown as a string."""
-    return convert_document(source, filename=filename, config=config).markdown
+    resulting Markdown as a string. See `convert_document` re: `output_dir`."""
+    return convert_document(source, filename=filename, config=config, output_dir=output_dir).markdown
 
 
-def _convert_path(filepath: str, config: ConvertConfig) -> ConversionResult:
+def _convert_path(
+    filepath: str, config: ConvertConfig, output_dir: str | Path | None
+) -> ConversionResult:
     converter = get_converter(filepath)
     result = converter.convert(filepath, config)
 
@@ -73,7 +85,7 @@ def _convert_path(filepath: str, config: ConvertConfig) -> ConversionResult:
         markdown = clean_tables(markdown)
     if config.normalize_headings:
         markdown = normalize_headings(markdown)
-    markdown = apply_image_handling(markdown, result.images, config.image_mode)
+    markdown = apply_image_handling(markdown, result.images, config.image_mode, output_dir)
 
     return ConversionResult(
         markdown=markdown,

{docmd_cli-0.1.0 → docmd_cli-0.1.1}/docmd/cli.py

@@ -47,12 +47,39 @@ def main() -> None:
     show_default=True,
     help="How to represent images in the output.",
 )
-def convert(file: Path, output: Path | None, force_ocr: bool, use_llm: bool, image_mode: str) -> None:
+@click.option(
+    "--image-dir",
+    "image_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Where to save image files in --image-mode alt-text. Defaults to "
+    "the output file's directory when -o is given; without -o, images "
+    "won't be saved unless this is set explicitly.",
+)
+def convert(
+    file: Path,
+    output: Path | None,
+    force_ocr: bool,
+    use_llm: bool,
+    image_mode: str,
+    image_dir: Path | None,
+) -> None:
     """Convert FILE to Markdown."""
     config = ConvertConfig(force_ocr=force_ocr, use_llm=use_llm, image_mode=image_mode)
 
+    if image_mode == "alt-text" and image_dir is None:
+        if output is not None:
+            image_dir = output.parent
+        else:
+            click.echo(
+                "warning: --image-mode alt-text with no -o/--image-dir - "
+                "image links in the output won't resolve to real files. "
+                "Pass --image-dir to save images somewhere.",
+                err=True,
+            )
+
     try:
-        result = convert_document(str(file), config=config)
+        result = convert_document(str(file), config=config, output_dir=image_dir)
     except DocmdError as exc:
         click.echo(f"error: {exc}", err=True)
         sys.exit(1)

{docmd_cli-0.1.0 → docmd_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docmd-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Convert PDFs, DOCX, and PPTX to clean, structure-preserving Markdown."
 readme = "README.md"
 license = { text = "MIT" }

docmd_cli-0.1.1/tests/fixtures/generate_stress_fixtures.py

@@ -0,0 +1,110 @@
+"""Regenerates the stress-test PDF fixtures used to prove post-processing
+fixes real Marker defects, not just hand-crafted markdown strings. See
+tests/test_postprocess_integration.py for stress.pdf, and
+tests/test_postprocess_more_integration.py for the ones generated here.
+
+    python tests/fixtures/generate_stress_fixtures.py
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image as PILImage
+from reportlab.lib import colors
+from reportlab.lib.pagesizes import LETTER
+from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+from reportlab.lib.units import inch
+from reportlab.platypus import (
+    Image,
+    PageBreak,
+    Paragraph,
+    SimpleDocTemplate,
+    Spacer,
+    Table,
+    TableStyle,
+)
+
+FIXTURES_DIR = Path(__file__).parent
+styles = getSampleStyleSheet()
+body = styles["BodyText"]
+h_title = ParagraphStyle("H0", fontSize=28, leading=32, fontName="Helvetica-Bold")
+h_big = ParagraphStyle("H1", fontSize=22, leading=26, fontName="Helvetica-Bold")
+
+
+def generate_running_header() -> None:
+    """4-page document with a bold header drawn at a fixed position on every
+    page (not a flowable heading) - tests whether that gets misdetected as a
+    duplicate heading, and whether structurally identical section headings
+    get assigned consistent levels throughout."""
+
+    def draw_header(canvas, _doc):
+        canvas.saveState()
+        canvas.setFont("Helvetica-Bold", 14)
+        canvas.drawString(72, 740, "CONFIDENTIAL - INTERNAL REPORT")
+        canvas.restoreState()
+
+    doc = SimpleDocTemplate(str(FIXTURES_DIR / "running_header.pdf"), pagesize=LETTER)
+    story = [Paragraph("Quarterly Risk Review", h_title), Spacer(1, 20)]
+    for section in range(1, 5):
+        story.append(Paragraph(f"Section {section}: Findings", h_big))
+        story.append(
+            Paragraph(
+                (f"This is body paragraph content for section {section}. ") * 20,
+                body,
+            )
+        )
+        story.append(PageBreak())
+    doc.build(story, onFirstPage=draw_header, onLaterPages=draw_header)
+
+
+def generate_merged_cells() -> None:
+    """A table with a spanned header cell (merged columns) - tests whether
+    that breaks raw column-count reconstruction."""
+    rows = [
+        ["", "Q1 2026", "", "Q2 2026", ""],
+        ["Region", "Revenue", "Growth", "Revenue", "Growth"],
+        ["West", "$1.2M", "+5%", "$1.4M", "+17%"],
+        ["East", "$0.9M", "+2%", "$1.0M", "+11%"],
+    ]
+    doc = SimpleDocTemplate(str(FIXTURES_DIR / "merged_cells.pdf"), pagesize=LETTER)
+    table = Table(
+        rows,
+        style=TableStyle(
+            [
+                ("GRID", (0, 0), (-1, -1), 0.5, colors.black),
+                ("SPAN", (1, 0), (2, 0)),
+                ("SPAN", (3, 0), (4, 0)),
+                ("BACKGROUND", (0, 0), (-1, 1), colors.lightgrey),
+            ]
+        ),
+    )
+    doc.build([Paragraph("Regional Revenue", h_big), Spacer(1, 10), table])
+
+
+def generate_with_image() -> None:
+    """A PDF with a real embedded image, to test image_handling.py against
+    real Marker image extraction rather than a synthetic dict."""
+    img_path = FIXTURES_DIR / "_gen_chart.png"
+    PILImage.new("RGB", (300, 200), color=(70, 130, 180)).save(img_path)
+
+    doc = SimpleDocTemplate(str(FIXTURES_DIR / "with_image.pdf"), pagesize=LETTER)
+    doc.build(
+        [
+            Paragraph("Revenue Chart", h_big),
+            Spacer(1, 10),
+            Paragraph("See the chart below for regional performance.", body),
+            Spacer(1, 10),
+            Image(str(img_path), width=3 * inch, height=2 * inch),
+            Spacer(1, 10),
+            Paragraph("Chart data is preliminary and subject to revision.", body),
+        ]
+    )
+    img_path.unlink()  # embedded in the PDF now, don't need the source file
+
+
+if __name__ == "__main__":
+    generate_running_header()
+    generate_merged_cells()
+    generate_with_image()
+    print(f"wrote stress fixtures to {FIXTURES_DIR}")

docmd_cli-0.1.1/tests/fixtures/merged_cells.pdf

@@ -0,0 +1,74 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document (opensource)
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/Contents 8 0 R /MediaBox [ 0 0 612 792 ] /Parent 7 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+5 0 obj
+<<
+/PageMode /UseNone /Pages 7 0 R /Type /Catalog
+>>
+endobj
+6 0 obj
+<<
+/Author (\(anonymous\)) /CreationDate (D:20260918162747+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260918162747+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
+>>
+endobj
+7 0 obj
+<<
+/Count 1 /Kids [ 4 0 R ] /Type /Pages
+>>
+endobj
+8 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 500
+>>
+stream
+GasalbAP0N&A70Vp-9o2Wp=eD-b`WU86("e7cKB,5`9lcPa:4qq@P(tY`O,]Za6u")iVSsT_nZ>!'F9Npl'_)WWf&+&uo"M<S;SNJQ\51bEBr"EJNqJ)3nW0U7)Oj#S9a"BWKOQf#t8QG.r]FrE!oel[,R2:^sN$K[+:a_DUPO=;K+'BWcc!<f03nK_'+#AkN:2FjDq_&fu'&q\g6&PA-RZmS&LGZ/\-&1=ej\YEP*'kqZfH'*Q.*mPsGb;(?2K8/2H2#)SB%GBB864%J<+%_J8lZD(cfpUfJE1HFGhRYKCsD@tF+GXn4Q5DPJg5jKR,D^co^2cOum(Tj4?-KdNKH<=DaUo3YuUNtRDBD"5?an\):.+7.VApU&?5,]WJjm4jMU%^&7a/@sV.6'4E@FO!8MV%@c@,@XU"QV-bjt@#hftnF^0\s/C;r#1\/&LrLYfuJQXh9^h\l#gnMn:+3@rCY5Ca+P;!Y*lN\<ILke\iKLrW,hE#lt~>endstream
+endobj
+xref
+0 9
+0000000000 65535 f 
+0000000061 00000 n 
+0000000102 00000 n 
+0000000209 00000 n 
+0000000321 00000 n 
+0000000514 00000 n 
+0000000582 00000 n 
+0000000862 00000 n 
+0000000921 00000 n 
+trailer
+<<
+/ID 
+[<04e44ee2661fab79030feb6409b489d5><04e44ee2661fab79030feb6409b489d5>]
+% ReportLab generated PDF document -- digest (opensource)
+
+/Info 6 0 R
+/Root 5 0 R
+/Size 9
+>>
+startxref
+1511
+%%EOF

docmd_cli-0.1.1/tests/fixtures/running_header.pdf

@@ -0,0 +1,131 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document (opensource)
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/Contents 11 0 R /MediaBox [ 0 0 612 792 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+5 0 obj
+<<
+/Contents 12 0 R /MediaBox [ 0 0 612 792 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+6 0 obj
+<<
+/Contents 13 0 R /MediaBox [ 0 0 612 792 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+7 0 obj
+<<
+/Contents 14 0 R /MediaBox [ 0 0 612 792 ] /Parent 10 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+8 0 obj
+<<
+/PageMode /UseNone /Pages 10 0 R /Type /Catalog
+>>
+endobj
+9 0 obj
+<<
+/Author (\(anonymous\)) /CreationDate (D:20260918162747+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260918162747+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
+>>
+endobj
+10 0 obj
+<<
+/Count 4 /Kids [ 4 0 R 5 0 R 6 0 R 7 0 R ] /Type /Pages
+>>
+endobj
+11 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 361
+>>
+stream
+Gb"/chbJeX'ZTTeMXM0P7+reOn,*7oahf$h(I5uBe\Nf8g"T^lL:@V#9Xn<\1sL5>cgPXF;?g>7VUonlg^u.@#0&qZ0ZS3!1\bLn)`kj$VB`8*[1T7A[`F\ClI_a=bklZ"KF`N"iU%$i#UAp#88Vl:E?<RHkQQ(b*+,Ymh0BO6a-@13fijSb^V1/T.Gi_8?=RK^)\_An,E[*qhfafEonka+'\V(k`\GH_P[ejqrf+$%LV'#RPbkc9$a:QQU0*9sYD1,"I.2U:hB&CP@-`$n?]`j5Jst$IEeeKUP?]Hh2:Ae/Z_GI>Pc,'U/Gqa0i7o<7nWVeV7V).t45PdP??V)cFmmhn5t:`K_"\,!^:87~>endstream
+endobj
+12 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 319
+>>
+stream
+Gb"/c]5E6T(km1*if#]lM/Bf]AEsCEUklDMIfVkK6D^%P=Sh_K/toX>L.Z9E/^*uDk<$*uF"fD[?1T<17$pIa>_)P+dZ^==6?:A3bm4uh);eA@`l*-U&dSW'JW=]Af1?[kKF,VY/)2@E-qk;\9uGS*8p?p=d&_#41X\Y*K!1F/@:II#l=-j@+?T,=L9Ll9hjJH@GBmCn)IeQ%eD!k;bqHpU`^:lP0c'$n@W$bMZO.)66eT9!9ssr<.BBeLc;"W*Q#:fW`P/A">^UekJ+^dk4!EX^HD"!R(fq6\#oTN'!I&n(gZr-VoH+7,0.TP^h#~>endstream
+endobj
+13 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 320
+>>
+stream
+Gb"/c:JZTs(rl#lMW]dB@Tt?^Dn85$Z7okY(I5D`9NEKZn_77t6el+*-/=eE:%S@0IS\^o*6\h/f6e+A'(-tS/jNW[kt05'+ZWnibm4uh);eA@`l*-U&dSW'JbF%qb9Vu.@7'M-!dBG6$Icq0e*q4BdLGCRFPF4<)sO&'_,neS0JR0LFYVH[OI^W/6WeuXmnC6l:#;2$`ksU,;Qi`!2#dh/N5n2T@m$_tLq*\$cRLK!G%Cb35H=B8%U#>;F`uC\YB7D(/[eZ=k30_#jjclamY$P6l@Ci:@pD1d-=i(8#Mf"FY-3&8d=2jLIK3B<S+6~>endstream
+endobj
+14 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 319
+>>
+stream
+Gb"/c]5E6T(km1*if#]lM/Bf]AEsCEUklDMIfVkK6D^%P=Sh_K/toX>L.Z9E/^*uDk<$*uF"fD[?1T<17$pIa>_)P+dZ^==6?:A3bm4uh);eA@`l*-U&dSW'JW=]Af1?[kKF,VY/)2@E-qk;\9uGS*8p?p=d&_#41X\Y*K!1F/@:II#l=-j@+?T,=L9Ll9hjJH@GBmCn)KL\5eD!k;bqHpU`^:lP0c'$n@W$bMZO.)66eT9!9ssr<.BBeLc;"W*Q#:fW`P/A">^UekJ+^dk4!EX^HD"!R(fq6\#oTN'!I&n(gZr-VoH+7,07WM^#6~>endstream
+endobj
+xref
+0 15
+0000000000 65535 f 
+0000000061 00000 n 
+0000000102 00000 n 
+0000000209 00000 n 
+0000000321 00000 n 
+0000000516 00000 n 
+0000000711 00000 n 
+0000000906 00000 n 
+0000001101 00000 n 
+0000001170 00000 n 
+0000001450 00000 n 
+0000001528 00000 n 
+0000001980 00000 n 
+0000002390 00000 n 
+0000002801 00000 n 
+trailer
+<<
+/ID 
+[<71bc982e6efde47f41d5e095c3f3e0e4><71bc982e6efde47f41d5e095c3f3e0e4>]
+% ReportLab generated PDF document -- digest (opensource)
+
+/Info 9 0 R
+/Root 8 0 R
+/Size 15
+>>
+startxref
+3211
+%%EOF

docmd_cli-0.1.1/tests/fixtures/stress.pdf

@@ -0,0 +1,99 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document (opensource)
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R /F3 4 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/BaseFont /Helvetica-BoldOblique /Encoding /WinAnsiEncoding /Name /F3 /Subtype /Type1 /Type /Font
+>>
+endobj
+5 0 obj
+<<
+/Contents 10 0 R /MediaBox [ 0 0 612 792 ] /Parent 9 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+6 0 obj
+<<
+/Contents 11 0 R /MediaBox [ 0 0 612 792 ] /Parent 9 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+7 0 obj
+<<
+/PageMode /UseNone /Pages 9 0 R /Type /Catalog
+>>
+endobj
+8 0 obj
+<<
+/Author (\(anonymous\)) /CreationDate (D:20260918161648+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260918161648+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
+>>
+endobj
+9 0 obj
+<<
+/Count 2 /Kids [ 5 0 R 6 0 R ] /Type /Pages
+>>
+endobj
+10 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1689
+>>
+stream
+Gat%d>AkH>&;B$?/,6=ZDEt88?QOPc$5>dYfE1p9`bWVGCq6k<+TK1:mL7&l`"<A%M7E/F_m<"-*3E`qrQ+6l0+X$?\n40VOA%.4^1G`o$sS3ln(24PSk1&Q?nSG^Ve]bQ[_"Uo^F%,tl$"2s/;hQ2B2L/)+a%&/OK.UcG5f\Fj3.+M?!VBgB6H:!D0PlLf_QOk^LJ';Ql:HL5Ki3GjQ:BagAep`o1uRMme)&,NkLL^dtX;nbnI!:-Dij_:]00_ZXGe&P.93%Z.nZ+mD"\JpAXk\](BLFhJr88&%3GGm^J6-ZFa")`7jE9etgJfSC[=Z?I$UY?*g(1FsT!R0_[%FDldJfs%V;j'5rS5b/dS/)AhY8mZP5,MtO`r.B-[^9#jViH(F,bdp8nQ<DceuPci**j&f"Pe/'YD4jHX"<d!HSnaU0QN[eI<:)3J;J%^>W5)uKX]q21sf?\eA#]N?@PGAlmZ]khH6j!WV!"Y3-j(UN(rjLKDO#Kcnf$:#!0DhrK*WWMf7Hsmboe^('"7RErGL=chJ3>&Hqhb/"q$\h\^ar$?JcJ2)%2]3K4=J7(Bfo$&"RN%aZ#M,=Hns!Aa2e.][F[\UTNP+O:4aSg;,@?!5l_GLE#f!3#T$,u+YfUq^W.!88/*R^QII/?6;I[f4TH!^EN^<0l2d4%UI1Xu+IDa\8e6NPVZG+i&0@q6+uBcKkWtNgE8#FQ!eOQM_hgX=>8fg1"uuYo2KGQ:/][N$6Lr5^6U3=5C@$!QA<qtsJ3aa^KCdmq`hPpf^n)+5\h*s1/?*VB6'>DT63@E`!"[q+W>]r9P(4jfSEr$7jJMrT"Xuqo*2*Og*.WfP\FC"BjiAK5:pJ=YOIHB8+TY.K7"tht#K;=k6NWu0o_;0W5]@?(V?A/A&=F.B*i.lFd4#*!C;VLTBaG&?HH;1u,jHO?!lBSKgpWe#lENLDTQIXj+?F3\ErqN'M9H83&'FKOl'tRN95@FR[Xd-YL^XV]U*)3>+?X>X<@_"@+CN;c-TXsf<2MqC"=-hSR1g,QN8`@93<<:Zq5!J@IBJ+YUkjs:8>7:`.Ngk+jE$HD$HSf8j>q\i_+>6,'p(gPA6(s?E0;_=B*DhF/LO9%.j-l%,,54&W/-B>#S/OJ?)45^=Y9T2FIt'+2go$Z_ZGuDW!.erJ-YOg1iuhbp4ORAk6o@*K#k0H,RPa5!l@;q2AbSaJ1S+k@](Znl?*/r']QtB>3mdEfYMO)l'N$/r4mO1JNpY1.h9m/r5&kGm&\097Sl2O3[=EkLg[j.^`KRBOTE9NS=mjHE\,34agIl'JN`ss_0!CXW'#TZKs7oaq@*KcJ;W.X'/'p.^+FHhK'N-[Z!_kRku7Y<?O,FM=s^QKCpLdm?_)U#%kNc*R0N0A40BTp"ce$raKNV`9RjdmHgT!@c;p6Z0<`,4n-+%XCtR9;&F$L!XoK["F<U.J$1;am%naZlWfRF]@&o.TTG4c5$>E<DZ<D`!?pVi5Goi3%YF=W?.CcC'*gD8URccscW2b+aP_,j'MaMP#WoeS'$GL8H#Gkh/k'9c1\n[fAV')i$H%6&9X6+\($DD4+#Gp@Yk'9c1VJ;\-V4ajNGu+jBDCuFDA(<X^>5P>+5;]hAG-,Y,ID;h[F\cgf9Ko>alhp"OO$gtn1KW^7LPdo@S\n^#5?3sco"gefo1,m1Spo>FImINnLB~>endstream
+endobj
+11 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 1195
+>>
+stream
+Gasb[>E9FX&4YRK/,[a)J=<RCD>SI"fp,SD"@V6p"?cj#/hiJlr]\%qg$U#d=<j3ClQhaZEITDF`l!j.s*qUgm*>e2iuc*jA;<f)oNnlAC\I%tqlpf"$>9'!0kFp@6FaaRdV:#Ze)0n$]A)fXV'V=/m&akQKk'j-]6pmDl*USDm<E@nTinm_h%ll`B87H"m/;8'p$VN64+(On(JcHspJNm0pX>K?5.4jKY8>fg3FV!_D>aE[qm`4e-.i#_(A>Z9iqW:f)@`ku7&&Pnh&jCn-3+5`-64N;A<_?gGRk!'J1%+).i-hEfY=TX*nJY#,O&4*f%]55n)MVeLaFKF3?a5S*B6,(4=t=1M^"_7];;("8^tfRiCF:V(PNPNKn'<"*Xk@8:KG\CFANYQp?hU^F(^0X1H$tk0$`Y\QZNA0"!m/R@*eq!Z@97%dQ518q>2SMfBs^E]*Q5`,Y96B2b"f)Mu]H>Rg%EN&[5o,jBsS_R#F(Q*K9&+(O@bP!B_rT88_T::iaVHnPJ.$'NF7j"<kJcKcUXh!)FdASaU)5)Y&qd#iBqqTn$A\16`?5.+EgS&AjW1Zd9^,KTJ>A[#Ds*E_35$PlX4p2AS>-#Q[&eOE/'V^S)4Ce=I>"0GG'l5+OY7+2&,;%LbN$:Wh!YFhY--7ur=T:kPHl?nrp]"XMKO*#9*WFGMqI%h$IM0bVC7J7rsILBSsNM&[9BT$/sZ?7)B[YgfiIA"hgr->7Ern=)u4Z.T<5C!j8.oU+Q,!l9oYJZWpbaXP&Dd\+Wm(Q1)$R\cfm"?S@_R)(I12%)6$+IGk;o[k^)E'+]<Z1N8@.(.%d?jc*9!h,VfoHjZdCfUR[Edm_F*Xq\fEFF5KW;"'(kCUtGhd^YH".`RIB82##R:,CDDsi$o*n]?Gj>6j\^0'Mdd'LO0j$>fNrtkZ_K6-hbIs67WI[9$j%3F0^igP;:"fXk?Dm&VX,ujFMHs/jdHO[L#Rp((aD_L]09n/qGcH#lcKZBpIF8:b:C[ej`KO3*;51\Y3Xa-6Dnu2nQet4V?>6tZg8EX_2/kWr<:2s,<VYQ22U(gS%)],=nRc\U@L%%QI+YHC'29k0U'UGVA>a0hXR`@iGaJO5fPQGcmo@htY]mXa7S'JH#2GIOWgT'u=DOS!sh.B%D\fJpoa]j;Ibtom8"7Wl:C*ioQH*\*Up+H<Jh(LG8*K^~>endstream
+endobj
+xref
+0 12
+0000000000 65535 f 
+0000000061 00000 n 
+0000000112 00000 n 
+0000000219 00000 n 
+0000000331 00000 n 
+0000000450 00000 n 
+0000000644 00000 n 
+0000000838 00000 n 
+0000000906 00000 n 
+0000001186 00000 n 
+0000001251 00000 n 
+0000003032 00000 n 
+trailer
+<<
+/ID 
+[<363e53a615617ff0e3d5d99a726c39b8><363e53a615617ff0e3d5d99a726c39b8>]
+% ReportLab generated PDF document -- digest (opensource)
+
+/Info 8 0 R
+/Root 7 0 R
+/Size 12
+>>
+startxref
+4319
+%%EOF

docmd_cli-0.1.1/tests/fixtures/with_image.pdf

@@ -0,0 +1,85 @@
+%PDF-1.4
+%���� ReportLab Generated PDF document (opensource)
+1 0 obj
+<<
+/F1 2 0 R /F2 3 0 R
+>>
+endobj
+2 0 obj
+<<
+/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
+>>
+endobj
+3 0 obj
+<<
+/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
+>>
+endobj
+4 0 obj
+<<
+/BitsPerComponent 8 /ColorSpace /DeviceRGB /Filter [ /ASCII85Decode /FlateDecode ] /Height 200 /Length 255 /Subtype /Image 
+  /Type /XObject /Width 300
+>>
+stream
+Gb"0<!=8`+$j3/G$ar_:p`'OXFAZ%<<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3%!<E3&lcN@.'qUP~>endstream
+endobj
+5 0 obj
+<<
+/Contents 9 0 R /MediaBox [ 0 0 612 792 ] /Parent 8 0 R /Resources <<
+/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ] /XObject <<
+/FormXob.33833d909d83ea6c265a8c21bc2adfc1 4 0 R
+>>
+>> /Rotate 0 /Trans <<
+
+>> 
+  /Type /Page
+>>
+endobj
+6 0 obj
+<<
+/PageMode /UseNone /Pages 8 0 R /Type /Catalog
+>>
+endobj
+7 0 obj
+<<
+/Author (\(anonymous\)) /CreationDate (D:20260918162747+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260918162747+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+  /Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
+>>
+endobj
+8 0 obj
+<<
+/Count 1 /Kids [ 5 0 R ] /Type /Pages
+>>
+endobj
+9 0 obj
+<<
+/Filter [ /ASCII85Decode /FlateDecode ] /Length 341
+>>
+stream
+Gas2Dc#/.f&;9L7`>mVRLi'qpCYIq#93Vn>)RC\Wr1o(ClJ'pXW)@>_<jLf6mPgp"?uEK(9abcYCj$e'+KrT@0Ll%nk</MJpiSAmO@m&pV_PC.IGiEG0?N%WNZoT.7EC=*pI5tac@j5j[c9OA,P$VHr9EDt4n\HD.bU8gQp"_qk*$2Aq+cV55VSBL$>TDj<5"!^IGK+Y_258j\%4@0Y%C;Y1)%tJ&gld<K$.;Wj(jprB'6rOI1\r2MP;k9=fEUndKl7SAHXZFct-cJT)/JAE@,Ug&>uSJh_)_]N`(oVomi7&VJb]pgMc;Y`,I>hA4DNkCZSG)Y*W]5#^uc+qh+V~>endstream
+endobj
+xref
+0 10
+0000000000 65535 f 
+0000000061 00000 n 
+0000000102 00000 n 
+0000000209 00000 n 
+0000000321 00000 n 
+0000000766 00000 n 
+0000001022 00000 n 
+0000001090 00000 n 
+0000001370 00000 n 
+0000001429 00000 n 
+trailer
+<<
+/ID 
+[<a37d360f94bbcb79be8c654f5f762036><a37d360f94bbcb79be8c654f5f762036>]
+% ReportLab generated PDF document -- digest (opensource)
+
+/Info 7 0 R
+/Root 6 0 R
+/Size 10
+>>
+startxref
+1860
+%%EOF

docmd_cli-0.1.1/tests/test_postprocess_integration.py

@@ -0,0 +1,68 @@
+"""Integration test proving post-processing fixes a *real* Marker bug, not
+just hand-crafted markdown strings (see tests/test_postprocess.py for those -
+useful for fast unit coverage, but circular as evidence of real-world value,
+since the input was written to match what the regex expects).
+
+fixtures/stress.pdf has a 45-row table that spans a PDF page break
+(reportlab's repeatRows=1, matching how real multi-page business reports are
+laid out). Marker processes pages independently, so it renders this as two
+separate Markdown tables with a duplicated header row in between - this test
+converts the real PDF through real Marker, confirms that split actually
+happens (so this test fails loudly if a future Marker version stops doing
+it, rather than silently testing nothing), then confirms docmd's full
+convert() pipeline merges them back into one continuous table.
+"""
+
+from pathlib import Path
+
+from docmd import convert_document
+from docmd.config import ConvertConfig
+from docmd.converters.marker_converter import MarkerConverter
+
+FIXTURE = Path(__file__).parent / "fixtures" / "stress.pdf"
+
+
+def test_marker_really_does_split_a_page_spanning_table():
+    """Documents the real upstream behavior this feature exists to fix."""
+    raw = MarkerConverter().convert(str(FIXTURE), ConvertConfig())
+    # Raw Marker output pads cell widths with extra spaces for column
+    # alignment (e.g. "| Region  | Rep    |"), so match loosely rather than
+    # on an exact literal string.
+    header_count = sum(
+        1
+        for line in raw.markdown.splitlines()
+        if "Region" in line and "Revenue" in line and line.strip().startswith("|")
+    )
+    assert header_count >= 2, (
+        "expected Marker to render the page-spanning table as 2+ blocks "
+        "with a repeated header - if this fails, Marker's behavior changed "
+        "and test_docmd_merges_the_split_table's premise needs revisiting"
+    )
+
+
+def test_docmd_merges_the_split_table():
+    result = convert_document(str(FIXTURE))
+    markdown = result.markdown
+
+    # One continuous table: header appears exactly once, not once per page.
+    assert markdown.count("| Region | Rep | Deal | Revenue | Status |") == 1
+
+    # All 45 data rows survived the merge - none silently dropped, including
+    # the ones on both sides of where the original page-break duplicate
+    # header used to sit (rows 27 and 28 of 45).
+    for i in range(1, 46):
+        assert f"Deal-{1000 + i}" in markdown
+
+    # The row right after the original page-break duplicate header is still
+    # present as a *data* row, not swallowed along with the header.
+    assert "North | Rep 28 | Deal-1028" in markdown
+
+
+def test_docmd_promotes_first_heading_to_h1():
+    """Source PDF's title paragraph rendered as H2 in raw Marker output (its
+    font size wasn't visually distinct enough for Marker's heading-level
+    detection) - docmd promotes a document's opening heading to H1 rather
+    than leaving it start at H2 with no root."""
+    result = convert_document(str(FIXTURE))
+    first_line = result.markdown.splitlines()[0]
+    assert first_line.startswith("# ") and "Annual Sales Report" in first_line

docmd_cli-0.1.1/tests/test_postprocess_more_integration.py

@@ -0,0 +1,91 @@
+"""More real-Marker-bug regression tests, generated by "do many more tests" -
+each one converts a real PDF through real Marker and checks docmd's output,
+not hand-written markdown. See test_postprocess_integration.py for the
+first one (page-spanning table). Honest negative results are included too,
+not just wins - see test_merged_header_cells_survive_cleanly.
+"""
+
+from pathlib import Path
+
+from docmd import convert_document
+from docmd.config import ConvertConfig
+from docmd.converters.marker_converter import MarkerConverter
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def test_inconsistent_heading_levels_get_normalized_to_match():
+    """running_header.pdf has 4 structurally identical section headings
+    (same paragraph style). Raw Marker assigns them *different* levels -
+    Section 1 comes out H3, Sections 2-4 come out H2, a genuine model
+    inconsistency, not a deliberately constructed skip. Confirm that first,
+    then confirm docmd normalizes them to be consistent."""
+    raw = MarkerConverter().convert(str(FIXTURES / "running_header.pdf"), ConvertConfig())
+    assert "### **Section 1: Findings**" in raw.markdown
+    assert "## **Section 2: Findings**" in raw.markdown
+
+    result = convert_document(str(FIXTURES / "running_header.pdf"))
+    for n in range(1, 5):
+        assert f"## **Section {n}: Findings**" in result.markdown
+        assert f"### **Section {n}: Findings**" not in result.markdown
+
+
+def test_running_header_does_not_leak_into_output():
+    """The bold text drawn at a fixed position on every page ("CONFIDENTIAL
+    - INTERNAL REPORT") never appears in Marker's raw markdown at all -
+    Marker's own PageHeaderProcessor already strips repeated page headers.
+    This is an honest negative result: docmd's duplicate-heading dedup
+    wasn't needed here because Marker solved it upstream. Pinned as a
+    regression test so a future Marker version silently changing this
+    doesn't go unnoticed."""
+    raw = MarkerConverter().convert(str(FIXTURES / "running_header.pdf"), ConvertConfig())
+    assert "CONFIDENTIAL" not in raw.markdown
+
+
+def test_merged_header_cells_survive_cleanly():
+    """merged_cells.pdf has a spanned header cell (colspan). Honest negative
+    result: Marker already renders this as a clean, consistent 5-column
+    table (blank cells for the spanned columns) with no ragged rows -
+    nothing for table_cleanup.py to fix here. Pinned so this doesn't
+    silently regress, and so nobody assumes this case needs a fix it
+    doesn't need."""
+    raw = MarkerConverter().convert(str(FIXTURES / "merged_cells.pdf"), ConvertConfig())
+    table_lines = [l for l in raw.markdown.splitlines() if l.strip().startswith("|")]
+    # spanned quarter-label row, column-label row, separator, 2 data rows.
+    assert len(table_lines) == 5
+    assert all(line.count("|") == 6 for line in table_lines)  # 5 columns, consistent
+
+    result = convert_document(str(FIXTURES / "merged_cells.pdf"))
+    assert "West" in result.markdown and "$1.2M" in result.markdown
+
+
+def test_alt_text_mode_actually_saves_the_image(tmp_path):
+    """Regression test for a real bug found while doing this testing:
+    `output_dir` was accepted by apply_image_handling() but never actually
+    threaded through from convert()/convert_document(), so alt-text mode
+    produced a markdown image link pointing to a file that was never
+    written anywhere. Fixed in docmd/__init__.py and docmd/cli.py."""
+    result = convert_document(
+        str(FIXTURES / "with_image.pdf"),
+        config=ConvertConfig(image_mode="alt-text"),
+        output_dir=tmp_path,
+    )
+    assert "![Image 1](" in result.markdown
+
+    saved_images = list(tmp_path.glob("*.jpeg"))
+    assert len(saved_images) == 1
+    assert saved_images[0].name in result.markdown
+    # A real, valid JPEG - not an empty/placeholder file.
+    assert saved_images[0].read_bytes()[:2] == b"\xff\xd8"
+
+
+def test_placeholder_mode_never_writes_image_files(tmp_path):
+    """The default mode should never touch the filesystem, even if an
+    output_dir happens to be passed."""
+    result = convert_document(
+        str(FIXTURES / "with_image.pdf"),
+        config=ConvertConfig(image_mode="placeholder"),
+        output_dir=tmp_path,
+    )
+    assert "omitted" in result.markdown
+    assert list(tmp_path.iterdir()) == []