feat(latex): add optional Tectonic TikZ rendering

[adityasasidhar]

Resolves #3302

Description

Added an optional TikZ rendering path for the LaTeX backend using Tectonic, with configurable flags and safe fallbacks.

Here's how it works:

1. A user passes a LaTeX source containing a tikzpicture environment.
2. The user enables the TikZ engine option with --tikz-engine. ( tectonic automatically installs the required packages only )
3. The LaTeX backend detects tikzpicture blocks and captures them atomically.
4. A Tectonic render task is scheduled asynchronously while the rest of the document continues processing.
5. The renderer builds a standalone LaTeX document from:
   • the extracted TikZ source
   • the extracted LaTeX preamble
6. If the source document is file-backed, explicitly referenced local TikZ dependencies are staged into the temporary render directory:
   • \input
   • \include
   • \includegraphics
7. Tectonic compiles the staged standalone document.
8. If compilation succeeds, the generated PDF is rasterized into an image and attached to the PictureItem.
9. If compilation fails, times out, produces no PDF, or rasterization fails, the system falls back to storing the original TikZ source as PictureMeta.code.

Configuration added

1. --tikz-engine / -T: Enables optional TikZ rendering with Tectonic.
2. --no-tikz-engine-download: Disables automatic Tectonic download if no binary is present.
3. --tikz-engine-timeout: Sets the timeout for rendering a single TikZ diagram.
4. --tikz-shell-escape: Explicitly enables shell escape during Tectonic compilation. This is optional and remains disabled by default.

I ran testing on 10's of files, but testing on a corpus would be great to capture all kinds of edge cases that could creep in.

Further instead of installing tectonic from the default curl script could pose a threat, so we can choose an appropriate version and store it in the docling hugging face repo where it can simply send a curl request from a safe and known source.

currently we use this

curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net | sh

It could be a hf curl request. Currently I have not added installation support for windows, this should be taken into account for the next commit.

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

[github-actions]

✅ DCO Check Passed

Thanks @adityasasidhar, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[dosubot]

Documentation Updates

1 document(s) were updated by changes in this PR:

What are the detailed pipeline options and processing behaviors for PDF, DOCX, PPTX, and XLSX files in the Python SDK?

View Changes

@@ -247,11 +247,15 @@
 - **Pipeline/Backend**: `SimplePipeline` + `LatexDocumentBackend`
 - **Key Options** (`LatexBackendOptions`):
     - `parse_timeout` (default: 30.0 seconds): Maximum time allowed for parsing a LaTeX document. Set to `None` to disable the timeout. This prevents `pylatexenc` from spinning indefinitely when parsing legacy arXiv documents with complex or malformed macroscopic environments. If parsing exceeds this timeout, the conversion will fall back to raw text extraction rather than structured parsing. A warning will be logged when a timeout occurs.
+    - `tikz_engine` (Optional[Literal["tectonic"]]): The engine to use for rendering TikZ diagrams into images. Set to `'tectonic'` to enable asynchronous image generation. Defaults to `None`.
+    - `tikz_engine_timeout` (float, default: 60.0): The timeout in seconds for rendering a single TikZ diagram.
+    - `tikz_engine_allow_shell_escape` (bool, default: False): Allow Tectonic TikZ rendering to enable shell escape during compilation. Disabled by default for safer rendering of untrusted LaTeX.
 - **Processing**:
     - Parses LaTeX source using `pylatexenc` to extract structured content (sections, equations, tables, etc.)
     - Pre-processes custom macros (e.g., `\be`/`\ee` shortcuts for equations)
     - Timeout enforcement runs parsing in a daemon thread to allow graceful fallback on timeout
-- **Notes**: The `parse_timeout` option is particularly useful for processing legacy arXiv documents that may contain complex or malformed macro environments. To configure the timeout:
+    - **TikZ Rendering**: When `tikz_engine` is set to `'tectonic'`, the backend detects `tikzpicture` environments and renders them asynchronously into images. When Tectonic compilation succeeds, the TikZ diagram is rasterized and stored as an image. When compilation fails, times out, produces no PDF, or rasterization fails, Docling preserves the original TikZ source as fallback code metadata.
+- **Notes**: The `parse_timeout` option is particularly useful for processing legacy arXiv documents that may contain complex or malformed macro environments. CLI flags are available for TikZ rendering: `--tikz-engine` / `-T`, `--tikz-engine-timeout`, and `--tikz-shell-escape`. To configure the timeout:
 
 ```python
 from docling.datamodel.backend_options import LatexBackendOptions

^{How did I do? Any feedback?}  

[codecov]

Codecov Report

❌ Patch coverage is 76.17021% with 56 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/backend/latex/engines/tectonic.py	70.94%	52 Missing ⚠️
docling/backend/latex/handlers/environments.py	87.09%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[PeterStaar-IBM]

lgtm!

[adityasasidhar]

@PeterStaar-IBM

Merged the main branch please re run the CI tests

[PeterStaar-IBM]

@adityasasidhar Seems like fail here,

  Files exceeding 1000 line limit:
    FAIL: docling/cli/main.py has 1030 lines

I think to add these very specific tikz commands to the main docling cli might be a bit overkill. I wonder if it is not better to have a dedicated docling-latex one, where we can add something more specific. I know it is nice to have, but the current cli is already very heavy.

@cau-git @dolfim-ibm feel free to pitch in

[dolfim-ibm]

@adityasasidhar Seems like fail here,

  Files exceeding 1000 line limit:
    FAIL: docling/cli/main.py has 1030 lines

I think to add these very specific tikz commands to the main docling cli might be a bit overkill. I wonder if it is not better to have a dedicated docling-latex one, where we can add something more specific. I know it is nice to have, but the current cli is already very heavy.

@cau-git @dolfim-ibm feel free to pitch in

If I get it right, we are talking about 3 arguments. We indeed don't need all options in the CLI, we could have clean examples for the latex options.
On the other hand, if we agree on exposing them in the CLI, I would prepend with latex_ or tex_. I'm pretty sure that 90% of the Docling users don't know what tikz is 😉

[adityasasidhar]

@adityasasidhar Seems like fail here,

  Files exceeding 1000 line limit:
    FAIL: docling/cli/main.py has 1030 lines

I think to add these very specific tikz commands to the main docling cli might be a bit overkill. I wonder if it is not better to have a dedicated docling-latex one, where we can add something more specific. I know it is nice to have, but the current cli is already very heavy.

@cau-git @dolfim-ibm feel free to pitch in

hey @PeterStaar-IBM @dolfim-ibm

I agree with you, certainly exceeding the 1000 line limit on the cli/main.py file adds overhead....

also true on adding very specific latex commands like, most people using docling won't know what tikz is...

specifically those are:

  1. --tikz-engine or -T:  Enables TikZ rendering with Tectonic
  2. --tikz-shell-escape: Enables shell escape during Tectonic rendering
  3. --tikz-engine-timeout: Sets the TikZ render timeout for each diagram

I think skipping them in the cli would probably be a better choice:

1. most people people are not looking for such specific niche features
2. the people who are looking out could probably just use the python API
3. Plus people who want the features in the CLI could simply benefit from a dedicated docling-latex, which could be introduced if there is any demand for it ( shouldn't be a lot of work, easy couple of commits )

I'm however good to go in any direction

[adityasasidhar]

@PeterStaar-IBM @dolfim-ibm

Just pushed the latest changes

Apologies for the delay.

The latest changes include:

1. getting rid of the latex specific flags and keeping the cli/main.py under the 1000 line limit
2. exposes the options only through the python api
3. passes all the linters and checkers

[PeterStaar-IBM]

@PeterStaar-IBM @dolfim-ibm

Just pushed the latest changes

Apologies for the delay.

The latest changes include:

1. getting rid of the latex specific flags and keeping the cli/main.py under the 1000 line limit
2. exposes the options only through the python api
3. passes all the linters and checkers

all good, let's let the CI do its thing now!

[adityasasidhar]

@PeterStaar-IBM @dolfim-ibm
Just pushed the latest changes
Apologies for the delay.
The latest changes include:

1. getting rid of the latex specific flags and keeping the cli/main.py under the 1000 line limit
2. exposes the options only through the python api
3. passes all the linters and checkers

all good, let's let the CI do its thing now!

yessss lets go

[PeterStaar-IBM]

lgtm!

[PeterStaar-IBM]

@dolfim-ibm I think this looks good to merge now