/awesome-docs

name: awesome-docs
description: Generate, convert, and maintain animated GitHub-safe Markdown documents with animated SVG diagrams. Covers four SVG patterns (architecture flow, lifecycle loop, field carousel, timeline phases), guided interview for any doc type (README, architecture guide, runbook, API reference, tutorial, RFC, post-mortem, how-it-works, or custom), converting existing plain Markdown, diffing for stale diagrams, quality auditing, local preview, and multi-platform export. Use when asked to "create a README for X", "write an architecture doc", "animate this guide", "convert my doc to animated", "check if my diagrams are stale", or "export my doc for Confluence".
argument-hint: "[generate|convert|update|diff|audit|preview|export] [doc type or file path]"
title: "Awesome Docs Command"
sidebar_label: "awesome-docs"
custom_edit_url: null

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 |

**Theme parameter:** append `--theme github-dark` (default), `--theme docs-light`, or `--theme custom:#bg,#primary,#accent` to override colors. See `references/awesome-docs.md` → Theme System.

If you need deeper context on SVG patterns, theme configuration, or the quality checklist, load `references/awesome-docs.md`.

---

Mode: convert

Animate an existing plain Markdown document by injecting SVGs in-place.

Steps: 1. Ask: path to the existing Markdown file, or a directory path for batch mode (e.g. `docs/keda-guide.md` or `docs/`)

• If a directory is given, discover all `.md` file