From long text to structured docs
A Claude Code skill that transforms any long-form text into a paginated documentation site — structured, visual, scannable, self-contained HTML.
Why this exists
Most LLM-generated docs are flat markdown. No navigation, no structure, no editorial judgment. This skill fixes that — it decides what format each idea deserves before writing one line of HTML.
Paste any essay, analysis, guide, or reference doc. The skill runs a 6-phase editorial process — parse, classify, compress, structure, render, deliver — and produces a single self-contained HTML file that opens in your browser instantly.
No build step. No npm. No server. Just a file that works.
What you get
Editorial workflow
Six phases from raw text to browser-ready documentation. The format decision in Phase 2 is what separates this from a template renderer.
The 6 phases
Parse → decide format per section → compress → structure navigation → render using template → deliver. Never start writing HTML before Phases 1–3 are done.
flowchart LR
P1["Phase 1\nParse & Inventory"] --> P2["Phase 2\nFormat Decision"]
P2 --> P3["Phase 3\nCompression"]
P3 --> P4["Phase 4\nNavigation"]
P4 --> P5["Phase 5\nRender"]
P5 --> P6["Phase 6\nDeliver"]
classDef core fill:#7a2e0e18,stroke:#7a2e0e,stroke-width:1.5px,color:#7a2e0e
classDef support fill:#0e3a2e14,stroke:#0e3a2e,stroke-width:1px,color:#0e3a2e
class P2,P3 core
class P1,P4,P5,P6 support
Phase 1 — Parse & Inventory. Read the full source. Detect macro-sections. Classify each: concept, law, pattern, anti-pattern, sequence, comparison, checklist. Flag redundancies and high-density sections that need compression.
Phase 2 — Format Decision. The core step. For each section, pick the rendering format that fits the content type. Not everything is a diagram. Not everything is a table. See the decision table below.
Format decision table
| Content type | Best format |
|---|---|
| Cause → effect relationship | Mermaid flowchart |
| Step-by-step process | Mermaid flowchart or numbered steps |
| Good vs bad practice | DoDont card |
| Spatial / layout concept | PatternVisual (HTML/CSS) |
| Named law + implication + action | LawBlock card |
| Set of operating principles | RuleCard grid |
| Failure mode | AntiPattern card (symptom + cost + fix) |
| Abstract concept + definition | Prose + TL;DR + applied example |
| Actionable checklist | Checklist component |
| Closing compression | CompressionSummary |
The rule: if it scans better than it reads → visual. If it needs nuance or argument → prose. If it has tabular structure → table. Never force visual where a precise sentence covers it better.
Semantic compression
Rewrite content before rendering. Remove filler. Preserve precision. One idea per block.
Compression rules
This is not caveman speak. It's editorial compression: precise, technical, scannable. Filler out. Vocabulary intact. One strong idea per sentence.
Each paragraph, card, or list item carries exactly one idea. If it can be split, split it. If it can be cut, cut it. If the reader can stop after the first sentence and have the key insight, the block is correct.
- Sentences over 25 words can be split — do it
- Remove: "cabe destacar que", "it's worth noting", "in this sense", "as we can see"
- Pattern: noun + verb + impact — no padding before or after
- Technical vocabulary stays intact — never simplify at the cost of precision
Before and after
They hunt for semantic anchors.
Visual hierarchy decides what survives the first glance.
In short
- One idea per block. Split anything over 25 words.
- Kill filler openers. Start with the noun that matters.
- Technical vocabulary is untouchable. Precision stays.
- Write the TL;DR last — it forces you to know what the section is actually about.
- If the reader can stop at the first sentence and have the key insight, you're done.
Component library
All visual blocks available in the output. Use only what the content actually needs — each component earns its place through the format decision in Phase 2.
Available components
13 components. Each maps to a content type. Using the wrong component for a content type is an anti-pattern, not a stylistic choice.
Format anti-patterns
The most common mistakes when applying docs-generator. Each one has a predictable symptom and a direct fix.
Format mistakes
The most common failure is forcing a visual where prose is more precise. The second most common is decorating without information. Both come from skipping Phase 2.
Quick start
Everything you need to use docs-generator in one page.
Install
git clone --depth 1 https://github.com/franciscobeccaria/docs-generator.git /tmp/docs-generator
cp -r /tmp/docs-generator ~/.claude/skills/docs-generator
rm -rf /tmp/docs-generatorUsage
/docs-generator [paste your text here]
/docs-generator --file ~/path/to/document.md
/docs-generator --file ~/notes/analysis.txt --name my-guideOutput is written to ~/.agent/docs/{topic}.html and opened in your browser automatically.
Pre-ship checklist
- Phase 2 (format decision) done before writing any HTML
- Every section has a TL;DR
- No walls of text — every block under 5 sentences
- Every visual earns its place (removes it → information lost)
- Mermaid diagrams have zoom controls
- Light and dark themes both look intentional
- No overflow at narrow widths (min-width: 0 on flex/grid children)
- The value is Phase 2 — format decision per section, not template filling.
- Compression before render. One idea per block. TL;DR every section.
- Visual only when it conveys something prose cannot. Otherwise: prose.
- Output is self-contained HTML. No build, no server, opens anywhere.
- The squint test: hierarchy visible without reading. If not, revise.