vt-c-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: core-standards
Category: Documentation Pipeline
Command: /vt-c-document-converter-branded

Document Converter with VisiTrans Branding¶

Overview¶

This skill converts markdown files to professional PDF and Word documents using Pandoc with VisiTrans Corporate Design templates. It ensures proper image embedding, brand-compliant styling, and validates output quality.

Prerequisites¶

Required Software¶

# Pandoc (3.6.4 or higher)
pandoc --version

# XeLaTeX (for PDF generation)
xelatex --version

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

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

Quick Start¶

Convert to PDF¶

python scripts/convert_to_pdf.py \
  --input docs/markdown_mermaid/architecture.md \
  --output docs/pdf/architecture.pdf \
  --product visitrans

Convert to Word¶

python scripts/convert_to_word.py \
  --input docs/markdown_mermaid/architecture.md \
  --output docs/word/architecture.docx \
  --product visimatch

Batch Convert Directory¶

python scripts/batch_convert.py \
  --input-dir docs/markdown_mermaid/ \
  --pdf-dir docs/pdf/ \
  --word-dir docs/word/ \
  --product visifair

VisiTrans Branded Templates¶

Available Templates¶

templates/
├── visitrans-pdf.latex        # General VisiTrans PDF
├── visimatch-pdf.latex        # VisiMatch-specific PDF
├── visifair-pdf.latex         # VisiFair-specific PDF
├── visiarea-pdf.latex         # VisiArea-specific PDF
├── visitrans-word.docx        # General VisiTrans Word
├── visimatch-word.docx        # VisiMatch Word template
├── visifair-word.docx         # VisiFair Word template
└── visiarea-word.docx         # VisiArea Word template

Template Features¶

PDF Templates: - VisiTrans logo in header - Brand colors (Orange #FC9E00, Black #000000) - Frutiger font family (with Arial fallback) - Professional margins (1 inch) - Table of contents - Syntax highlighting for code blocks - Page numbers in footer

Word Templates: - Product logo in header - Corporate design styles - Proper heading hierarchy - Image placeholders - Footer with page numbers

Conversion Workflow¶

PDF Generation Process¶

# CRITICAL: Must run pandoc from markdown directory
cd docs/markdown_mermaid/

pandoc architecture.md \
  -o ../pdf/architecture.pdf \
  --template ~/.claude/skills/vt-c-document-converter-branded/templates/visitrans-pdf.latex \
  --pdf-engine=xelatex \
  --toc \
  --number-sections \
  --highlight-style=tango \
  --variable=geometry:margin=1in \
  --variable=logo:BRAND_ASSETS_ROOT/logos/VisiTrans.jpg

Why directory matters: - Pandoc resolves image paths relative to working directory - ![](images/diagram.png) must resolve correctly - Running from wrong directory = missing images

Word Generation Process¶

cd docs/markdown_mermaid/

pandoc architecture.md \
  -o ../word/architecture.docx \
  --reference-doc ~/.claude/skills/vt-c-document-converter-branded/templates/visitrans-word.docx \
  --toc

Image Embedding Validation¶

Critical Validation Steps¶

After conversion, MUST validate images are embedded:

For PDF:

# Check embedded images
pdfimages -list docs/pdf/architecture.pdf

# Should show:
# page   num  type   width height color comp bpc  enc interp  object ID
#--------------------------------------------------------------------
#    1     0 image     800  1150  rgb     3   8  jpeg   no      15  0
#    2     1 image     800   600  rgb     3   8  jpeg   no      23  0

For Word:

# Check embedded media
unzip -l docs/word/architecture.docx | grep media

# Should show:
# word/media/image1.png
# word/media/image2.png

File Size Validation¶

Expected file sizes: - PDF with images: >100KB (typically 200-500KB) - Word with images: >80KB (typically 150-300KB) - Files under threshold = missing images

python scripts/validate_output.py \
  --pdf docs/pdf/ \
  --word docs/word/ \
  --min-pdf-size 100000 \
  --min-word-size 80000

Product-Specific Branding¶

Logo Selection¶

PRODUCT_LOGOS = {
    'visitrans': 'VisiTrans.jpg',
    'visimatch': 'VisiMatch.jpg',
    'visifair': 'VisiFair.jpg',
    'visiarea': 'VisiArea.jpg'
}

Logo automatically selected based on --product parameter.

Color Schemes¶

From visitrans_cd skill: - Primary Orange: #FC9E00 - Primary Black: #000000 - Accent colors: Product-specific (see visitrans_cd)

Typography¶

PDF (LaTeX):

\setmainfont{Frutiger}[
  Extension = .otf,
  UprightFont = *-57Condensed,
  BoldFont = *-67BoldCondensed,
  ItalicFont = *-47LightCondensed
]
\setsansfont{Frutiger}
\setmonofont{Courier New}

Word: - Headings: Frutiger 67 Bold Condensed - Body: Frutiger 57 Condensed - Fallback: Arial (if Frutiger unavailable)

Quality Gates¶

Validation Checklist¶

validation_checks = {
    'file_created': output_file.exists(),
    'file_size_ok': output_file.stat().st_size > min_threshold,
    'images_embedded': check_images_embedded(output_file),
    'toc_present': check_table_of_contents(output_file),
    'logo_present': check_logo_in_header(output_file),
    'page_numbers': check_page_numbers(output_file)
}

Run after conversion:

python scripts/validate_output.py --file docs/pdf/architecture.pdf --strict

Error Handling¶

Common Errors¶

Error 1: Images Not Embedded

Symptom:

[WARNING] Could not fetch resource images/diagram.png

Diagnosis:

# Check current directory when running pandoc
pwd  # Must be docs/markdown_mermaid/

# Check image exists relative to pwd
ls -la images/diagram.png

Fix:

# Always cd to markdown directory first
cd docs/markdown_mermaid/
pandoc file.md -o ../pdf/file.pdf

Error 2: Missing Fonts

Symptom:

! fontspec error: "font-not-found"
! The font "Frutiger" cannot be found.

Fix:

# Install fonts or use fallback
# Update template to use Arial fallback
\setmainfont{Arial}

Error 3: XeLaTeX Not Found

Symptom:

pdflatex not found. Please select a different --pdf-engine

Fix:

# Install XeLaTeX
brew install --cask mactex  # macOS
sudo apt-get install texlive-xelatex  # Linux

Error 4: Small Output Files

Symptom:

PDF file is only 15KB (images missing)

Diagnosis:

# Check if images embedded
pdfimages -list output.pdf

# If empty, images not embedded - check paths

Integration Points¶

Works With¶

markdown-diagram-processor: Receives markdown with image references
visitrans_cd: Uses brand guidelines and logos
docs-pipeline-orchestrator: Final step in pipeline

Input Requirements¶

Markdown files with ![](images/*.png){width=X%} references
Images must exist in correct relative location
UTF-8 encoding required

Output Format¶

PDF: XeLaTeX-generated, embedded fonts and images
Word: .docx with reference template styles

Advanced Features¶

Custom Metadata¶

python scripts/convert_to_pdf.py \
  --input document.md \
  --output document.pdf \
  --title "VisiMatch Architecture Guide" \
  --author "VisiTrans Engineering" \
  --date "2025-10-23"

Table of Contents Customization¶

# PDF with custom TOC depth
python scripts/convert_to_pdf.py \
  --input doc.md \
  --output doc.pdf \
  --toc-depth 3

Page Layout¶

# Custom margins
python scripts/convert_to_pdf.py \
  --input doc.md \
  --output doc.pdf \
  --margin-top 1.5in \
  --margin-bottom 1in

Batch Processing¶

Process Entire Directory¶

python scripts/batch_convert.py \
  --input-dir docs/markdown_mermaid/ \
  --pdf-dir docs/pdf/ \
  --word-dir docs/word/ \
  --product visitrans \
  --parallel 4  # Convert 4 files simultaneously

Selective Processing¶

# Only convert files matching pattern
python scripts/batch_convert.py \
  --input-dir docs/markdown_mermaid/ \
  --pdf-dir docs/pdf/ \
  --pattern "*guide*.md"

Best Practices¶

✅ Do¶

Always run pandoc from markdown directory
Validate output after conversion
Use product-specific templates
Check file sizes to ensure images embedded
Test fonts before production use

❌ Don't¶

Run pandoc from random directories
Skip image embedding validation
Use absolute image paths
Forget to install fonts
Mix product templates (use correct logo/colors)

File Structure¶

~/.claude/skills/vt-c-document-converter-branded/
├── SKILL.md (this file)
├── scripts/
│   ├── convert_to_pdf.py           # Single PDF conversion
│   ├── convert_to_word.py          # Single Word conversion
│   ├── batch_convert.py            # Batch processing
│   ├── validate_output.py          # Quality validation
│   └── check_images.py             # Image embedding check
└── templates/
    ├── visitrans-pdf.latex
    ├── visimatch-pdf.latex
    ├── visifair-pdf.latex
    ├── visiarea-pdf.latex
    ├── visitrans-word.docx
    ├── visimatch-word.docx
    ├── visifair-word.docx
    └── visiarea-word.docx

Version History¶

v1.0 (2025-10-23): Initial release
VisiTrans branded templates
Image embedding validation
Quality gates
Compatible with Pandoc 3.6.4+

References¶

Pandoc: https://pandoc.org/
XeLaTeX: https://www.latex-project.org/
VisiTrans CD: See visitrans_cd skill
Font specifications: Frutiger family, Arial fallback