InkDoc

Turn any document into clean, AI-ready Markdown — most conversions run right on your machine

A unified desktop workbench and local REST API that bridges Microsoft MarkItDown, Docling, a broad-format Markit engine and the GLM-OCR model into one zero-friction Markdown pipeline — with collision-safe auto-saving.

Website  •  Download  •  Quickstart  •  Engines  •  REST API  •  Contributing

_{Drop a file, directory, or URL → conversion starts instantly → clean Markdown is auto-saved to ~/Downloads with collision-safe naming.}

Ready-to-run desktop packages with every dependency and runtime bundled — no Python installation required.

# Windows
Get-FileHash .\inkdoc-setup.exe -Algorithm SHA256

# macOS / Linux
shasum -a 256 inkdoc-macos.zip

gh attestation verify inkdoc-setup.exe --repo AbdoslamB/inkdoc

_{Detailed release notes, asset bundles, and SHA-256 checksums are available on the GitHub Releases page.}

Multi-Engine Conversion Pipeline Intelligently dispatches between Microsoft MarkItDown (fast everyday documents), Docling (deep layout analysis and TableFormer reconstruction), Markit (InkDoc's own broad-format extractors, inspired by Shift Labs' Markit, for formats like EPUB, YAML and Jupyter Notebooks) and GLM-OCR (a downloadable OCR model for scans, photos, math and tables). Auto picks the engine per file, and every PDF is checked for missing text so a silently incomplete conversion gets a warning and a one-click fix.

Single Source of Truth Interface The native desktop executable (Edge WebView2 on Windows, WebKit on macOS/Linux) and the local web workbench (http://127.0.0.1:13118/InkDoc) run the exact same user interface without code divergence.

Zero-Friction Auto-Save Documents convert asynchronously and are automatically saved to ~/Downloads the moment they finish, with collision-safe numbered suffixes (e.g., report (1).md). No manual export required.

Embedded Local REST API FastAPI backend with streaming multipart uploads, URL conversion, interactive OpenAPI Swagger documentation (/docs), and a headless server mode for programmatic pipelines and CI/CD.

InkDoc provides four dedicated conversion routes, switchable at any time from the UI pills or via API query parameters, plus Auto, which picks the route for each file.

flowchart LR
    IN(["📥 File · Folder · URL"]) --> SEL{"Auto, or<br/>your choice"}
    SEL -->|"Office, HTML, media"| MD["MarkItDown"]
    SEL -->|"Complex and scanned PDFs"| DL["Docling"]
    SEL -->|"EPUB, notebooks, feeds"| MK["Markit"]
    SEL -->|"Hard scans, photos, math"| GL["GLM-OCR"]
    MD --> OUT(["📝 Clean Markdown"])
    DL --> OUT
    MK --> OUT
    GL --> OUT
    OUT --> SAVE[("💾 ~/Downloads<br/>collision-safe naming")]

    classDef engine stroke:#10b981,stroke-width:2px;
    class MD,DL,MK,GL engine;

GLM-OCR (zai-org, 0.9B parameters, MIT license) is a small vision-language model built for OCR. InkDoc runs it locally through llama.cpp's llama-server in a separate process, so it works on a normal laptop with no Python ML stack.

• One click, after a clear warning. Settings → Processing Engines → GLM-OCR → Download first shows the download size (~1.45 GB) and that processing is much slower than the other engines, and only downloads after you confirm.
• Official source first, mirror fallback. The model comes from Hugging Face and the runtime from the llama.cpp releases. If either fails for any reason (blocked, down, rate limited, or a wrong hash), the same files come from InkDoc's own GitHub release. Every file is checked against SHA-256 hashes pinned in InkDoc, and the runtime files are re-hashed before every launch.
• Tested before use. The install is only complete when the model reads a known test image on your computer, which also measures its speed there.
• Speed. On a laptop CPU (Ryzen 9 4900HS) expect roughly 15–40 seconds per page; with GPU acceleration (Settings, Vulkan on Windows/Linux for NVIDIA, AMD and Intel graphics, Metal on Apple Silicon) about 4–7 seconds per page on the same laptop's integrated Radeon. Long jobs show "Page 7 / 30 · ~8 min left" with a Cancel button, and InkDoc asks before starting a job longer than 5 minutes.
• Private and offline after install. Documents converted with GLM-OCR never leave your computer; the server listens on the loopback interface only, with a per-session key, and runs with downloads disabled.
• Auto uses it only when it is quick enough. For scans and images, Auto prefers GLM-OCR when it is installed and the file should finish within 5 minutes on your computer; otherwise it uses Docling (or tells you how to run GLM-OCR yourself).

Auto (the default for new installs) takes one quick look at each file and picks the engine: MarkItDown for digital documents, GLM-OCR or Docling for scanned pages and images when installed (GLM-OCR only for files it should finish within 5 minutes), and Markit for YAML and XML. It tells scanned pages apart from cover photos, so an annual report with a photo on the front stays on fast MarkItDown. Auto only uses what is already on disk: it never downloads a model, and when Docling would help but is missing it converts with MarkItDown and suggests installing Docling.

After every PDF conversion, with any engine, InkDoc compares the Markdown with the PDF's own embedded text. If part of it is missing (scanned pages MarkItDown can't read, fonts that come out as (cid:12), a table Docling dropped) the item shows a warning such as "~18% of the source text may be missing (pages 4, 7). Try Docling." with a one-click Re-convert button and a Details list. The saved file is never changed, and you can turn the check off in Settings.

When Auto's first result fails the check and Docling is installed, Auto converts once more with Docling and keeps the better result, and says so. That is the only automatic re-run: with an explicitly chosen engine, InkDoc warns and leaves the choice to you.

Each format has a recommended engine, which is what Auto uses, and you can always switch if a document needs a different approach.

• Python 3.10+ (python.org)
• (Optional) ffmpeg on your system PATH, if you process audio transcription

git clone https://github.com/AbdoslamB/inkdoc.git
cd inkdoc

# Create and activate a virtual environment
python -m venv .venv

# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate

# Install dependencies
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

# Native desktop window (Edge WebView2 / WebKit)
python main.py

# Headless REST API server (no GUI window)
python main.py --headless --port 13118

# Platform helper scripts
run.bat       # Windows
./run.sh      # macOS / Linux

Once running, open the local web workbench at http://127.0.0.1:13118/InkDoc (or /MarkItDown).

InkDoc ships with an embedded REST API for automated pipelines, agents, and developer workflows. Complete endpoint schemas and cURL documentation are in API.md.

# Convert a PDF with Docling and auto-save straight to Downloads
curl -F "file=@annual_report.pdf" \
  "http://localhost:13118/convert/file?engine=docling&save_to_downloads=true"

import requests

response = requests.post(
    "http://localhost:13118/convert/url",
    json={"url": "https://en.wikipedia.org/wiki/Markdown", "save_to_downloads": True}
)

data = response.json()
print(f"Saved to: {data.get('saved_to_downloads')}")
print(data["markdown"][:200])

The interactive Swagger UI is available at http://localhost:13118/docs while the server is running.

inkdoc/
├── app/
│   ├── core/                  # Core conversion domain & engine adapters
│   │   ├── converter.py       # MarkItDown orchestrator & collision-safe auto-save
│   │   ├── queue_model.py     # EngineKind enum (incl. auto), QueueItem data definitions
│   │   ├── auto_engine.py     # Auto engine: per-file routing & verified Docling retry
│   │   ├── pdf_probe.py       # Fast PDF text-layer & scanned-page probe (pypdfium2)
│   │   ├── quality_check.py   # Missing-text check for PDF conversions
│   │   ├── jobs.py            # Conversion progress & cancel registry
│   │   ├── glm_ocr_catalogue.py  # GLM-OCR pins, hashes & sources (+ signed online catalogue)
│   │   ├── glm_ocr_manager.py    # GLM-OCR download (upstream → mirror), self-test, update, remove
│   │   └── engines/           # Docling, Markit & GLM-OCR adapters; llama-server management
│   ├── server/                # Embedded FastAPI backend
│   │   └── server.py          # REST endpoints (/convert, /convert/progress, /health, /extensions)
│   ├── desktop/               # Native desktop runner
│   │   └── runner.py          # pywebview window manager & loopback orchestration
│   └── ui/                    # Shared Web & Desktop user interface
│       ├── index.html         # Application DOM structure & dropzone
│       ├── style.css          # Inkbench Obsidian design system (CSS custom properties)
│       └── app.js             # Reactive client-side logic & marked.js preview
├── tests/                     # Automated integration test suite
├── scripts/                   # Build, release & calibration tooling
├── examples/                  # Developer client scripts & cURL examples
├── docs/                      # GitHub Pages landing page website
├── API.md                     # Dedicated REST API reference manual
├── CONTRIBUTING.md            # Contribution guidelines & security policy
├── main.py                    # Unified entry point (Desktop GUI or --headless)
└── requirements.txt           # Python dependencies

# 1. Byte-compile all sources (verifies syntax across all modules)
python -m compileall -q main.py app tests examples scripts

# 2. Run the whole test suite, exactly as CI does
python -m pytest tests/

# 3. UI logic tests (need Node.js; CI runs them on Linux)
node tests/auto_engine_ui.test.js
node tests/docs_release_selector.test.js
node tests/enrichment_addon_ui.test.js
node tests/glm_ocr_ui.test.js
node tests/preview_word_count.test.js

# 4. Verify code style and formatting with Ruff
ruff check .

Contributions, bug reports, and feature proposals are welcome.

• Review CONTRIBUTING.md for architecture guidelines, pull request protocols, and test requirements.
• Report security vulnerabilities confidentially via the Security Policy.

Author & lead maintainer: Abdoslam Baabbad (@AbdoslamB)

InkDoc is built on excellent open-source work. Code and model weights are listed separately because their licenses differ:

EasyOCR is not included: InkDoc's Docling pack uses RapidOCR. The full list of components, including all bundled Python packages, is in THIRD_PARTY_NOTICES.md.

InkDoc's own code is licensed under the MIT License. Third-party components keep their own licenses; see Legal.

InkDoc's MIT License covers only InkDoc's own code. The components and models it uses or downloads stay under their own licenses, including some that are not MIT (such as CDLA-Permissive-2.0, Apache-2.0 and GPL-2.0), and you are responsible for reviewing and following them. You may use a third-party component or model commercially only if, and to the extent that, its own license allows it. See THIRD_PARTY_NOTICES.md, the full texts in LICENSES/, and DISCLAIMER.md, which also explains which features use the internet.

If you copy or redistribute InkDoc's code, in whole or in substantial part, the MIT License requires you to keep InkDoc's copyright notice and license text with it.

Beyond that requirement, if InkDoc helps your project, please credit it where your users can see it, for example in your README or about page:

Uses InkDoc by Abdoslam Baabbad (MIT License).

For papers and reports, GitHub's Cite this repository button (from CITATION.cff) gives a ready-made citation.