SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsguizang-page-skill

guizang-page-skill

Writing & research

View repository

Updated 10-31 17:36

About this skill

Guizang Page

Source identification: Guizang Page is created and maintained by 歸藏. This information is not written into the generated HTML page.

What this Skill does

Render Markdown documents assingle-file HTML pages, with a restrained, content-first design style.

Core architecture:the model makes annotation judgments, and scripts perform deterministic rendering.

Markdown 原文 ──→ annotations.json ──→ render.mjs ──→ output.html
 (全量保留)        (升格标注，数百token)   (确定性脚本)    (styled HTML)

Two styles

Style Aesthetic anchor Features
Magazine style (Magazine) Monocle × photocopy Serif headlines, off-white paper color, predominantly ink color (default Ink Classic), cross-line texture, slightly rounded corners
Swiss style (Swiss) Helvetica Forever Ultra-thin sans-serif, cool gray background, single anchor color (default Klein Blue), card language, right angles, grid dots

The color schemes of the two styles are the same theme set as the PPT and graphic card skills (6 sets for Magazine style, 4 sets for Swiss style), see references/themes.md。

Two modes

Mode Purpose Annotation volume
Faithful mode Retains the full original text, with a small amount of upgrading 10-20 annotations
Explanatory mode Retains the original text + inserts explanatory components + language filtering Depending on length, about 3–5 explanatory components per thousand characters

When to use

Suitable: document typesetting, article presentation, knowledge note visualization, PRD formatting, reading note organization, monolingual rendering of bilingual documents Not suitable: PPT presentations (use guizang-ppt-skill), social media cards (use guizang-social-card-skill), WeChat official account typesetting (this Skill has removed WeChat official account export; use wechat-formatter)

Workflow

Step 1 · Confirm requirements

Questions that need clarification:

  1. Which style? Magazine / Swiss
  2. Which mode? Faithful (retain original text) / Explanatory (add visualization)
  3. What language? If it is a bilingual document, choose the primary language (zh / en)
  4. Are there specific image requirements? By default, fetch general high-quality images from Unsplash
  5. Color scheme? It is also fine not to ask; use the default theme; when the content has a clear tone, choose from references/themes.md choose a set; if the user provides a brand color or logo primary color, use --brand

Step 2 · Analyze the document and generate annotations.json

Read the original Markdown,scan line by line, and identify the following upgrade patterns:

Upgrade judgment rules

Original pattern Upgraded to Basis for judgment
> **Term**：definition def-card Already a "term: explanation" structure
A standalone bolded judgment sentence pullquote The whole paragraph contains only one sentence, and it is an opinionated conclusion
3+ consecutive numbers big-number(Not auto-generated for now, reserved) Data is naturally suited to visual emphasis
Ordered steps 1→2→3 process Sequential relationship already exists
3+ parallel cases of the same kind gallery Parallel structure, suited to card layout
Constraint/rule list checklist Negative or constraint-based list
Core definition/principle sentence highlight Standalone bold sentence + context is a definition
Social call-to-action/ad drop Not part of the body content

Extra annotations in explanation mode

Type Purpose Source
figure Unsplash image AI selects images based on paragraph content
embed SVG infographic AI-generated diagram
aside Practice tip card Engineering suggestions distilled by AI
summary-card Quick-reference grid Full-text summary generated by AI

annotations.json format

{
  "meta": {
    "title": "文档标题",
    "author": "作者",
    "date": "2026.06.17",
    "reading_time": "约 X 分钟",
    "tags": ["标签1", "标签2"],
    "subtitle": "一句话摘要",
    "hero_image": "https://images.unsplash.com/photo-xxx?w=1400&h=600&fit=crop",
    "lang": null
  },
  "upgrades": [
    { "type": "pullquote", "line": 37, "accent": "关键词" },
    { "type": "highlight", "line": 87, "label": "核心定义" },
    { "type": "def-card", "lines": [51, 55, 59] },
    { "type": "drop", "line": 17 },
    { "type": "gallery", "lines": [155, 163, 171, 177], "items": [
      { "title": "标题", "desc": "描述" }
    ]},
    { "type": "process", "lines": [311, 313], "items": [
      { "title": "步骤名", "desc": "步骤描述" }
    ]},
    { "type": "checklist", "lines": [382, 384, 386] },
    { "type": "figure", "line": 35, "src": "https://...", "caption": "图注" },
    { "type": "embed", "line": 30, "label": "标签", "svg": "<svg>...</svg>", "caption": "说明" },
    { "type": "aside", "line": 46, "title": "提示标题", "text": "提示内容" },
    { "type": "summary-card", "line": 241, "label": "速查卡", "items": [
      { "title": "名称", "desc": "描述" }
    ]}
  ]
}

Key constraints：

  • line field is the 1-based line number in the original markdown file
  • In faithful mode, upgrades array only contains pullquote / highlight / def-card / drop / gallery / process / checklist
  • Explanation mode additionally includes figure / embed / aside / summary-card: the componentis inserted before the line line Before that line; that line's original text is output as usual and will not be replaced;line can point to a blank line (inserting between two paragraphs is most reliable)
  • The same document can have multiple process / checklist annotations, each using its own lines
  • During rendering, the terminal will list the count of each annotation type; if a line number points to a blank line or the type does not match (for example, pullquote points to something that is not a bold sentence), a warning will be given. Fix the line number according to the warning and render again
  • The magazine-style header only has a title and subtitle;hero_image is only displayed in Swiss style
  • ARTICLE / FINAL in the Swiss-style top bar come from the Markdown frontmatter's type / status(for example, type: release-note); when there is no frontmatter, default values are displayed
  • For bilingual documents, after setting meta.lang , the renderer automatically filters out paragraphs in the other language

Step 3 · Run the rendering script

node scripts/render.mjs <input.md> <annotations.json> <output.html> --style swiss|magazine [--theme <id>] [--brand "#hex"] [--embed]
  • --theme: initial color scheme, see id in references/themes.md(you can also write meta.theme）
  • --brand: the user's brand color, generates a constrained brand theme (you can also write meta.brand); the terminal will print what was adjusted, and fall back to the preset if it does not meet the standard
  • --embed: embed a subset of the fonts used by the page into the HTML. Use this when the page needs to be viewed offline, sent to people in mainland China whose networks cannot open Google Fonts, or exported to PDF / long images; on first use, first run in the skill directory npm install. If not added, fonts use online links and the file is about 120KB

The script automatically:

  1. Reads markdown + annotations
  2. Matches and promotes annotations by line
  3. Unannotated lines are rendered as default prose
  4. Inline CSS: design system (assets/gz-<风格>.css: theme, font-size roles, spacing) + style layout (assets/style-<风格>.css) + settings panel
  5. Generates a single-file HTML (by default only depends on online fonts; after--embed there are no external dependencies)
  6. Automatically adds a TOC sidebar + scroll spy

Step 4 · Open in a browser to verify

open output.html

Check:

  • Heading levels are correct
  • Upgrade component positions are accurate
  • No duplicate content (bilingual filtering works)
  • Images load properly
  • TOC navigation works
  • No consecutive double-line issues

Step 5 · Export PDF / long image (model executes; there is no export button on the page)

When the user wants a PDF or long image, the model runs the export script (requires Chrome + puppeteer-core, first time in the skill directory npm install; Chrome path can be specified with CHROME_PATH ):

node scripts/export.mjs output.html --pdf output.pdf                 # A4，走页面的 print CSS（空白预算 ≤25%/页）
node scripts/export.mjs output.html --png output.png --width 1440    # 全页长图，默认 2x 像素
node scripts/export.mjs output.html --pdf a.pdf --png a.png --color forest-ink --font 0   # 指定配色/字体（主题 id、序号或名称）

The script first changes lazy-loaded images to load immediately and scrolls the whole page, waiting for all images and document.fonts.ready, the long image hides the settings button and table of contents. After export, check: no missing images (the script prints failed images), reasonable PDF page count, no large blank pages. Attach the exported file on delivery.

  • Long images have a height limit: when page height × scale exceeds about 16000 pixels, the script automatically lowers the scale and gives a notice; for extremely long pages, it is recommended to provide only the PDF
  • The PDF fills the entire page with the page's theme paper color (dark themes are also dark), with margins in the content
  • --embed only has built-in fonts; local images are still files next to the HTML, so when delivering the HTML, give the image folder along with it
  • After readers open the page, they can directly click on text to edit it (headings, paragraphs, and table cells are all editable); after editing, use browser printing or export again

Component reference

See references/components.md。

Design rules

See references/design-rules.md。

Automatically rendered elements (no annotation needed)

The following elements are automatically recognized by the renderer and do not need to be declared in annotations.json:

  • Markdown tables（| col | col |) → themed <table>
  • HTML tables（<table>...</table>) → passed through directly, wrapped in .table-wrap middle
  • Code blocks（```) → dark background <pre><code>
  • Native bar charts（```chart code block) → pure HTML/CSS bar chart (no JS, exportable to PDF/long image, follows the color palette). Format:title: / unit: / max: / series: A, B(grouped) / highlight: 名称 / note: / source:, data rows 标签 | 值(when grouped 标签 | 值1 | 值2). Non-numeric values display as "no data".
  • Table enhancements: separator row --: controls alignment; pure numeric columns are automatically right-aligned + tabular numbers;**数值** bold means emphasis; a line immediately below the table 表：… / 来源：… serves as the table caption
  • Replace screenshots with native tables/charts: If the numbers in parameter tables and benchmark charts in the article are clear, they should be transcribed into Markdown tables + ```chart. Only transcribe numbers that are clearly legible; write "?" for unclear ones (rendered as "no data") or keep the original image; never estimate or fabricate; state in the table caption which image it was transcribed from
  • Images（![alt](url)）→ <figure> + <img> + optional caption
  • blockquote（> text) → styled blockquote
  • Ordered/unordered lists（1. / -) → standard lists
  • Footnotes: write in the body [^1], write anywhere [^1]: 说明, rendered as superscript numbers and an end-of-document list (if there is a ## 脚注 / ## Footnotes section, put it there; otherwise create a new section); the footnote section automatically reduces font size and spacing

Gotchas

  1. Do not significantly cut user content。Elevation is component replacement on the original text line, not deletion, modification, or rewriting.
  2. Do not add too many divider lines. Swiss style is a card language—separate with background color/spacing, not lines. Zero lines between sections.
  3. Do not set meta.langfor monolingual documents. lang is used for language filtering in bilingual documents; set it to nullfor all-English/all-Chinese documents, otherwise all non-target-language paragraphs will be skipped.
  4. The line of highlight must exactly correspond to the bolded line. If it is off by one line, the original paragraph will show both the elevated component and the original paragraph.
  5. The SVG of embed must be purely inline, and must not reference external files. The recommended viewBox width is 600-720. Do not hard-code colors: use currentColorfor lines and text (follows the body text color), use style="fill:var(--accent)" / stroke:var(--accent)for emphasis, use var(--paper-2)for light background blocks, and use var(--line)for lines, so the graphic changes with the theme (including the dark Midnight Ink theme). On mobile, the graphic keeps a readable minimum width and scrolls horizontally
  6. hero_image can only use photos/video frames(on-site photos, video screenshots, architecture/geometric photography),never use tables, charts, rankings, or text screenshotsas the header image. If unsure, write "hero_image": "auto" or omit it: the renderer will pick the first photo from the body images whose filename/caption does not look like a chart (preferring “video screenshot/photo/panorama”), and automatically rejects candidates whose filename or caption contains chart/table/bench/index/图表/表格/评测/基准/指数.
  7. After writing annotations.json, count the line numbers first. A common mistake is miscalculating line numbers, causing annotations to land on blank lines or the wrong paragraphs.
  8. The large number and the title must be on the same line(Swiss mode). The renderer already handles this, but if writing HTML by hand, note that you should use flex baseline rather than splitting into two lines.
  9. Bold text inside a highlight cardautomatically inherits white (on a dark background), so there will be no problem of black text disappearing.