jp-pdf

jp-pdf — Japanese Markdown → colorized offline PDF

Converts Markdown into acolorized PDF with beautifully typeset Japanese. The generation path is pandoc → xelatex only, and it does not use Chrome or external services (zero external communication).

<SKILL_DIR> is to be read as the actual path of the directory containing this SKILL.md .

When to use

Requests such as "turn this Markdown into a PDF" or "PDF化して this research proposal."
When you want to output a Japanese document (design document, proposal, report) in a format suitable for distribution.

Prerequisite tools (all local/offline)

Tool	Purpose	Installation example
pandoc	Markdown→LaTeX→PDF	`brew install pandoc`
xelatex (TeX Live)	Japanese-capable PDF engine	MacTeX / TeX Live
rsvg-convert (librsvg)	SVG figure → vector PDF	`brew install librsvg`
IPAexGothic font	Japanese body text	`~/Library/Fonts/ipaexg.ttf`
ghostscript (gs)	Preview (PNG)	`brew install ghostscript`

If anything is missing, the build script names it and stops.

Basic procedure

Prepare the input Markdown (an existing file is fine). If there are no figures, this one step completes the process.

Run the build:

python3 "<SKILL_DIR>/scripts/build_pdf.py" \
  --input path/to/doc.md \
  --output path/to/doc.pdf \
  --title "ドキュメント表題" \
  --running-title "ヘッダに出す短い題" --doc-tag "研究計画書" \
  --toc --preview

--preview If you add doc_p1.png , the first page is output togs . Use to convert any page to PNG for visual confirmation:

gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=png16m -r120 \
   -dFirstPage=1 -dLastPage=3 -sOutputFile=out-%02d.png doc.pdf

When adding figures (ASCII figures → SVG)

ASCII figures in the body can be replaced with easy-to-read SVG figures. In the manuscript .md , the approach is to leave the ASCII as is and replace it with an image only at PDF build time (the manuscript remains readable in an editor).

<SKILL_DIR>/scripts/svglib.py import and write a drawing script. The template is <SKILL_DIR>/../../examples/gen_diagrams.py(import and use svglib). Assemble rounded boxes box(), arrows arrow(), labels label(), and chips chip() .
Place the generated SVG in assets/ .

Map "which ASCII fence is replaced by which SVG" using figures.json (the template is examples/figures.example.json）：

[
  {"sig": "フェンス内に必ず含まれる一意な文字列", "svg": "pipeline.svg", "caption": "図：…"}
]

Pass --assets assets --figures figures.json to the build. The corresponding fence is ![caption](assets/xxx.pdf) replaced and the SVG is automatically converted to vector PDF.

Design highlights (pitfalls encountered in this procedure)

Fully offline: The Chrome/HTML path is not used. Because pandoc→xelatex completes locally, no telemetry or external resource fetching occurs.
Fonts: Since IPAexGothic has a single weight, bold is simulated with AutoFakeBold (the build script applies this by default).
Color scheme：<SKILL_DIR>/assets/style.tex is handled by. Teal-based, colored headings + underline rules, tcolorbox callout quotes (> blocks),rowcolors striped tables, fancyhdr headers/footers, and rules above and below the title.
SVG frame overflow：textLength(stretch specification) is in rsvg-convert's PDF output ignored(it works in PNG, so it's easy to overlook).svglib insteadshrinks the font size to actual size andfits it in (fitfs). When drawing, using this box()/label() is safe.
Glyph substitution: ✕・≈ not present in IPAexGothic is replaced with ×・≒ only at build time (default; the manuscript is unchanged). If other missing-glyph warnings appear, add --glyph-subs "字=代替,…" .
Preventing label/box overlap: Do not place freely positioned label() at coordinates that intersect the box's vertical range (y to y+h) and horizontal range. Names attached to arrows should be only short wordsabovethe arrow, and descriptions should be placed by securing a dedicated bandbelow the box row(vertical zone). Keep zones at least 16px apart. For long labels, always specify maxw to shrink them.
Verification (required): Before building, convert the SVG itself to PNG with rsvg-convert -o check.png and visually inspect it; if text overlaps frames or arrows, fix it before incorporating. After building, also convert pages to PNG with gs and visually check whether the figures fit within the frames and symbols appear. Do not consider it complete while overlaps remain.

Main options of build_pdf.py

--input --output(required) /--assets DIR／--figures JSON／--title／ --running-title／--doc-tag／--style style.tex(bundled by default) /--font(default IPAexGothic) / --fontsize(default 10pt) /--margin(default 16mm) /--img-width(default 88%) / --toc／--preview／--glyph-subs "a=b,c=d"。

Demo (bundled samples)

examples/ contains a full set of general-purpose samples. You can try a full run with the following.

python3 "<SKILL_DIR>/../../examples/gen_diagrams.py" "<SKILL_DIR>/../../examples/assets"
python3 "<SKILL_DIR>/scripts/build_pdf.py" \
  --input "<SKILL_DIR>/../../examples/sample.md" \
  --output sample.pdf \
  --assets "<SKILL_DIR>/../../examples/assets" \
  --figures "<SKILL_DIR>/../../examples/figures.example.json" \
  --title "月次レポート自動化の検討メモ" --toc --preview