webpage-screenshot-md

name	webpage-screenshot-md
description	Use when the task is to capture reusable screenshots from a local or remote webpage and insert those images into a Markdown article or note. Best for blog posts, Zhihu/公众号 drafts, documentation pages, product pages, or local static-site previews where the user wants selected sections cropped by CSS selector and turned into Markdown image blocks.

Webpage Screenshot MD

Overview

This skill packages a repeatable workflow for:

• capturing section-level screenshots from a webpage with Puppeteer
• mixing full-page long screenshots with section-level screenshots
• saving the images to a target folder
• generating Markdown ![alt](path) snippets that can be pasted or written into an article
• optionally updating a target Markdown file directly

Use it when the user wants more than a one-off screenshot and would benefit from a reusable capture script or config.

When To Use

Use this skill when the task includes one or more of these patterns:

• "把这个页面几个模块截图下来，插到文章里"
• "给这个专题页自动截几张图"
• "做个可复用的网页截图脚本"
• "把截图和 md 插图流程封装一下"
• "我以后还会反复对这个页面截图"

Do not use it for image editing, SVG-native edits, or when the user only needs a single ad hoc screenshot with no reusable workflow.

Workflow

1. Decide the page source

Pick the least fragile source:

• Remote published page: open the real URL directly.
• Local static site: prefer a local HTTP server such as python3 -m http.server 8766 --directory site.
• Raw file:// pages: avoid when possible because dynamic fetches often fail.

2. Identify the capture targets

Create or update a JSON config listing the sections to capture.

Use CSS selectors that are stable and meaningful:

• section mounts such as #cc-tool-tiles-mount
• major blocks such as .hero
• unique widgets such as #cc-loop-player

Avoid brittle selectors based on DOM order alone.

3. Run the bundled capture script

Use:

node ~/.codex/skills/webpage-screenshot-md/scripts/capture_sections.js \
  --url http://127.0.0.1:8766/topic-cc-unpacked-zh.html \
  --config ~/.codex/skills/webpage-screenshot-md/references/config-example.json \
  --out-dir /absolute/path/to/images \
  --md-out /absolute/path/to/snippets.md

The script:

• opens the page with Puppeteer
• waits for the selectors
• scrolls each block into view
• supports both type: "fullPage" and type: "selector" shots in one run
• saves cropped PNG files
• optionally writes Markdown image lines to --md-out

Markdown Insertion

If the user wants the article file updated:

1. generate screenshots first
2. inspect the article structure
3. insert image blocks near the matching section using concise alt text

Prefer relative paths from the article file to the image file. Keep alt text descriptive but short.

Example:

![工具系统分组地图](../images/topic-cc-unpacked-tool-system.png)

To let the script update the article directly:

node ~/.codex/skills/webpage-screenshot-md/scripts/capture_sections.js \
  --url http://127.0.0.1:8766/topic-cc-unpacked-zh.html \
  --config /absolute/path/to/config.json \
  --out-dir /absolute/path/to/images \
  --target-md /absolute/path/to/article.md \
  --insert-mode append

Supported insertion modes:

• append: add the image block to the end of the file
• replace-marker: replace a marker string such as <!-- SCREENSHOTS -->

Marker example:

node ~/.codex/skills/webpage-screenshot-md/scripts/capture_sections.js \
  --url http://127.0.0.1:8766/topic-cc-unpacked-zh.html \
  --config /absolute/path/to/config.json \
  --out-dir /absolute/path/to/images \
  --target-md /absolute/path/to/article.md \
  --insert-mode replace-marker \
  --marker '<!-- SCREENSHOTS -->'

Config Guidance

Use a JSON file shaped like the sample in references/config-example.json.

Each shot supports:

• type: fullPage or selector; default is selector
• selector: required CSS selector
• file: output filename
• alt: alt text for Markdown generation
• block: optional scroll alignment, usually center
• waitMs: optional per-shot extra wait before capture

Use page-level config for:

• viewport
• waitMs
• shots

Puppeteer Resolution

The script tries to load Puppeteer from:

1. process.cwd()/node_modules/puppeteer
2. the skill's own node_modules/puppeteer
3. normal Node resolution

If Puppeteer is missing, install it in the working project or another reachable Node environment.

Output Expectations

When using this skill, aim to leave behind:

• generated PNG files in the requested image folder
• a reusable JSON capture config when the task is likely to repeat
• a Markdown snippet file or direct article edit
• a short note about which URL and selectors were used

Resources

scripts/capture_sections.js

Reusable Puppeteer capture tool for section screenshots plus optional Markdown snippet generation.

references/config-example.json

Minimal example config showing the expected schema.