html-docs-skill

Point Codex or Claude at a folder, codebase, website, paper, PDF, document, or research topic.

Get a source-grounded HTML document, narrated explainer video, or complete learning course—with citations, captions, editable scenes, and a shareable site.

Should you use this?

Use HTML Docs when the answer needs to teach, not merely exist:

For a quick factual answer or a throwaway note, ask your agent normally. Use

this skill when source grounding, visual explanation, narration, presentation,

or a reusable learning experience matters.

This is not a separate chatbot. It is a production workflow installed into the

Codex or Claude Code session you already use:

your source → your agent + $html-docs → private page, Player, and Studio

Start in sixty seconds

npx skills add raunaqbn/html-docs-skill --skill html-docs -g

Then:

1. Start a fresh Codex task or Claude Code session.

2. Open it in the source folder, or give it a URL, PDF, document, or topic.

3. Mention `$html-docs`, the audience, and what they should understand.

For example:

Use $html-docs to turn this codebase into a private course for new engineers.

No hosted authoring model is hidden behind the command. Your current agent

researches, writes, designs, and authors the project. The open local tools

normalize sources, compile scenes, synchronize narration, audit frames, render

media, and publish a private preview.

Ask for the outcome you need

Automatic runs stay private. Public or unlisted publication is a separate,

explicit action.

Built with HTML, voice, and evidence

These lightweight loops are frames from real HTML Docs renderer output—not

product mockups.

From terminal to published

The document preserves the launch brief and review context. The companion video teaches the workflow visually.

How two samples become velocity

A formula becomes a concrete mental model with timed motion, captions, and a settled visual read.

Guarding a velocity estimator

A defensive-programming lesson turns invalid timestamps and non-finite inputs into a visual contract learners can remember.

Explore the live Player, course pages, source projects, and Studio artifacts in

the HTML Docs showcase.

Complete course examples

Reproduction briefs and portable source ledgers live in

`examples/`: codebase → course, website → document + video, and

research topic → course.

The production loop

folder · repo · URL · PDF · document · topic
                      │
                      ▼
          source snapshot + evidence graph
                      │
                      ▼
        learner contract · course specification
                      │
                      ▼
        vertical lesson slices · mastery evidence
                      │
           ┌──────────┴──────────┐
           ▼                     ▼
    rich HTML page        locked narration
                                 │
                                 ▼
                     timed words + visual cues
                                 │
                                 ▼
                  deterministic HTML scene modules
                                 │
                                 ▼
                  audit · Player · Studio · MP4

The page and video share one evidence model but serve different jobs: the page

is the detailed reference; the video teaches the core mechanism visually.

Courses also preserve the learner’s purpose, canonical terminology,

demonstrated capabilities, misconceptions, retrieval schedule, source ledger,

and the decision trail behind the curriculum. Completion is navigation state;

mastery requires evidence.

Why the synchronization holds

• Generate or record final audio before final scene timing.
• Prefer provider-native word timestamps.
• Forced-align the locked transcript when timestamps are unavailable.
• Assign every spoken word to exactly one cue and scene.
• Give every cue one or more same-scene `data-html-video-id` targets.
• Derive captions, chapters, scenes, and visual timing from the same word track.
• Seek Chromium to explicit timestamps; never depend on wall clocks or

self-running animation.

• Compare repeated same-time captures and inspect cue/scene contact sheets.

Voice profiles are provider-neutral: `warm-teacher`, `gentle-guide`,

`precise-engineer`, and `energetic-coach`. ElevenLabs is supported through

bring-your-own-key; Kokoro is the offline fallback. Provider keys stay local.

The open product

Authored source, rendering, voice generation, and provider credentials stay on

your machine. HTML Docs hosts private project versions, collaborative pages,

the live Player, Guided Studio, course sites, and explicitly published media.

Local project commands

The skill invokes these for you, but every stage is inspectable:

# Any source, with an explicit or automatic output mode
html-docs project init ./source --mode auto --output ./explanation
html-docs project build ./explanation
html-docs project audit ./explanation
html-docs project preview ./explanation

# A video
html-docs/scripts/video.sh build ./video-project
html-docs/scripts/video.sh check ./video-project
html-docs/scripts/video.sh audit ./video-project
html-docs/scripts/video.sh render ./video-project --output ./final.mp4

# A course
html-docs/scripts/video.sh course init ./source \
  --output ./course-project --title "Course title"
html-docs/scripts/video.sh course build ./course-project
html-docs/scripts/video.sh course audit ./course-project
html-docs/scripts/video.sh course preview ./course-project
html-docs/scripts/video.sh course publish ./course-project

Renderer frame caches are content-addressed. If Chromium or FFmpeg is

interrupted, rerunning the render reuses every completed deterministic frame.

The scaffold is only a normalized starting point. The active agent replaces it

with the evidence graph, learner contract, course specification, dependency

map, vertical lesson slices, lesson pages, narration, storyboards, semantic

scenes, diagnostic practice, captions, and checks.

Publish any HTML

The document-only path stays one command:

npx @html-docs/cli publish page.html
# → https://www.html-docs.com/site/

Authenticate owned work:

npx @html-docs/cli auth

Install the MCP server in detected clients:

npx @html-docs/cli install

Available tools include document publishing, reading, updating, commenting,

video synchronization, and project operations. See the

agent guide and

API reference.

Portable artifacts

Courses and videos are ordinary folders with JSON manifests, a learner

contract, course specification, mastery records, production slices, Markdown

briefs, HTML/CSS/JavaScript scene modules, audio files, timed words, captions,

evidence records, quality reports, and rendered fallbacks. They can be

inspected, versioned, moved, rendered locally, or hosted independently.

License and provenance

The HTML Docs skill, Producer, Player, and Studio are MIT licensed. Third-party

dependencies and adapted design references are recorded in

`NOTICE`. See `PROVENANCE.md`

and `THIRD_PARTY_NOTICES.md` for release provenance.