Convert a Document Archive to Searchable Markdown with MarkItDown

npx terminal-skills install markitdown uv sqlite

Install MarkItDown and show me what our Harbour Street fire strategy PDF looks like as Markdown.

uv tool install 'markitdown[all]'
markitdown project-archive/2026/harbour-street/fire-strategy-rev-c.pdf -o fire-strategy-rev-c.md
markitdown project-archive/2026/harbour-street/cost-plan-stage-3.xlsx

Convert everything under project-archive/ to Markdown. Keep the folder structure and give me a report of what worked.

# /// script
# requires-python = ">=3.10"
# dependencies = ["markitdown[all]"]
# ///
import csv
from pathlib import Path

from markitdown import FileConversionException, MarkItDown, UnsupportedFormatException

SOURCE, TARGET = Path("project-archive"), Path("archive-md")
WANTED = {".pdf", ".docx", ".pptx", ".xlsx", ".xls", ".msg", ".html", ".csv"}

md = MarkItDown(enable_plugins=False)
rows = []
for path in sorted(SOURCE.rglob("*")):
    if not path.is_file() or path.suffix.lower() not in WANTED:
        continue
    try:
        text = md.convert_local(path).markdown.strip()
    except (FileConversionException, UnsupportedFormatException) as exc:
        rows.append([str(path), "failed", 0, type(exc).__name__])
        continue
    out = TARGET / path.relative_to(SOURCE).with_suffix(".md")
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_text(text + "\n", encoding="utf-8")
    rows.append([str(path), "empty" if len(text) < 50 else "ok", len(text), str(out)])

with open("conversion-report.csv", "w", newline="", encoding="utf-8") as fh:
    csv.writer(fh).writerows([["source", "status", "chars", "detail"], *rows])

for status in ("ok", "empty", "failed"):
    print(status, sum(1 for r in rows if r[1] == status))

uv run convert_archive.py

ok 318
empty 19
failed 3

19 files came out empty. They are scanned surveys. Can you get the text out of those?

# /// script
# requires-python = ">=3.10"
# dependencies = ["markitdown[all]", "markitdown-ocr", "openai"]
# ///
import csv
from pathlib import Path

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(enable_plugins=True, llm_client=OpenAI(max_retries=5), llm_model="gpt-4o")

with open("conversion-report.csv", encoding="utf-8") as fh:
    scans = [row for row in csv.DictReader(fh) if row["status"] == "empty"]

for row in scans:
    text = md.convert_local(row["source"]).markdown.strip()
    Path(row["detail"]).write_text(text + "\n", encoding="utf-8")
    print(f"{row['source']}: {len(text)} chars")

uv run ocr_scans.py

Put the Markdown into something I can search from the terminal.

import sqlite3
import sys
from contextlib import closing
from pathlib import Path

with closing(sqlite3.connect("archive.db")) as conn:
    conn.execute("PRAGMA journal_mode=WAL")
    conn.execute("DROP TABLE IF EXISTS docs")
    conn.execute("CREATE VIRTUAL TABLE docs USING fts5(path, body)")
    files = sorted(Path("archive-md").rglob("*.md"))
    conn.executemany(
        "INSERT INTO docs (path, body) VALUES (?, ?)",
        [(str(f), f.read_text(encoding="utf-8")) for f in files],
    )
    conn.commit()
    print(f"indexed {len(files)} documents")
    hits = conn.execute(
        "SELECT path, snippet(docs, 1, '[', ']', ' ... ', 10) FROM docs "
        "WHERE docs MATCH ? ORDER BY rank LIMIT 5",
        (sys.argv[1],),
    )
    for path, snippet in hits:
        print(f"{path}: {snippet}")

uv run --no-project build_index.py '"smoke ventilation"'

indexed 337 documents
archive-md/2026/harbour-street/fire-strategy-rev-c.md:  ... stair core relies on natural [smoke ventilation] via a 1.0 m2 vent ...
archive-md/2024/quay-works/fire-strategy-rev-a.md:  ... mechanical [smoke ventilation] to the basement car park ...