HTML Docs MCP Server

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

Related MCP server: LLMSTXT-MCP Server

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.

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/<slug>

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.