leeguooooo htmldock
Use htmldock for HTML technical documents that should be published to the team document base.
Agent Autopilot
When the user wants to upload or publish HTML, do not ask how to install the CLI.
- Check whether
htmldockworks:
command -v htmldock && htmldock --version
- If it is missing, install it automatically from the GitHub Release binary. Prefer the bundled installer:
installer="$(find "$HOME/.codex/skills" "$HOME/.agents/skills" -path "*/htmldock/scripts/install-cli.sh" -print -quit 2>/dev/null)"
if [ -n "$installer" ]; then
bash "$installer"
else
curl -fsSL https://raw.githubusercontent.com/leeguooooo/htmldock/main/scripts/install.sh | bash
fi
- If the binary was installed to
~/.local/binand that directory is not in PATH, run it by absolute path for this session:
~/.local/bin/htmldock --version
- If the user says they already have a token, configure it with
htmldock config set-token <token> --server <server>. Never ask the user to choose between install methods.
Upload Workflow
- Confirm the target repo has
.htmldock.toml. If it does not, runhtmldock initonce from the repo.teamis required in.htmldock.toml; ask the user which team this repo belongs to, or runhtmldock team listto see joined teams. - Before writing the HTML, run
htmldock list --treefor the current project to see the existing module tree. Reuse existing module prefixes (auth/,billing/,infra/) rather than inventing synonyms (authentication/,infrastructure/). - Keep the published file path at three display segments or fewer after
module_rootis removed:- ✓
auth-redesign.html(1 level) - ✓
auth/login-flow.html(2 levels) - ✓
auth/oauth/lark-integration.html(3 levels) - ✗
auth/oauth/lark/v2/proposal.html— server rejects withpath_too_deep
- ✓
- Upload with:
htmldock push path/to/doc.html
Use --public only when the document is safe to share by public token.
Team Workflow
htmldock team create acme-infra "Acme Infrastructure" # create team (you become admin)
htmldock team list # list teams you joined
htmldock team add acme-infra alice@example.com # admin: invite member
Deleting Documents
Hard delete — no recycle bin, not recoverable:
htmldock delete <doc-id> # delete one doc (you own it, or you are team admin)
htmldock project delete acme-infra/cherry --yes # delete whole project (team admin only)
HTML Style Reference
When generating the HTML you are about to publish, match the patterns in
ThariqS/html-effectiveness
— Thariq Shihipar's 20-file companion to his essay
The Unreasonable Effectiveness of HTML. Use the file whose category
fits the doc you are writing:
| Doc kind | Reference file in ThariqS/html-effectiveness |
|---|---|
| Exploration of options (code/visual) | 01-exploration-code-approaches.html, 02-exploration-visual-designs.html |
| Code review / PR walkthrough | 03-code-review-pr.html, 17-pr-writeup.html |
| Code understanding / module walkthrough | 04-code-understanding.html |
| Design system / component variants | 05-design-system.html, 06-component-variants.html |
| Animation / interaction prototype | 07-prototype-animation.html, 08-prototype-interaction.html |
| Slide deck | 09-slide-deck.html |
| SVG illustration / diagram | 10-svg-illustrations.html, 13-flowchart-diagram.html |
| Status / weekly / quarterly report | 11-status-report.html |
| Incident / postmortem / RCA | 12-incident-report.html |
| Feature explainer / research deep-dive | 14-research-feature-explainer.html, 15-research-concept-explainer.html |
| Implementation plan | 16-implementation-plan.html |
| Tunable / editable artifact (knobs, triage board) | 18-editor-triage-board.html, 19-editor-feature-flags.html, 20-editor-prompt-tuner.html |
A hosted mirror of all 20 examples lives at
https://htmldock.pwtk-dev.work under team html-effectiveness,
project gallery. Browse there for quick visual comparison without
cloning the repo.
Style invariants to copy:
- Self-contained
<style>in<head>— no external CDN, no JS frameworks - CSS custom properties on
:rootfor the palette - Semantic tags (
<header>,<section>,<aside>,<table>) — not div soup - Tables beat nested bullet lists for structured data
- One accent color + two or three grays — no decoration for its own sake
- Font stack:
-apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", "Inter", sans-serif
Token Setup
The CLI reads ~/.config/htmldock/config.toml:
server_url = "https://<your-htmldock-url>"
pat = "hd_pat_..."
default_project_sync = "off"
If no token is configured, run:
htmldock login
If the user already has a PAT, configure it with:
htmldock config set-token hd_pat_... --server https://<your-htmldock-url>
Useful Commands
htmldock list
htmldock push ./design.html --public
htmldock share 1 --ttl-days 30
htmldock open 1
Install This Skill
Platform-agnostic; install once for every agent on the machine:
npx skills add leeguooooo/htmldock --skill htmldock -g
(Pass -a <agent> to scope to one runner, e.g. -a codex or -a claude. Default registers for all detected agents.)
Do not paste PAT values into chat or committed files.