HTML Docs

HTML Docs

Create the clearest useful explanation of the user’s source. Use the active Codex or Claude session to research, write, design, and author the artifacts. Use the local CLI only to normalize sources, compile, validate, render, synchronize, and publish. Never invoke a hidden authoring model.

Choose the output

Resolve an explicit user request first. Otherwise use auto:

State the chosen mode in one short working update, then continue. Do not stop for storyboard or voice approval unless the user requests an approval gate. Finish automatic work as a private preview. Publish publicly or unlisted only after explicit instruction.

Start from any source

Classify the input before authoring:

• HTML Docs document or folder: read it through the API.
• Local document, PDF, HTML, Markdown, or text: recover its structure and facts.
• Directory or Git repository: respect ignore rules; exclude credentials, dependencies, build output, binaries, and VCS internals.
• URL: capture the requested page. For a site-level request, crawl same-origin links to depth two and at most 100 pages unless the user sets another bound.
• Research topic: perform deep research with primary and authoritative sources. Freeze a source manifest before writing.
• Pasted material: preserve it as a source record rather than treating it as unsupported background knowledge.

Read references/source-grounding.md for source normalization, research, privacy, evidence IDs, and refresh rules.

Universal production loop

1. Define mastery. Identify the audience, prerequisites, confusion gap, desired capability, thesis, mechanism, evidence, and limits.
2. Ground claims. Create stable source/evidence records. Every substantive claim and knowledge-check answer must cite evidence.
3. Design the explanation. Build a cumulative teaching spine. Do not follow source order when another sequence teaches better.
4. Specify the learning experience. For a course, define the learner contract, demonstrated mastery states, assessment seams, dependencies, and vertical production slices before authoring.
5. Choose a visual language. Set typography, dominant color, contrast, diagram grammar, layout rhythm, and one memorable visual signature.
6. Author the selected outputs. Derive the page and video from the same lesson/evidence model without duplicating them: the page is the reference; the video teaches the mental model.
7. Audit. Check facts, citations, readability, responsive behavior, accessibility, visual quality, narration coverage, cue ownership, captions, deterministic seeking, and contact sheets.
8. Refine until clean. Fix every failing audit and every visibly weak scene.
9. Publish privately. Return the private document/course link and the stable video player link. Mention raw MP4 only as a fallback or requested download.

Document workflow

Read references/design-system.md before any substantial document. Use references/anti-slop.md as the final visual linter. Use inline CSS and inline SVG; freeze assets locally.

Publish:

npx @html-docs/cli publish page.html
npx @html-docs/cli publish ./site --slug my-site

Authenticate owned work once:

npx @html-docs/cli auth

Read references/api.md when editing regions, commenting, versioning, or using document APIs. Read references/pdf.md for PDF import or export.

For documents that will be reviewed or updated later, give each meaningful HTML block a stable data-hd-block-id. Use targeted block/region PATCH calls for local changes. Before a whole-document PUT, GET the document and send its ETag in If-Match; never overwrite a newer human review revision blindly.

Agent editing loop

For an existing HTML Docs document, treat GET /api/v1/docs/:id/editor as the live semantic source of truth. Apply the smallest precise batch through POST /api/v1/docs/:id/editor/commands, then read the editor state again to verify it. Use visible UTF-16 offsets and expectedText for region selections; round-trip node_checks as target_checks for structured documents. A 409 is a request to reread and replan, never permission to overwrite.

Use set_marks to format only the selected phrase, semantic block/node types for hierarchy, bounded block styles for alignment and spacing, and comments for review feedback. Prefer one title, consistent heading levels, predictable labels, short paragraphs or lists, and a final Notes section. Every agent command batch creates a recovery version and publishes through the collaboration backend, so do not replace the whole document for a local formatting change.

For a flow, timeline, callout, metric strip, comparison, or decision matrix, send a semantic visual specification to POST /api/v1/docs/:id/editor/visuals; do not improvise a large HTML/SVG block. The endpoint uses the same deterministic renderer as Docsmith in both editor engines and creates a recovery version first.

When the user explicitly asks for a complete transformation, read the entire editor payload before writing. For structured documents, send one isolated replace_document command with the complete semantic doc JSON. For region documents, use a conditional whole-document PUT with the latest ETag. Both paths must preserve the pre-change version; a 409 or 412 means reread and replan, not force overwrite.

Video workflow

Read both:

• references/html-video.md for project format, narration, timing, captions, compilation, rendering, and publication.
• references/video-scene-craft.md for explanatory scene grammar, layout rhythm, cue choreography, and visual review.

For narrated work, render captions in the composition itself as a karaoke rail: keep the phrase readable while the exact word currently spoken receives the design-matched highlight. WebVTT/SRT metadata alone is not a finished caption system.

For a narrated explainer:

<skill-root>/scripts/video.sh build ./video-project
<skill-root>/scripts/video.sh check ./video-project
<skill-root>/scripts/video.sh audit ./video-project
<skill-root>/scripts/video.sh render ./video-project --output ./final.mp4

For a document-linked video:

<skill-root>/scripts/video.sh publish ./video-project \
  --document <document-id> \
  --prompt "Teach the central mechanism clearly" \
  --provider codex

For a standalone video, omit --document after the standalone video API is available in the installed CLI release. Always prefer the stable /v/<code> player link over the raw storage URL.

Course workflow

Read all three:

• references/html-course.md for portable course artifacts, paired pages/videos, checks, publication, and refresh.
• references/learning-design.md for the learner contract, mastery evidence, retrieval, feedback, adaptation, and reusable teaching components.
• references/course-specification.md for decision-rich course specs, vertical production slices, dependencies, validation seams, and large-project uncertainty.

Then:

<skill-root>/scripts/video.sh course init <source> \
  --output ./course-project --title "Course title"
<skill-root>/scripts/video.sh course build ./course-project
<skill-root>/scripts/video.sh course audit ./course-project
<skill-root>/scripts/video.sh course preview ./course-project
<skill-root>/scripts/video.sh course publish ./course-project

The scaffold is not the course. Replace it with a real evidence graph, course specification, learner model, course map, vertical lesson slices, lesson pages, locked narration, cue-directed storyboards, semantic scene modules, diagnostic checks, captions, and source dependencies before building.

For changed sources:

<skill-root>/scripts/video.sh course diff ./course-project
<skill-root>/scripts/video.sh course refresh ./course-project

Regenerate only affected lessons, preserve surviving semantic overrides, audit again, and create a new private version. Never replace the published version automatically.

Guided Studio

Use Studio after a private version exists:

<skill-root>/scripts/video.sh studio context <video-id>
<skill-root>/scripts/video.sh studio requests <video-id>

Treat a Studio selection as precise source context: composition version, scene, timestamp, semantic element ID, bounds, text, evidence, and surrounding cue. Apply direct layout/text/color changes as structured overrides. Apply narration, voice, evidence, or generative scene changes in the local project, audit, then push a new immutable version.

Publication and authentication

• Anonymous documents can be published with curl or the CLI.
• Owned videos, courses, edits, and durable publication require HTMLDOCS_API_KEY or credentials saved by npx @html-docs/cli auth.
• Keep provider keys local. Never upload TTS keys or put them in a project bundle.
• Keep source projects and diagnostics private. Only published runtime bundles, posters, and media should be public.

Machine-readable API:

curl https://www.html-docs.com/api/v1

Human documentation:

• https://www.html-docs.com/agents
• https://www.html-docs.com/developers
• https://www.html-docs.com/showcase