terrylica/cc-skills

pandoc-pdf-generation

PDF generation from markdown via Pandoc/XeLaTeX.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/terrylica/cc-skills --skill pandoc-pdf-generation

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Pandoc PDF Generation

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Overview

Generate professional PDF documents from Markdown using Pandoc with the XeLaTeX engine. This skill covers automatic section numbering, table of contents, bibliography management, LaTeX customization, and common troubleshooting patterns learned through production use.

When to Use This Skill

Use this skill when:

  • Converting Markdown to PDF with professional formatting requirements
  • Needing automatic section numbering and table of contents
  • Managing citations and bibliographies without manual duplication
  • Controlling table formatting and page breaks in LaTeX output
  • Building automated PDF generation workflows

Quick Start: Universal Build Script

Single Source of Truth Pattern

This skill provides production-proven assets in $(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/:

  • table-spacing-template.tex - Production-tuned LaTeX preamble (booktabs, colortbl, ToC fixes)
  • build-pdf.sh - Universal auto-detecting build script

From Any Project

bash
/usr/bin/env bash << 'DETECT_EOF'
# Create symlink once per project (git-friendly)
ln -s "$(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/build-pdf.sh" build-pdf.sh

# Auto-detect single .md file in directory (landscape default)
./build-pdf.sh

# Portrait mode
./build-pdf.sh --portrait document.md

# Monospace font for ASCII diagrams
./build-pdf.sh --monospace diagrams.md

# Explicit input/output
./build-pdf.sh input.md output.pdf
DETECT_EOF

Options:

FlagDescription
--landscapeLandscape orientation (default)
--portraitPortrait orientation
--monospaceUse DejaVu Sans Mono - ideal for ASCII diagrams
--hide-detailsHide <details> blocks from PDF
-h, --helpShow help message

Features:

  • ✅ Auto-detects input file (if single .md exists)
  • ✅ Auto-detects bibliography (references.bib) and CSL files
  • ✅ Always uses production-proven LaTeX preamble from skill
  • ✅ Pre-flight checks (pandoc, xelatex, files exist)
  • ✅ Post-build validation (file size, page count)
  • ✅ Code blocks stay on same page (no splitting across pages)
  • ✅ Lua filter to hide <details> blocks from PDF output

Landscape PDF (Quick Command)

For landscape PDFs with blue hyperlinks (no build-pdf.sh dependency):

bash
pandoc file.md -o file.pdf \
  --pdf-engine=xelatex \
  -V geometry:a4paper,landscape \
  -V geometry:margin=1in \
  -V fontsize=11pt \
  -V mainfont="DejaVu Sans" \
  -V colorlinks=true \
  -V linkcolor=blue \
  -V urlcolor=blue \
  --toc --toc-depth=2 \
  --number-sections

Use landscape for: Wide data tables, comparison matrices, technical docs with code blocks.

Manual Command (With LaTeX Preamble)

bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
pandoc document.md \
  -o document.pdf \
  --pdf-engine=xelatex \
  --toc \
  --toc-depth=3 \
  --number-sections \
  -V geometry:margin=1in \
  -V mainfont="DejaVu Sans" \
  -H "$(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/table-spacing-template.tex"
SKILL_SCRIPT_EOF

ASCII Diagrams

ASCII diagrams need consistent character alignment to survive PDF rendering: use box-drawing characters consistently and keep every row the same width.

Also important: Keep annotations OUTSIDE code blocks. Don't add inline comments like # contains: file1, file2 inside diagram code blocks - they break alignment.


Hiding Content for PDF Output

Use --hide-details to remove <details> blocks from PDF output. This is useful when:

  • Diagram source blocks: Keep source in markdown for diagram regeneration, but hide from printed PDFs
  • Technical implementation notes: Show in web/markdown view, hide from printed handouts
  • Collapsible sections: HTML <details> tags don't render as collapsible in PDF

Usage:

bash
./build-pdf.sh --hide-details document.md

Markdown pattern:

`markdown
## My Section

┌─────┐ ┌─────┐ │ Box │ ──> │ Box │ └─────┘ └─────┘

diagram source
[Box] -> [Box]

With `--hide-details`, the entire `<details>` block is stripped from PDF output while remaining visible in markdown/HTML.

---

## Verification Checklist

Before considering a PDF "done", verify:

**Pre-Generation:**

- [ ] No manual section numbering in markdown (use `--number-sections`)
- [ ] Annotations are outside code blocks, not inside

**Post-Generation:**

- [ ] Open PDF and visually inspect each page
- [ ] Verify diagrams don't break across pages
- [ ] Check section numbering is correct (no "1. 1. Title" duplication)
- [ ] Confirm bullet lists render as bullets, not inline dashes

**Pre-Print:**

- [ ] Get user approval before printing
- [ ] Confirm orientation preference (landscape/portrait)
- [ ] Confirm duplex preference (one-sided/two-sided)

---

## Printing Workflow

Always let the user review the PDF before printing.

**Open for review:**

open output.pdf


**Print one-sided (simplex):**

lpr -P "PRINTER_NAME" -o Duplex=None output.pdf


**Print two-sided (duplex):**

lpr -P "PRINTERNAME" -o Duplex=DuplexNoTumble output.pdf # Long-edge binding lpr -P "PRINTERNAME" -o Duplex=DuplexTumble output.pdf # Short-edge binding


**Find printer name:**

lpstat -p -d


**Never print without user approval** - this wastes paper if issues exist.

---

## Reference Documentation

For detailed information, see:

- [Core Development Principles](./references/core-principles.md) - **START HERE** - Universal principles learned from production failures
- [Markdown for PDF](./references/markdown-for-pdf.md) - Markdown structure patterns for clean landscape PDFs
- [YAML Front Matter Structure](./references/yaml-structure.md) - YAML metadata patterns
- [LaTeX Customization](./references/latex-parameters.md) - Preamble and table formatting
- [Bibliography & Citations](./references/bibliography-citations.md) - BibTeX and CSL styles
- [Document Patterns](./references/document-patterns.md) - Document type templates
- [Troubleshooting](./references/troubleshooting-pandoc.md) - Common issues and fixes

---

## Troubleshooting

| Issue                         | Cause                        | Solution                                          |
| ----------------------------- | ---------------------------- | ------------------------------------------------- |
| Font not found                | DejaVu Sans not installed    | `brew install font-dejavu`                        |
| xelatex not found             | MacTeX not installed         | `brew install --cask mactex`                      |
| Table breaks across pages     | Missing longtable package    | Include table-spacing-template.tex preamble       |
| Double section numbers        | Manual numbering in markdown | Remove manual numbers, use --number-sections only |
| Bullet list renders as dashes | Markdown formatting issue    | Check for proper blank lines before lists         |
| Bibliography not rendering    | Missing references.bib       | Create .bib file or remove --bibliography flag    |
| PDF file size too large       | Embedded fonts               | Use --pdf-engine-opt=-dEmbedAllFonts=false        |

## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.
같은 저장소의 Skills

더 많은 Skills

모든 Skills
terrylica
커뮤니티

academic-pdf-to-gfm

Convert academic PDF papers to GitHub-renderable GFM markdown with math equations. TRIGGERS - PDF, GitHub markdown, math

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일
terrylica
커뮤니티

adr-code-traceability

Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일
terrylica
커뮤니티

arxiv-source-first-paper-ingest

Read an arXiv paper faithfully by fetching the authors' own LaTeX source instead of OCR-ing the PDF. Extracts every display equation with its label, environment and enclosing proposition, renders each to MathML, and proves usability by compiling each formula with a real TeX engine. Use when you need a paper's formulas exactly — to replicate a method, implement a loss function or custom objective, verify a quoted number, or check a claim against what the authors actually wrote. TRIGGERS - read th

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일
terrylica
커뮤니티

azure-provision

Bootstrap Azure automation when interactive az login is blocked by a Conditional Access policy (error 530035, "Device state: Unregistered"). Mints a service principal through the Azure Portal session ONCE — using Microsoft Graph over a captured token, not DOM clicking — then provisions resource groups, Cognitive Services / AI Language / Speech resources and their keys entirely via az/REST, writing key AND endpoint together into the SCS vault. Use when az login fails but the portal works, when mo

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일