tomevault-io Analyze to PDF
Convert a markdown file to PDF using pandoc. Designed for experiment analysis reports but works with any markdown file.
Your Task
- Check that required system tools are installed
- Locate the markdown file to convert
- Convert to PDF with pandoc
- Report the result
Dependency Check
Verify tools are available before proceeding:
Required: pandoc
which pandoc
If missing, stop and report:
pandoc is not installed. Install it with your package manager (e.g., apt install pandoc, dnf install pandoc).
Required: PDF engine (one of the following, in priority order)
which xelatex # preferred — better Unicode support
which pdflatex # fallback
If neither is found, stop and report:
No PDF engine found. pandoc needs a LaTeX installation to produce PDFs.
Install texlive (e.g., apt install texlive-xetex or dnf install texlive-xetex).
Record which engine is available for the conversion step.
Locate Markdown File
If user provides a path argument: Use that path directly.
If no argument provided:
- Check if current directory contains
experiment_summary.yaml - If yes, look for
analysis/report.md - If that file exists, use it
- Otherwise, ask the user for a path
Validate the file exists before proceeding.
Preprocess for PDF
Reports may contain HTML <details> blocks (collapsible sections) that LaTeX cannot render. Expand them before conversion:
from pathlib import Path
from tools.inspect.report_generator import expand_details_for_pdf
md_path = Path("{full_path_to_md}")
text = md_path.read_text()
expanded = expand_details_for_pdf(text)
# Write to a temp file in the same directory (so relative image paths still work)
tmp_path = md_path.with_suffix(".tmp.md")
tmp_path.write_text(expanded)
This converts <summary> text to bold labels and <pre><code> blocks to fenced code blocks. If the markdown has no <details> blocks, the text passes through unchanged.
Convert to PDF
Critical: Change to the markdown file's parent directory before running pandoc. This ensures relative image paths (e.g., ) resolve correctly.
cd {parent_directory}
pandoc {tmp_filename} -o {stem}.pdf --pdf-engine={engine} \
--from markdown-implicit_figures \
-V geometry:margin=1in
Why these flags matter:
--from markdown-implicit_figures— disables pandoc's automatic wrapping of images in LaTeX\begin{figure}float environments. Without this, LaTeX treats every image as a float and reorders them past surrounding text onto later pages. With this flag, images are inline\includegraphicscalls that appear exactly where they are in the markdown, just like text. The tradeoff is noFigure N:captions, but report images already have###headings so captions are redundant.geometry:margin=1in— maximizes page real estate for figures
Where {stem} is the original filename without the .md extension (e.g., report.md → report.pdf).
After conversion, clean up the temp file:
tmp_path.unlink()
Report Result
On success:
PDF created: {full_path_to_pdf} ({file_size})
On failure: Show the pandoc error output. Common issues:
- Missing LaTeX packages: suggest
tlmgr install {package}or a fuller texlive install - Image format not supported: suggest converting images to PNG first
- Unicode issues with pdflatex: suggest installing xelatex instead
Important Notes
- No logging file — this is a lightweight utility, not a multi-stage workflow
- Idempotent — re-running overwrites the existing PDF
- Image embedding — the
cdinto the file's directory is what makes relative image paths work. Do not skip this. - xelatex over pdflatex — prefer xelatex when available for better Unicode and font handling
Converted and distributed by TomeVault — claim your Tome and manage your conversions.