# Docling Convert

> Convert local files or URLs with a locally deployed Docling Gradio service into Markdown, JSON, HTML, text, or DocTags, with OCR and image export support. Use when handling `.docx`, `.pdf`, `.pptx`, `.xlsx`, `.html`, images, or web pages for document-to-Markdown conversion, batch conversion, image extraction, or Docling-based parsing through `http://localhost:5001`.

- Skill: `mhliulgy/docling-convert` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add mhliulgy/docling-convert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mhliulgy/docling-convert/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: mhliulgy (https://skillmd.com/u/mhliulgy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mhliulgy/docling-convert

---


# Docling Convert

Use this skill to run document conversion through a local Docling service instead of ad-hoc parsing.

## Quick Start

- Assume the Docling service is already deployed locally and reachable at `http://localhost:5001`.
- Prefer `scripts/docling_gradio_convert.py` for repeatable work. It wraps the documented Gradio API and handles submission, waiting, and archive extraction.
- Install the required client before running the script:

```bash
pip install gradio_client
```

- If URL jobs need placeholder image repair and `beautifulsoup4` is missing, install it:

```bash
pip install beautifulsoup4 lxml
```

- Read `references/gradio-api-workflow.md` only when changing endpoints, tuning advanced options, or debugging output layouts.

## Workflow

1. Classify the inputs.
   Use the file flow for local paths and the URL flow for web pages. Do not mix files and URLs in one API request; if the user gives both, run two jobs.

2. Choose the outputs.
   Default to `md`.
   Add `json` when the user also needs structured output.
   Add `html`, `text`, or `doctags` only when the task explicitly needs them.

3. Choose the processing options.
   Keep `pipeline=standard`, `ocr=true`, `force_ocr=false`, `pdf_backend=dlparse_v4`, and `table_mode=accurate` unless the task calls for a change.
   Keep `image_export_mode=embedded` when the goal is to preserve extracted images. The wrapper post-processes embedded Markdown images into real files under `images/`.
   Turn on enrichment flags only when the user explicitly wants code, formulas, picture classification, or picture descriptions.
   For URL jobs, the wrapper also normalizes Markdown output by injecting stable front matter, preserving unknown existing front matter keys, and prepending `# title` only when the document body does not already start with that title.

4. Run the wrapper script.

```bash
# Single file
python scripts/docling_gradio_convert.py report.pdf

# Batch files with Markdown + JSON
python scripts/docling_gradio_convert.py "*.pdf" --to-format md --to-format json

# Single URL
python scripts/docling_gradio_convert.py https://example.com/article --output-dir ./article

# Single URL with optional sidecar files
python scripts/docling_gradio_convert.py https://example.com/article --save-source-html --save-manifest

# Alternate service URL
python scripts/docling_gradio_convert.py slides.pptx --service-url http://localhost:5001
```

5. Verify the extracted results.
   The script always requests `return_as_file=true`, downloads the returned artifact, extracts it into the chosen output directory, rewrites embedded Markdown images into local files when needed, and for URL conversions can backfill Docling image placeholders from the source page.
   URL Markdown outputs are post-processed after extraction so the final `.md` contains normalized front matter plus a title heading when needed.
   Inspect the produced Markdown plus any extracted image assets before presenting the result to the user.

## Output Conventions

- Prefer the script defaults unless the user asks for a different layout.
- For a single local file, extract into a sibling directory named after the input stem.
- For a single URL, extract into `docling-<slug>` under the current working directory.
- For multiple inputs, extract into `docling-files-batch` or `docling-urls-batch` under the current working directory, unless `--output-dir` is supplied.
- If the user supplies `--output-dir` and both file and URL jobs are needed, the script creates `files/` and `urls/` subdirectories to keep the results separate.

## Script Notes

- Use `scripts/docling_gradio_convert.py --dry-run ...` to verify grouping, endpoint selection, and destination paths without contacting the service.
- Let the script infer the Gradio UI URL from the service root. `http://localhost:5001` becomes `http://localhost:5001/ui/`.
- Let the script ask `/change_ocr_lang` for the default OCR language set when `--ocr-lang` is not provided. Fall back to `en,fr,de,es` if the endpoint is unavailable.
- Treat a missing `gradio_client` installation as an environment issue and fix it with `pip install gradio_client` instead of rewriting the workflow.
- If a URL conversion returns `<!-- 🖼️❌ Image not available ... -->`, let the wrapper fetch the source page, collect article images, download them into `images/`, and replace placeholders in order.
- URL post-processing fetches the source page once and reuses that HTML for metadata extraction, title normalization, and optional sidecar output instead of maintaining a separate capture flow.
- Existing front matter keys outside the managed set are preserved; managed keys are `url`, `title`, `description`, `author`, `published`, `cover_image`, `language`, `captured_at`, `converter`, `pipeline`, `ocr`, and `ocr_lang`.
- Use `--save-source-html` to write `source.html` for single URL jobs, and `--save-manifest` to write `manifest.json` with the conversion settings and output summary.
- Sidecar files are skipped for multi-URL batch jobs even if the flags are set.

## Resources

### `scripts/docling_gradio_convert.py`

Use this wrapper for deterministic Docling conversions. It supports:

- local files, URLs, and wildcard expansion
- batch conversion
- OCR and enrichment flags
- archive download and extraction
- output directory planning
- dry-run validation

### `references/gradio-api-workflow.md`

Read this reference when you need:

- the endpoint mapping for file versus URL jobs
- the argument names expected by the Gradio client
- the `wait_task_finish` tuple layout
- the defaults adopted by this skill