awesome-docs

Generate, convert, and maintain animated Markdown documents with GitHub-safe SVG animations.

---

Mode: generate

Create a new animated Markdown document from scratch. Adapts structure and SVGs to the document type — not limited to demo docs.

Steps:

1. Ask one at a time:
   • Document type — what kind of document? Choose from: readme, architecture-guide, runbook, tutorial, api-reference, how-it-works, rfc, post-mortem, or custom (user defines sections)
   • Topic / subject — what is the document about? (e.g. "KEDA autoscaling", "orders-service API", "Kubernetes upgrade runbook")
   • Output path — where should the file be written? (e.g. README.md, docs/architecture.md, runbooks/keda.md)
   • Key components — the main moving parts, concepts, or resources covered (3–6 items)
2. Show the user an outline of the proposed document structure and which SVG patterns will apply:
   • List the sections from the doc-type section map (see below) in order
   • Next to each section that will get an SVG, note the pattern name: e.g. Architecture → arch-flow
   • Ask: "Does this structure look right? Confirm to continue or describe what to change."
   • Only proceed after explicit confirmation; adjust sections or pattern choices on request
3. Classify which SVG patterns are relevant to this doc type and topic:
   • arch-flow — any doc that describes a system with multiple components or a data flow
   • lifecycle-loop — docs covering a repeating control loop, approval cycle, or state machine
   • sequence-diagram — docs covering request/response chains, API call sequences, or auth flows
   • state-machine — docs covering distinct states and transitions (deployment lifecycle, approval workflow, error/retry paths)
   • field-carousel — docs covering a configurable resource (YAML, HCL, JSON, or TOML); ask the user to paste their config at this point and identify the format before generating
   • timeline-phases — docs covering distinct phases, stages, or a lifecycle with durations
   • For rfc, post-mortem, runbook: SVGs are optional — ask "Would diagrams help here?" before generating
4. For each applicable SVG pattern (incremental):
   • Generate the SVG using the blueprint in references/awesome-docs.md
   • Write to assets/<topic-slug>-<pattern>.svg
   • Show to the user and ask: "Does this look right? Confirm to continue or describe what to adjust."
   • Only proceed to the next SVG after explicit confirmation
5. Build the document structure from the doc type section map below
6. Write the file to the output path with all confirmed SVGs embedded using <img> tags, each followed by a > blockquote caption
7. Commit: git add <output-path> assets/ && git commit -m "docs(<scope>): add <doc-type> for <topic>"

Doc type section map — use these as the default structure, adapt to user needs:

Doc type	Default sections
readme	Header (title + badges), Overview, Architecture diagram (arch-flow), How it works, Getting started, Configuration (field-carousel if applicable), Examples, Troubleshooting
architecture-guide	Overview, System diagram (arch-flow), Component responsibilities, Data flow, Scaling/state behavior (lifecycle-loop or state-machine), Configuration reference (field-carousel), Deployment phases (timeline-phases), Decisions & trade-offs
runbook	Prerequisites, Health check commands, Architecture diagram, State/failure paths (state-machine if applicable), Step-by-step procedure, Validation, Rollback
tutorial	Introduction, Prerequisites, Architecture overview (arch-flow), Request flow (sequence-diagram if API-heavy), Step-by-step walkthrough, What you built, Next steps
api-reference	Overview, Authentication, Request flow (sequence-diagram), Endpoints, Request/response fields (field-carousel), Error codes, Examples
how-it-works	Overview, Architecture diagram (arch-flow), Lifecycle/control loop (lifecycle-loop or state-machine), Request flow (sequence-diagram if applicable), Configuration fields (field-carousel), Load phases (timeline-phases if applicable)
rfc	Context and problem, Proposal, Architecture diagram, Alternatives considered, Decision criteria, Open questions
post-mortem	Incident summary, Timeline, Root cause analysis, Impact (state-machine of failure path if helpful), Action items, Lessons learned
custom	Ask the user to list the sections they want, then generate them in order