Skip to content

vt-o-document-converter-branded

Converts markdown files to professional PDF and Word documents using VisiTrans-branded Pandoc templates. Embeds images properly, applies corporate typography and layout from visitrans_cd guidelines, validates output quality (file size, image embedding). Use when creating final branded documents from markdown source files with embedded diagram images.

Plugin: vt-office
Category: Documentation Pipeline
Command: /vt-o-document-converter-branded

Document Converter with VisiTrans Branding

Overview

This skill converts a markdown file to a branded PDF using Pandoc + XeLaTeX and a VisiTrans Corporate Design LaTeX template. It also covers plain (unbranded) Word output and manual output-quality checks.

Scope note (read first). This skill ships one PDF template (templates/visimatch-pdf.latex) and no helper scripts. Earlier versions of this document described a scripts/ directory and per-product PDF/Word templates that were never committed — that documentation has been corrected to match what actually ships. See Limitations below for what is not yet implemented.

When to Use

  • You have a finished markdown file (typically with ![](images/*.png) diagram references) and need a branded PDF.
  • You are producing a VisiMatch document, or any document where the shipped template's header (Meeting Minutes) and footer (VisiMatch — Smart Logistics) labels are acceptable, or you are willing to pass a different logo.

Do not use this for per-product branded PDFs (VisiTrans / VisiFair / VisiArea) that need product-correct header/footer labels — those templates are not yet built (see Limitations).

Prerequisites

Required software

pandoc --version     # 3.6.4 or higher
xelatex --version    # from TeX Live / MacTeX

# Install if needed (macOS)
brew install pandoc
brew install --cask mactex

# Install if needed (Linux)
sudo apt-get install pandoc texlive-xetex

Brand assets

Logos live in the visitrans_cd skill and resolve via BRAND_ASSETS_ROOT (see root CLAUDE.md). When the skills are deployed, the concrete paths are:

  • Template: ~/.claude/skills/vt-o-document-converter-branded/templates/visimatch-pdf.latex
  • Logos: ~/.claude/skills/vt-b-visitrans-cd/assets/logos/*.jpg

The logo files are real JPEG images (13 of them, .jpg). XeLaTeX's \includegraphics loads JPEG directly — do not feed it WebP/PNG-behind-.jpg.

Execution

1. Convert to branded PDF

The template is parameterised by a logo variable. Pandoc resolves image paths relative to the working directory, so run it from the markdown file's directory so that ![](images/diagram.png) references resolve.

cd docs/markdown_mermaid/     # so relative image paths resolve

pandoc architecture.md \
  -o ../pdf/architecture.pdf \
  --template ~/.claude/skills/vt-o-document-converter-branded/templates/visimatch-pdf.latex \
  --pdf-engine=xelatex \
  --highlight-style=tango \
  --variable=logo:$HOME/.claude/skills/vt-b-visitrans-cd/assets/logos/VisiTrans.jpg

Pick the --variable=logo: path from the table under Logo selection.

2. Convert to Word (plain, unbranded)

No branded Word reference template ships yet (see Limitations). A plain, correctly-structured .docx is produced with default styles:

cd docs/markdown_mermaid/
pandoc architecture.md -o ../word/architecture.docx --toc

3. Logo selection

Only these base/module logos exist in visitrans_cd/assets/logos/. There is no plain VisiFair.jpg — VisiFair has module logos only.

Brand Logo file
VisiTrans VisiTrans.jpg
VisiMatch VisiMatch.jpg (+ VisiMatch_Carrier/Pricing/Terminal.jpg)
VisiArea VisiArea.jpg (+ VisiArea_Defense.jpg)
VisiFair module logos only: VisiFair_Data/Guide/Marker/Outdoor/Planner/Show.jpg

Template Features

templates/visimatch-pdf.latex:

  • Logo in header-left (via the $logo$ variable)
  • Fixed header-right label Meeting Minutes and footer-left VisiMatch — Smart Logistics (hardcoded in the template — see Limitations)
  • Brand colours: Orange #FC9E00, Anthracite #101216 (text/links); logo base stays #000000
  • Arial main/sans font, Courier New mono (Frutiger is not wired up in this template)
  • A4 geometry with corporate margins, page numbers in footer, code syntax highlighting

Note: this template has no $title$/$toc$ placeholders, so --toc and title-block metadata are not rendered by it. Use section headings in the markdown for structure.

Output Validation

Validate manually after conversion (there is no validate_output.py).

# 1. File was created and is a non-trivial size (images embedded → typically >100 KB)
ls -la docs/pdf/architecture.pdf

# 2. Images are embedded (logo + any diagrams should be listed)
pdfimages -list docs/pdf/architecture.pdf      # from poppler; brew install poppler

# 3. Word: check embedded media
unzip -l docs/word/architecture.docx | grep media

A PDF far under ~100 KB, or an empty pdfimages listing, means images did not embed — check that you ran pandoc from the markdown directory.

Edge Cases

  • Logo file is WebP behind a .jpg name → XeLaTeX aborts with Unable to load picture or PDF file. The shipped logos are real JPEG; if you add new ones, verify with file logo.jpg (must say JPEG image data), not just the extension.
  • Running pandoc from the wrong directory → [WARNING] Could not fetch resource images/diagram.png and a tiny PDF. Always cd to the markdown directory first.
  • Fonts — the template uses Arial. If Arial is unavailable, edit the template's \setmainfont to an installed font.

Integration Points

  • markdown-diagram-processor — produces the markdown with embedded image refs consumed here.
  • visitrans_cd — owns the brand colours and the logo assets referenced above.
  • docs-pipeline-orchestrator — calls this skill as the final render step.

Error Handling

Symptom Cause Fix
Unable to load picture or PDF file '...jpg' Logo is not really JPEG (WebP/PNG payload) Convert to real JPEG (sips -s format jpeg in.jpg --out in.jpg)
[WARNING] Could not fetch resource images/... Wrong working directory cd to the markdown directory before running pandoc
fontspec error: font-not-found Arial not installed Change \setmainfont in the template to an installed font
pdflatex not found Wrong engine Ensure --pdf-engine=xelatex and that XeLaTeX is installed

Anti-patterns

  • Never run pandoc from an arbitrary directory — pandoc resolves relative image paths against the working directory, so images silently fail to embed.
  • Never pass a .jpg logo without checking it is real JPEG — a WebP/PNG payload behind a .jpg name aborts the XeLaTeX run.
  • Never document scripts or templates that are not committed — the previous version did, which is the defect this skill was corrected for; keep this file in sync with the actual templates/ contents.

Limitations (not yet implemented)

Tracked as BUG-018. This skill intentionally documents only what ships:

  • No scripts/ directory. convert_to_pdf.py, convert_to_word.py, batch_convert.py, validate_output.py, check_images.py do not exist. Use the direct pandoc commands above.
  • Only one PDF template, visimatch-pdf.latex. The visitrans-, visifair-, and visiarea-pdf.latex templates were never built. The single template also hardcodes a Meeting Minutes header label and a VisiMatch footer, so it is not yet a true per-product template.
  • No branded Word templates. Word output uses Pandoc defaults (unbranded).

Building genuine per-product PDF/Word templates (parameterising the header/footer labels, adding $title$/$toc$) is deferred — see the spec-163 brand-plugin split, which relocates the logo assets and is the natural home for that work.

Success Criteria

  • pandoc … --pdf-engine=xelatex exits 0 and produces a PDF.
  • pdfimages -list shows the logo (and any diagrams) embedded as real images.
  • The header logo renders (no Unable to load picture error).

Version History

  • v1.1 (2026-07-31) — BUG-018: converted the 13 brand logos from WebP-behind-.jpg to real JPEG so XeLaTeX can load them; rewrote this document to match what actually ships (removed non-existent scripts and per-product templates, corrected logo filenames, replaced script invocations with direct pandoc commands).
  • v1.0 (2025-10-23) — Initial release.

References

  • Pandoc: https://pandoc.org/
  • XeLaTeX: https://www.latex-project.org/
  • VisiTrans CD: see the visitrans_cd skill