paper-webpage-builder

name	paper-webpage-builder
description	Build a polished single-page academic project webpage from a paper directory or paper source, including content extraction, figure selection/conversion, module planning, visual design, tables, assets, and validation. Use when asked to create or update webpages for papers, benchmarks, arXiv-style projects, OpenRaiser project pages, or paths containing paper.tex/PDF/images/assets.

Paper Webpage Builder

Use this skill to turn a paper project folder into a web-ready project page. It is optimized for repos with paper.tex, *.pdf, images/, and assets/, but also works from a PDF plus image assets.

Core Rule

Do not mechanically clone an existing webpage. Use prior pages only as references for interaction patterns and content completeness. The final design must follow the target paper's topic, figures, color palette, density, and audience.

Two failure modes to actively avoid:

• Do not reuse a background system from another paper page by default. Grids, coordinate paper, dark sections, gradients, or canvas textures are allowed only when they are supported by the target paper's own figures, domain, or visual language.
• Do not default to a split hero with oversized title text on the left and a paper figure/card on the right. This generic composition is allowed only when the paper has a product-like teaser image that clearly belongs in the first viewport and the whole composition is justified by the paper's evidence hierarchy.
• Do not summarize away central evidence. If the paper's main claim depends on a main experiment table, benchmark comparison table, dataset statistics table, or ablation table, the webpage must include that table in full or provide a clearly equivalent full presentation.
• Do not show partial or horizontally scrolling tables. Table rows, headers, and cell text must be statically visible; they must not be clipped by smaller white/card containers, fixed-height panels, masks, fades, overflow:hidden, or overflow-x:auto/scroll. Wide tables should use grouped columns, multiple full sub-tables, readable density reduction, or a larger responsive container while preserving values.

Workflow

1. Inspect inputs before editing.

   • Locate paper source, PDF, figures, logos, existing template.html, and target index.html.
   • Run scripts/scan_paper.py <paper.tex> when a TeX source exists. Multi-file projects are followed via \input/\include automatically. This gives the skeleton (title, authors, captions, table/figure metadata, links) — not the argument.
   • Run scripts/extract_sections.py <paper.tex> to read the body prose of every section. The skeleton is not enough: designing from scan_paper.py alone is the main cause of shallow pages with abstract-paraphrased copy and invented headings. Read this output in full (use --full for truncated sections).
   • Run scripts/scan_pdf.py <paper.pdf> when only a PDF is available; it produces the same shape of inventory (title, authors, abstract, sections, figure/table captions, links).
   • Run scripts/extract_tables.py <paper.tex> to dump every table (caption, label, header rows, data rows) as JSON. Use this to seed the table ledger instead of eyeballing the .tex.
   • Build a table ledger before designing: caption, label, section, whether it is main evidence, and whether it must appear fully on the page.
   • Identify important tables as well as figures; main results, benchmark comparisons, dataset statistics, and ablations usually belong on the page.

2. Read deeply and build a Paper Brief.

   • This step is mandatory and comes before any visual or copy decision. Follow references/paper_reading.md.
   • From the section prose, write an explicit eight-part Brief in working notes: thesis (as a claim), problem, core idea/name, how it works (2-4 stages), evidence map (what each central table/figure proves), headline numbers (each with its comparison), honest limits, and audience/tone.
   • Do not invent any part. If a part cannot be filled from the extracted text, read more rather than guessing.
   • All later page copy (hero subtitle, TL;DR, section headings, result framing) must derive from this Brief, not from the abstract directly. Section headings must be claims, not academic labels; never use "the paper argues/proposes/presents" phrasing; never show a number without its comparison or a central table without a one-line "why this matters" framing.

3. Build a content map.

   • Extract title, authors, affiliations, abstract claim, contributions, links, dataset stats, method description, main results, case studies, citation.
   • Map every central table to a page module. If a central table is too large, plan grouped columns, multiple full sub-tables, or a larger static table module rather than dropping rows or adding horizontal scroll.

Publishing Workflow

When asked to upload a generated webpage to GitHub Pages or a project repo:

• Confirm the exact target repository and branch mapping in the working notes before pushing.
• Default to gh-pages for the webpage branch unless the user names another branch.
• Do not push webpage assets to main unless explicitly requested.
• If the user wants an empty main, create a minimal README-only main branch and keep webpage content isolated on the page branch.
• Before every push, run git ls-remote --heads <repo> and report whether the target branches already exist.
• Never force-push or delete remote branches unless the user explicitly asks for that exact operation.
• After pushing, verify with git ls-remote --heads <repo> and report the branch names and commit hashes.

9. Use the agent workbench when the user wants an interactive UI, ongoing progress, preview, or region-level repair.
   • Start the local workbench with python3 scripts/webpage_workbench.py --port 8765.
   • The workbench is a chat interface over the real skill workflow. The user should be able to say "build a webpage for this paper" and the backend agent should perform this workflow, not generate a generic scaffold.
   • The backend runs an agent command in the background (default: local codex exec when available; override with --agent-command for Claude or another runner), tracks progress, logs output, and mounts the generated index.html in the preview pane.
   • Use the iframe overlay to mark a visual defect. The workbench saves annotation.json, context.html, and repair_prompt.md under <paper-project>/.paper-webpage-builder/annotations/<timestamp>/, then includes that context in the next chat turn when requested.
   • Treat saved DOM selectors, bounding boxes, computed styles, and user instruction as the repair scope. Make the smallest local HTML/CSS/JS change that resolves the selected defect, then rerun the checks in step 8.
   • Read references/visual_workbench.md for the exact closed-loop contract.

Output Expectations

In the final response, include:

• The generated/updated index.html path.
• The major modules included.
• The important figures/tables included.
• The page metadata you set (lang, canonical URL, OG image; DOI/arXiv if known) — these populate the metadata block of the output schema.
• Suggested project keywords or tags for discovery (required, at least one).
• The quality checks performed for links, HTML sanity, responsive layout, asset independence, visual consistency, table reconciliation, and design drift (required; use not_run with a reason rather than omitting an entry).
• Validation performed and remaining risks.

The output is validated against schemas/output.schema.json; keywords and quality_checks are required.

Reference Files

• references/paper_reading.md: deep-reading protocol and the Paper Brief that all page copy must derive from. Read this before designing.
• references/module_patterns.md: section patterns, paper-content extraction targets, and table handling.
• references/design_principles.md: visual design rules for paper webpages.
• references/visual_workbench.md: local UI loop for previewing generated pages, selecting visual defects, and handing region context to an agent.

Scripts

• scripts/scan_paper.py: summarize TeX title/authors/abstract/sections/figures/tables/links; follows \input/\include. Emits an explicit warning when the file is not UTF-8 (with the fallback encoding it used). Produces the skeleton only — not section body prose.
• scripts/extract_sections.py: print the cleaned body prose of every section (drops float/equation noise, keeps citations as [cite] and contribution lists). Read this to understand the paper's argument before designing; pair it with references/paper_reading.md.
• scripts/scan_pdf.py: PDF-only inventory in the same shape as scan_paper.py (used for kind: pdf_with_assets).
• scripts/extract_tables.py: dump every LaTeX table (caption/label/header/data rows) as JSON for the table ledger.
• scripts/extract_citation.py: produce a best-effort BibTeX draft with explicit notes for unverified fields.
• scripts/convert_figures.py (and convert_figures.sh shim): convert paper figures to web assets and emit figures.manifest.json. Handles multi-page PDFs, .eps, .svg, raster passthrough, and CJK filenames.
• scripts/render_template.py: substitute {{NAME}} placeholders in assets/single-page-template.html; --inplace refreshes only the head metadata of an existing page.
• scripts/inject_metadata.py: build SEO + Schema.org ScholarlyArticle JSON-LD; outputs render_template.py values, a copy-paste meta block, or runs the in-place head refresh in one shot.
• scripts/check_webpage_links.py: link/lint check for local assets; --full adds CSS url(...), srcset, <source>/poster, preload, og:image, #fragment targets, duplicate ids, missing alt/title, and path-traversal warnings. --check-external HEAD-requests external URLs (max 20, 5s timeout) and flags 4xx/5xx as errors, timeouts as warnings.
• scripts/check_design_drift.py: palette overlap between figures and page, plus figure-container, grid/dark/clone warnings, CSS variable name vs hue mismatch, hardcoded color orphans, grid responsive breakpoint checks, and paired-figure alignment checks against sibling .