Back to Details

brain-pdf

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

brain-pdf — Render a Brain Page to Publication-Quality PDF

brain-pdf — 将Brain页面渲染为出版级PDF

Convention: see conventions/quality.md for output rules. The PDF is a rendering — never the primary artifact. If a PDF exists, the source brain page exists behind it.
约定： 请查看conventions/quality.md了解输出规则。PDF仅为渲染产物——绝非主要工件。若存在PDF，其背后必然存在对应的brain页面源文件。

The rule

规则

The brain page is ALWAYS the source of truth. The PDF is a rendering of it, never a standalone artifact. If a PDF exists somewhere, the brain page must exist behind it.
brain页面永远是权威来源。PDF只是它的渲染产物，绝非独立工件。任何地方存在的PDF，背后都必须有对应的brain页面。

What this does

功能说明

Renders a brain page (markdown with frontmatter) into a publication-quality PDF using the gstack 
make-pdf
binary. Output is suitable for:
  • Sharing a personalized book mirror via email or Telegram
  • Delivering a strategic-reading playbook as a clean read
  • Producing a briefing or report with running headers and page numbers
  • Archiving a long-form essay in a portable format
使用gstack的
make-pdf
二进制文件，将带有前置元数据的markdown格式brain页面渲染为出版级PDF。输出适用于：
  • 通过邮件或Telegram分享个性化书籍镜像
  • 提供排版整洁的战略阅读手册
  • 生成带有页眉和页码的简报或报告
  • 以便携格式存档长篇文章

Prerequisite: gstack make-pdf

前置条件：gstack make-pdf

This skill depends on the gstack 
make-pdf
binary at:
$HOME/.claude/skills/gstack/make-pdf/dist/pdf
The user must have gstack co-installed. If absent, the skill cannot run. A future v0.26+ may bundle a fallback PDF renderer; for v0.25.1 gstack is a soft prereq.
Verify it exists before invoking:
bash
P="$HOME/.claude/skills/gstack/make-pdf/dist/pdf"
[ -x "$P" ] || { echo "make-pdf not installed; install gstack" >&2; exit 1; }
本技能依赖位于以下路径的gstack 
make-pdf
二进制文件：
$HOME/.claude/skills/gstack/make-pdf/dist/pdf
用户必须已安装gstack。若未安装，本技能无法运行。未来v0.26+版本可能会集成备用PDF渲染器；但在v0.25.1版本中，gstack是软依赖项。
调用前请验证其是否存在：
bash
P="$HOME/.claude/skills/gstack/make-pdf/dist/pdf"
[ -x "$P" ] || { echo "make-pdf not installed; install gstack" >&2; exit 1; }

Workflow

工作流程

1. RESOLVE  → Confirm the brain page exists (gbrain get <slug>).
2. STRIP    → Remove YAML frontmatter — the renderer would otherwise
              dump it as a full page of raw metadata text.
3. RENDER   → Invoke make-pdf with sane defaults (no --cover, no --toc).
4. DELIVER  → Hand the PDF to the requester via the agent's preferred
              channel (do not use raw `MEDIA:` tags on Telegram —
              they fail silently).
1. 确认 → 确认brain页面存在（执行gbrain get <slug>）。
2. 移除 → 删除YAML前置元数据——否则渲染器会将其作为整页原始元数据文本输出。
3. 渲染 → 使用合理默认值调用make-pdf（不添加--cover、--toc参数）。
4. 交付 → 通过Agent首选渠道将PDF交付给请求者（在Telegram上不要使用原始`MEDIA:`标签——它们会静默失败）。

Invocation

调用方式

bash
SLUG="path/to/page"
P="$HOME/.claude/skills/gstack/make-pdf/dist/pdf"
bash
SLUG="path/to/page"
P="$HOME/.claude/skills/gstack/make-pdf/dist/pdf"

1. Confirm the page exists.

1. 确认页面存在。

gbrain get "$SLUG" > /dev/null || { echo "Page $SLUG not found" >&2; exit 1; }
gbrain get "$SLUG" > /dev/null || { echo "Page $SLUG not found" >&2; exit 1; }

2. Get the raw markdown. Two paths: read from the brain repo (if user

2. 获取原始markdown内容。有两种方式：从本地同步的brain仓库读取，或通过API向gbrain请求正文。

syncs locally) OR ask gbrain for the body via the API.

—
BRAIN_DIR=$(gbrain config get sync.repo_path 2>/dev/null || echo) if [ -n "$BRAIN_DIR" ] && [ -f "$BRAIN_DIR/$SLUG.md" ]; then RAW="$BRAIN_DIR/$SLUG.md" else RAW=$(mktemp /tmp/brain-page-XXXXXX.md) gbrain get "$SLUG" --raw > "$RAW" # whatever flag exposes raw body fi
BRAIN_DIR=$(gbrain config get sync.repo_path 2>/dev/null || echo) if [ -n "$BRAIN_DIR" ] && [ -f "$BRAIN_DIR/$SLUG.md" ]; then RAW="$BRAIN_DIR/$SLUG.md" else RAW=$(mktemp /tmp/brain-page-XXXXXX.md) gbrain get "$SLUG" --raw > "$RAW" # 用于获取原始正文的参数 fi

3. Strip YAML frontmatter — sed: skip the opening '---' through the

3. 移除YAML前置元数据——使用sed命令：跳过开头的'---'到结尾的'---'（第1行到第N行），保留之后的所有内容。

closing '---' (lines 1..N), then keep everything after.

—
CLEAN=$(mktemp /tmp/brain-page-clean-XXXXXX.md) sed '1{/^---$/!q}; /^---$/,/^---$/d' "$RAW" > "$CLEAN"
CLEAN=$(mktemp /tmp/brain-page-clean-XXXXXX.md) sed '1{/^---$/!q}; /^---$/,/^---$/d' "$RAW" > "$CLEAN"

4. Render. NO --cover, NO --toc by default — they look corporate

4. 渲染。默认不添加--cover和--toc参数——这些参数会让PDF显得过于正式且浪费空间。仅在明确请求时添加。

and waste space. Add them only if explicitly requested.

—
OUT="/tmp/$(basename "$SLUG").pdf" CONTAINER=1 "$P" generate "$CLEAN" "$OUT"
echo "Rendered: $OUT"

`CONTAINER=1` is mandatory in containerized environments — it tells
Playwright to skip Chromium sandboxing. Harmless on bare-metal.
OUT="/tmp/$(basename "$SLUG").pdf" CONTAINER=1 "$P" generate "$CLEAN" "$OUT"
echo "Rendered: $OUT"

`CONTAINER=1`在容器化环境中是必填项——它会告诉Playwright跳过Chromium沙箱。在裸机环境中使用无影响。

Common patterns

常见用法示例

bash
undefined
bash
undefined

Default — clean PDF, no cover, no TOC

默认——简洁PDF，无封面、无目录

brain-pdf <slug>
brain-pdf <slug>

Draft watermark for in-progress work

为未完成的内容添加草稿水印

CONTAINER=1 "$P" generate --watermark DRAFT "$CLEAN" "$OUT"
CONTAINER=1 "$P" generate --watermark DRAFT "$CLEAN" "$OUT"

Optional cover + TOC if the user explicitly asks

若用户明确要求，可添加可选封面和目录

CONTAINER=1 "$P" generate --cover --toc "$CLEAN" "$OUT"
CONTAINER=1 "$P" generate --cover --toc "$CLEAN" "$OUT"

Custom title + author override (otherwise pulled from frontmatter)

自定义标题和作者（默认从前置元数据中提取）

CONTAINER=1 "$P" generate --title "Custom Title" --author "Custom Author" "$CLEAN" "$OUT"
undefined
CONTAINER=1 "$P" generate --title "Custom Title" --author "Custom Author" "$CLEAN" "$OUT"
undefined

Defaults: NO cover, NO TOC

默认设置：无封面、无目录

These flags are off by default because they look corporate and waste space on most personal-knowledge content. Only add them when the user explicitly asks for "formal" output (e.g., something they're sending to a board or printing as a deliverable).
这些参数默认关闭，因为它们会让大多数个人知识内容显得过于正式且浪费空间。仅当用户明确要求“正式”输出时（例如要发送给董事会或打印交付的文件）才添加。

Font requirements

字体要求

The renderer needs:
  • fonts-liberation
    (Helvetica/Arial substitute)
  • fonts-noto-cjk
    (Chinese/Japanese/Korean characters)
  • Minimum body font size: 10pt (page chrome 9pt)
  • Body text: 11pt
If running in an environment without these fonts, install them via the host's package manager (
apt install fonts-liberation fonts-noto-cjk
on Debian/Ubuntu containers).
渲染器需要以下字体：
  • fonts-liberation
    （Helvetica/Arial替代字体）
  • fonts-noto-cjk
    （中日韩字符字体）
  • 正文字体最小尺寸：10pt（页面装饰元素9pt）
  • 默认正文字体：11pt
若运行环境中缺少这些字体，请通过主机的包管理器安装（在Debian/Ubuntu容器中执行
apt install fonts-liberation fonts-noto-cjk
）。

Delivery

交付方式

After rendering, deliver via the agent's preferred channel:
  • Telegram: use the 
    message
    tool with 
    filePath="/tmp/<slug>.pdf"
    attachment. NEVER use raw 
    MEDIA:
    tags — they fail silently.
  • Email: attach via the host's email tool.
  • Direct file response: print the PDF path; the user can pull it manually.
Always include the brain page link in the delivery message so the user can also see it on GitHub / locally. The PDF is a rendering; the source is the artifact.
渲染完成后，通过Agent首选渠道交付：
  • Telegram： 使用
    message
    工具，附带
    filePath="/tmp/<slug>.pdf"
    附件。绝不要使用原始
    MEDIA:
    标签——它们会静默失败。
  • 邮件： 通过主机的邮件工具添加附件。
  • 直接文件响应： 打印PDF路径，用户可手动获取。
交付消息中务必包含brain页面链接，以便用户也能在GitHub或本地查看源文件。PDF仅为渲染产物，源文件才是权威工件。

Anti-Patterns

反模式

  • ❌ Generating a PDF without first confirming the brain page exists. No source = no PDF.
  • ❌ Skipping the frontmatter strip. The renderer dumps frontmatter as raw text on the first page; ugly.
  • ❌ Skipping emoji sanitization. Emoji that don't map to the rendering font show up as 
    □
    boxes.
  • ❌ Adding 
    --cover
    or 
    --toc
    by default. Off unless asked.
  • ❌ Using raw 
    MEDIA:
    tags for Telegram delivery. Use the 
    message
    tool with 
    filePath
    .
  • ❌ 未确认brain页面存在就生成PDF。无来源则无PDF。
  • ❌ 跳过移除前置元数据的步骤。渲染器会将前置元数据作为原始文本输出在第一页，非常不美观。
  • ❌ 跳过表情符号清理。无法映射到渲染字体的表情符号会显示为
    □
    方框。
  • ❌ 默认添加
    --cover
    或
    --toc
    参数。除非明确要求，否则保持关闭。
  • ❌ 在Telegram交付时使用原始
    MEDIA:
    标签。应使用带有
    filePath
    的
    message
    工具。

Related skills

相关技能

  • skills/book-mirror/SKILL.md
    — produces a brain page that's a natural input to brain-pdf (chapter-by-chapter personalized analysis).
  • skills/strategic-reading/SKILL.md
    — same shape, problem-lens variant.
  • skills/publish/SKILL.md
    — share brain pages as password-protected HTML (different rendering target).
  • skills/book-mirror/SKILL.md
    — 生成可作为brain-pdf输入的brain页面（逐章个性化分析）。
  • skills/strategic-reading/SKILL.md
    — 类似格式，聚焦问题视角的变体。
  • skills/publish/SKILL.md
    — 将brain页面分享为受密码保护的HTML（不同的渲染目标）。

Contract

契约

This skill guarantees:
  • Routing matches the canonical triggers in the frontmatter.
  • Output written under the directories listed in 
    writes_to:
    (when applicable).
  • Conventions referenced (
    quality.md
    , 
    brain-first.md
    , 
    _brain-filing-rules.md
    ) are followed.
  • Privacy contract preserved: no real names, no fork-specific filesystem path literals, no upstream-fork references.
The full behavior contract is documented in the body sections above; this section exists for the conformance test.
本技能保证：
  • 路由与前置元数据中的标准触发规则匹配。
  • 输出写入
    writes_to:
    列出的目录（如适用）。
  • 遵循引用的约定（
    quality.md
    、
    brain-first.md
    、
    _brain-filing-rules.md
    ）。
  • 遵守隐私契约：不包含真实姓名、不包含特定分支的文件系统路径字面量、不包含上游分支引用。
完整的行为契约记录在上述正文章节中；本节用于一致性测试。

Output Format

输出格式

The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (
test/skills-conformance.test.ts
).
技能的输出格式记录在上述正文章节中（请查看“输出”、“Brain页面格式”或等效部分）。此处的字面章节标题用于一致性测试（
test/skills-conformance.test.ts
）。