paper2blog

name

paper2blog

description

Use when transforming an academic paper, arXiv/OpenReview PDF, conference paper, technical report, poster, slide deck, repository README, or related research materials into a bilingual editorial package for an editing team. Produces two articles by default — a Chinese WeChat public-account version (`blog_zh.docx`) and an English research-blog version (`blog_en.docx`). Use for drafting, revising, or packaging article copy, figure placement, captions, image prompts, and the final `.docx` deliverables.

Bilingual Paper Editorial

Purpose

Create an editorial package for an editing team from academic paper materials. By default the package has two required deliverables, both .docx:

• <blog_outdir>/blog_zh.docx — a Chinese WeChat public-account article.
• <blog_outdir>/blog_en.docx — an English research-blog article.

Both carry strong content logic, figure-text coordination, captions, and source links. They share one evidence map and one set of extracted/cropped figures — you do the paper analysis and figure prep once, then write the article twice, once per language. When a paper2assets package exists, use it as that shared source of truth so blog, poster, slides, and video agree on the same section claims, figures, numbers, and narration scripts. Visual polish is secondary because editors may re-layout the article.

The two versions are not a mirror translation of each other. They report the same facts, figures, numbers, and claims, but each is voiced for its own audience: the _zh version in the restrained, public-account WeChat register; the _en version in a neutral Western research-blog register (see references/editorial-style.md). Write each natively in its language rather than translating sentence-by-sentence.

The default reader is technically curious but not necessarily expert in the paper's subfield. Preserve academic accuracy while making the contribution understandable and worth reading.

Work autonomously. Read the paper, make the editorial judgment calls yourself, and deliver two finished drafts — don't stop to ask the user to confirm the hook, structure, figures, captions, or titles. The only thing you never guess is a checkable hard fact (paper/code link, DOI, affiliation, acceptance status): if it isn't in the inputs, omit it rather than inventing one. Everything else, decide and move on.

Output Contract

Follow the shared paper2assets v2 layout. The paper2blog bundle top level holds only deliverable files plus manifest.json; dependencies and build artifacts live under a single assets/ container:

<blog_outdir>/
  blog_zh.docx
  blog_en.docx
  manifest.json
  assets/
    figures/
    meta/
      outline_zh.json
      outline_en.json
      reports/blog_qa_report.json
      previews/blog_qa_preview/

Pick <blog_outdir> (resolve BEFORE any file writes). The bundle directory is shared across every paper2* skill — when paper2assets, paper2blog, paper2poster, and paper2video target the same root, the blog's figures sit next to the poster's figures, the shared narration script, and any other deliverables in one self-contained package. Resolve deterministically:

1. An explicit <blog_outdir> argument from the caller wins — honor it verbatim. The defaults below only fire when no path was passed.
2. A paper2assets package already exists → reuse its folder verbatim as <blog_outdir>. The canonical detection signal is <dir>/assets/meta/paper_spec.md (the cross-skill source of truth produced by paper2assets Step 4); <dir>/manifest.json with "layout": "v2-assets" is a confirming hint when present. Writing into the same bundle means both .docx files share the existing assets/figures/, the QA report lands under assets/meta/reports/, and downstream tools reading manifest.json see the blog deliverables alongside everything else with no path swap.
3. Otherwise (a bare PDF is the only input) → default to <input_pdf_dir>/<pdf_stem>/ — the directory containing the input PDF, then a subfolder named after the PDF basename (no extension). Example: papers/8008_Ink3D_Sculpting.pdf → <blog_outdir> = papers/8008_Ink3D_Sculpting/. This matches the paper2assets default convention, so if you invoke paper2assets in Workflow step 2 below it lands in the same bundle without a later path swap.

# 1. Resolve $BLOG_OUT per the rule above
if [[ -n "$blog_outdir_arg" ]]; then
  BLOG_OUT="$blog_outdir_arg"                                  # explicit caller arg wins
elif [[ -f "$paper2assets_dir/assets/meta/paper_spec.md" ]]; then
  BLOG_OUT="$paper2assets_dir"                                 # reuse the paper2assets bundle
else
  BLOG_OUT="$(dirname "$paper_pdf")/$(basename "$paper_pdf" .pdf)"
fi

# 2. Create the assets/ scaffolding under that root
BLOG_ASSETS=$BLOG_OUT/assets
BLOG_META=$BLOG_ASSETS/meta
mkdir -p "$BLOG_ASSETS/figures" "$BLOG_META/reports" "$BLOG_META/previews"

manifest.json records root-relative paths and includes "layout": "v2-assets". Legacy final/ / intermedia/ outputs remain readable by the QA checker for old demos, but new runs must use the v2 bundle shape above.

Load References

• Read references/editorial-style.md before drafting article copy.
• Read references/output-contract.md before creating the .docx.
• Read references/image-guidelines.md before selecting, cropping, editing, or prompting images — it carries the figure crop-review procedure (scripts/crop_figure.py).
• Read references/review-checklist.md before final delivery.
• Read references/case-study-acl2026.md only when a concrete style example is useful.

Workflow

1. Gather inputs:

   • Paper PDF or source, title, authors, venue, links, code/repo links.
   • Existing paper2assets package files when available: manifest.json, assets/meta/sections.json, assets/meta/narration.json, assets/meta/figures.json, assets/meta/captions.json, assets/meta/text.txt, and assets/figures/.
   • Existing examples under the current project, especially example input/output pairs.
   • Paper figures, tables, poster assets, README summaries, and any user-provided constraints.
   • The editing team's required output format. Default to .docx.

2. Extract figures, text, and captions from the PDF:

   • If the working folder already has a shared paper2assets package, read it first:

     • manifest.json for file locations and counts.
     • assets/meta/sections.json for canonical claims, section ordering, selected figure references, and reusable evidence.
     • assets/meta/figures.json / assets/meta/captions.json / assets/figures/ for image selection and captions.
     • assets/meta/text.txt for source verification and details not captured by the sections.

   • If starting from a PDF and no shared package exists yet, initialize one into $BLOG_OUT directly (resolved per the Output Contract above) — re-using $BLOG_OUT as paper2assets' --outdir keeps every paper2* skill writing into the same bundle root, so figures/captions/spec/narration that paper2assets produces sit right next to the .docx files this skill will later write. From the repo root:

     python skills/paper2assets/scripts/build_package.py <paper.pdf> --outdir "$BLOG_OUT"
     

     After paper_spec.md or an equivalent section spec exists, sync it:

     python skills/paper2assets/scripts/build_package.py <paper.pdf> \
       --outdir "$BLOG_OUT" \
       --skip-extract \
       --paper-spec "/assets/meta/paper_spec.md"
     

Default Article Shape

Use this as the starting structure for each language version unless the user's example suggests otherwise. Both versions share this shape and the same figures; only the language and voice differ.

1. Title and subtitle.
2. Two to three lead paragraphs:
   • what people usually think or do,
   • why the paper's question matters now,
   • the paper's main idea.
3. First overview figure and caption.
4. Source links: paper and code when available.
5. Background/problem section.
6. Method or contribution section, often split into named components.
7. Figure-led evidence sections.
8. Compact result table only if it improves scanability.
9. Summary section with practical significance and limitations.

Quality Bar

A good output should feel like an editor can send it into the production pipeline after light copy edits. Both the _zh and _en versions should be understandable, technically faithful, and visually navigable even before professional layout — and they must agree on every number, claim, and figure.

Never let formatting polish compensate for weak content. The paragraph logic, figure captions, and claim accuracy matter most.

Tools

scripts/
├── extract_pdf.py        ← CLI: paper.pdf → text.txt + figures/ + figures.json + captions.json + metadata.json
├── crop_figure.py        ← CLI: clean a selected figure PNG (inspect / decaption / autotrim / box)
├── build_wechat_docx.py  ← CLI: JSON outline → editor-friendly .docx
└── check_blog_package.py ← CLI: hard QA gate for bilingual DOCX deliverables

• extract_pdf.py is caption-anchored: it finds each figure by its caption, glues multi-panel sub-figures together, and clamps caption text off the bottom of the crop. Run it once per paper PDF (Workflow step 2).
• crop_figure.py is the corrective tool for the crop-review step (Workflow step 6). It always backs up to <file>.png.bak before writing and keeps figures.json dimensions in sync. Full procedure and command reference live in references/image-guidelines.md.
• build_wechat_docx.py assembles one .docx from a JSON outline (paragraphs, headings, embedded figures, captions, tables). Run it once per language with --lang — a _zh outline → $BLOG_FINAL/blog_zh.docx --lang zh (font: 微软雅黑 for Chinese, Arial for Latin) and an _en outline → $BLOG_FINAL/blog_en.docx --lang en (font: Arial for Latin text), both embedding the same figures. The article logic must be planned by the agent; the script is only an assembly aid.
• check_blog_package.py validates the final bilingual package and rendered layout previews. Run it with --strict before delivery and iterate until it passes.
• Python package dependencies are listed in requirements.txt; extract_pdf.py also needs the Poppler pdftotext executable on PATH.