create-idocs 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -2
- package/template/.claude/skills/idocs/SKILL.md +1 -1
- package/template/.claude/skills/idocs/assets/examples/shop.diagram.yaml +1 -1
- package/template/.claude/skills/idocs/references/format.md +23 -0
- package/template/.claude/skills/idocs/references/scenarios.md +3 -3
- package/template/.claude/skills/idocs/references/setup.md +2 -2
- package/template/.claude/skills/idocs/references/troubleshooting.md +5 -0
- package/template/diagrams/diagram.schema.json +46 -0
- package/template/package.json +3 -3
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-idocs",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Scaffold a docs site with interactive diagrams: npm create idocs@latest my-docs",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"access": "public"
|
|
26
26
|
},
|
|
27
27
|
"devDependencies": {
|
|
28
|
-
"@the-package-labs/idocs-core": "^0.
|
|
28
|
+
"@the-package-labs/idocs-core": "^0.4.0"
|
|
29
29
|
},
|
|
30
30
|
"license": "MIT",
|
|
31
31
|
"scripts": {
|
|
@@ -25,7 +25,7 @@ Use the project's package manager for every command below (`pnpm idocs ...`, `np
|
|
|
25
25
|
|
|
26
26
|
1. **Look at what exists.** `idocs list --json` shows the diagrams, views and scenarios. Extend a diagram rather than starting a second one for the same system.
|
|
27
27
|
2. **Read the code you are documenting.** Never invent components, ports, routes or flows. Put the source files a node is based on in its `refs:` so readers can find them and `idocs check` warns when they move.
|
|
28
|
-
3. **Pick a scope.** One diagram answers one question ("how does checkout work?"). Aim for 8 to 25 nodes. If it needs more, make a second **view** of the same model
|
|
28
|
+
3. **Pick a scope.** One diagram answers one question ("how does checkout work?"). Aim for 8 to 25 nodes. If it needs more, make a second **view** of the same model. If one node has an inside worth a diagram of its own, give it `diagram: <name>` ("Nested diagrams" in [references/format.md](references/format.md)) instead of crowding the parent.
|
|
29
29
|
4. **Write the model**: nodes, then groups, then edges. Declare nodes in reading order: order decides layout. Format: [references/format.md](references/format.md).
|
|
30
30
|
5. **Add scenarios** for the flows a reader will ask about: the happy path first, then the failures that teach something. Format and writing advice: [references/scenarios.md](references/scenarios.md).
|
|
31
31
|
6. **Check.** `idocs check --json`. Fix every error and every warning; messages carry `file:line:column` and a suggestion. Common ones: [references/troubleshooting.md](references/troubleshooting.md).
|
|
@@ -36,6 +36,7 @@ Top-level keys: `title` (required), `description`, `nodes` (required), `groups`,
|
|
|
36
36
|
| `links` | `- { label: Runbook, url: https://... }` |
|
|
37
37
|
| `refs` | Source files or URLs the node is based on. `idocs check` warns when a path no longer exists. `src/api.ts`, `src/api.ts:40` and `src/api.ts#L40` all work. |
|
|
38
38
|
| `tags` | Free-form tags. |
|
|
39
|
+
| `diagram` | Name of another diagram (its folder under `diagrams/`) that shows the inside of this node: `diagram: payments`. The card gets **Expand** (show it in place, as a group around the whole inner diagram) and **Open** (move into it, with a trail and Back button). Clicking the node shows the inner diagram as a picture in the drawer. Long form: `diagram: { name: payments, view: refunds, scenario: pay, mode: both, expanded: false }`. See "Nested diagrams" below. |
|
|
39
40
|
|
|
40
41
|
Node kinds: `client user ui external service gateway worker container function database cache storage queue agent network vm auth monitor`. Add or override your own with a top-level `kinds:` map: `ledger: { icon: lucide:book-open, family: amber }`.
|
|
41
42
|
|
|
@@ -105,6 +106,28 @@ views:
|
|
|
105
106
|
|
|
106
107
|
Edges whose two ends are both in the view are included. A scenario plays on the first view unless it sets `view:`; every node it uses must be in that view.
|
|
107
108
|
|
|
109
|
+
## Nested diagrams
|
|
110
|
+
|
|
111
|
+
A node can hold a whole diagram of its own. Write the inside as an ordinary diagram in its own folder, then point the node at it:
|
|
112
|
+
|
|
113
|
+
```yaml
|
|
114
|
+
# diagrams/shop/diagram.yaml
|
|
115
|
+
nodes:
|
|
116
|
+
orders: { kind: service, title: Order service, diagram: orders }
|
|
117
|
+
payments: { kind: service, title: Payments, diagram: { name: payments, scenario: pay } }
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Readers can **expand** the card, which shows the whole inner diagram in place as a group (and nodes inside can be expanded too), or **open** it, which moves into that diagram with its own views, scenarios and player; **Back**, the trail above it, or Esc return to the parent exactly as they left it. Diagrams can nest as deep as the system does.
|
|
121
|
+
|
|
122
|
+
- `mode: both` (default), `expand` or `open` limits which of the two the reader gets. `expanded: true` starts the node expanded, so a page shows the whole picture at once.
|
|
123
|
+
- An expanded diagram is a preview of one view (the one named, else the first). Its scenarios are played by opening it.
|
|
124
|
+
|
|
125
|
+
- Nest when the inside of a node is a story of its own. If it only needs a paragraph, use a node doc (`nodes/<id>.md`); if it only needs a different slice of the same model, use a view.
|
|
126
|
+
- Several nodes may open the same diagram. A diagram cannot be inside itself: a node that opens its own diagram, or diagrams that open each other in a circle, are errors.
|
|
127
|
+
- `idocs check` verifies the name, `view` and `scenario` across diagrams, at the line that wrote them. `idocs list` shows what opens what.
|
|
128
|
+
- Nothing else is needed on the page: a compiled diagram carries the diagrams it can open, so `<Diagram name="shop" />` just works.
|
|
129
|
+
- Links: `#shop~=orders/stock` opens `orders` then `stock`; `#shop+=orders,orders/stock` has those expanded; each level's scenario is `#shop/orders=create.2`.
|
|
130
|
+
|
|
108
131
|
## Pages
|
|
109
132
|
|
|
110
133
|
```mdx
|
|
@@ -16,7 +16,7 @@ scenarios:
|
|
|
16
16
|
steps:
|
|
17
17
|
- browser -> orders:
|
|
18
18
|
label: POST /orders
|
|
19
|
-
note: The request carries an idempotency key. # explanation shown in the
|
|
19
|
+
note: The request carries an idempotency key. # explanation shown in the timeline
|
|
20
20
|
- orders -> db: { label: INSERT order, kind: lookup }
|
|
21
21
|
- title: Charge
|
|
22
22
|
steps:
|
|
@@ -41,7 +41,7 @@ Every step can be written compactly (`a -> b: label`) or as a map (`a -> b: { la
|
|
|
41
41
|
|---|---|
|
|
42
42
|
| `label` | What travels, shown on the packet. Keep it short. |
|
|
43
43
|
| `kind` | `request` (default), `response`, `error`, `lookup`, `event`. Changes the packet's colour and style. |
|
|
44
|
-
| `note` | Markdown explanation shown in the
|
|
44
|
+
| `note` | Markdown explanation shown in the timeline. |
|
|
45
45
|
| `status` | `planned` draws the step dashed with a tag. |
|
|
46
46
|
| `via` | Force the route through these nodes: `via: [gateway]`. |
|
|
47
47
|
| `hold` | Extra pause in seconds. |
|
|
@@ -98,7 +98,7 @@ scenarios:
|
|
|
98
98
|
- **One question per scenario.** "Pay with a card" and "Card declined" are two scenarios.
|
|
99
99
|
- **Failures get their own scenario.** That is where readers learn the most.
|
|
100
100
|
- **Label what travels** (`POST /payments`, `payment.succeeded`) and put the reasoning in `note`.
|
|
101
|
-
- **Two to five phases**, with plain names. They become the chapter headings in the
|
|
101
|
+
- **Two to five phases**, with plain names. They become the chapter headings in the timeline.
|
|
102
102
|
- **Do not narrate the obvious.** A note should answer "why" or "what could go wrong here".
|
|
103
103
|
- **Start at the actor.** The first step is usually `browser -> gateway`, or an `at` step describing the trigger.
|
|
104
104
|
- If a scenario needs a relationship you do not want drawn, add the edge with `hidden: true`.
|
|
@@ -7,7 +7,7 @@ idocs renders diagrams inside an **Astro** site (usually with **Starlight** for
|
|
|
7
7
|
| Package | Role |
|
|
8
8
|
|---|---|
|
|
9
9
|
| `create-idocs` | `npm create idocs@latest`: scaffolds a new site. |
|
|
10
|
-
|
|
|
10
|
+
| `@the-package-labs/idocs` | The CLI: `idocs check`, `list`, `schema`, `icons search`, `new`. |
|
|
11
11
|
| `@the-package-labs/idocs-astro` | The Astro integration and the `<Diagram>` component. |
|
|
12
12
|
| `@the-package-labs/idocs-react` | The interactive diagram component (a dependency of the integration). |
|
|
13
13
|
| `@the-package-labs/idocs-core` | Schema, compiler and layout (a dependency of the others). |
|
|
@@ -30,7 +30,7 @@ This creates an Astro + Starlight project with an example diagram (`diagrams/sho
|
|
|
30
30
|
1. **Install.**
|
|
31
31
|
```sh
|
|
32
32
|
pnpm add @the-package-labs/idocs-astro @the-package-labs/idocs-react @astrojs/react react react-dom
|
|
33
|
-
pnpm add -D idocs
|
|
33
|
+
pnpm add -D @the-package-labs/idocs
|
|
34
34
|
```
|
|
35
35
|
On pnpm 10 or later, allow the build scripts it asks about by adding to `pnpm-workspace.yaml`:
|
|
36
36
|
```yaml
|
|
@@ -15,6 +15,11 @@ Run `idocs check --json` first. Each message has a file, line, column and often
|
|
|
15
15
|
| `A step with at needs a label or a title` | `at x:` needs text: `at x: what happens`. |
|
|
16
16
|
| `"x" is not a direct member of group "g"` | Entries in a group's `rows:` must be nodes or groups whose `in:` is that group. |
|
|
17
17
|
| `Groups are nested in a cycle` | A group's `in:` chain loops back on itself. |
|
|
18
|
+
| `Node "x" opens diagram "y", which does not exist` | The `diagram:` name must be a folder under `diagrams/`. The hint names the nearest one. |
|
|
19
|
+
| `Diagram "y" has no view "v"` / `... no scenario "s"` | The `view` or `scenario` in a node's long-form `diagram:` is not in that diagram. The hint lists what it has. |
|
|
20
|
+
| `Scenario "s" plays on view "a", not "b"` | A node's `diagram:` names both, and they disagree. Drop `view` and it opens on the scenario's own view. |
|
|
21
|
+
| `Node "x" opens "y", which leads back to "z"` / `... opens its own diagram` | Diagrams cannot nest in a circle. The hint shows the loop; break it at one node. |
|
|
22
|
+
| warning `` `expanded` has no effect with `mode: open` `` | A node limited to `mode: open` cannot start expanded. Use `mode: expand` or `both`, or drop `expanded`. |
|
|
18
23
|
| `Edge id "e" is used twice` | Give edges distinct ids or drop the ids. |
|
|
19
24
|
| `Unknown edge kind "x"` | Use a built-in kind or define it under `edgeKinds:`. |
|
|
20
25
|
| warning `Unknown icon "x"` | `idocs icons search x`, then use the suggested name. |
|
|
@@ -312,6 +312,52 @@
|
|
|
312
312
|
"items": {
|
|
313
313
|
"type": "string"
|
|
314
314
|
}
|
|
315
|
+
},
|
|
316
|
+
"diagram": {
|
|
317
|
+
"description": "Another diagram (its folder name) that shows the inside of this node. The card gets buttons to expand it in place, as a group, or to open it one level deeper, with a way back.",
|
|
318
|
+
"anyOf": [
|
|
319
|
+
{
|
|
320
|
+
"type": "string",
|
|
321
|
+
"minLength": 1
|
|
322
|
+
},
|
|
323
|
+
{
|
|
324
|
+
"type": "object",
|
|
325
|
+
"properties": {
|
|
326
|
+
"name": {
|
|
327
|
+
"type": "string",
|
|
328
|
+
"minLength": 1,
|
|
329
|
+
"description": "Folder name of the diagram, under diagrams/."
|
|
330
|
+
},
|
|
331
|
+
"view": {
|
|
332
|
+
"description": "View to open first. Defaults to the scenario view, then the first.",
|
|
333
|
+
"type": "string",
|
|
334
|
+
"pattern": "^[A-Za-z0-9_.-]+$"
|
|
335
|
+
},
|
|
336
|
+
"scenario": {
|
|
337
|
+
"description": "Scenario to select when the diagram opens.",
|
|
338
|
+
"type": "string",
|
|
339
|
+
"pattern": "^[A-Za-z0-9_.-]+$"
|
|
340
|
+
},
|
|
341
|
+
"mode": {
|
|
342
|
+
"description": "both (default): the reader can expand it in place or open it. expand: only in place. open: only move into it.",
|
|
343
|
+
"type": "string",
|
|
344
|
+
"enum": [
|
|
345
|
+
"both",
|
|
346
|
+
"expand",
|
|
347
|
+
"open"
|
|
348
|
+
]
|
|
349
|
+
},
|
|
350
|
+
"expanded": {
|
|
351
|
+
"description": "Start expanded in place, so the whole inner diagram shows as a group.",
|
|
352
|
+
"type": "boolean"
|
|
353
|
+
}
|
|
354
|
+
},
|
|
355
|
+
"required": [
|
|
356
|
+
"name"
|
|
357
|
+
],
|
|
358
|
+
"additionalProperties": false
|
|
359
|
+
}
|
|
360
|
+
]
|
|
315
361
|
}
|
|
316
362
|
},
|
|
317
363
|
"additionalProperties": false
|
package/template/package.json
CHANGED
|
@@ -14,14 +14,14 @@
|
|
|
14
14
|
"@astrojs/starlight": "^0.42.0",
|
|
15
15
|
"@fontsource/ibm-plex-mono": "^5.3.0",
|
|
16
16
|
"@fontsource/ibm-plex-sans": "^5.3.0",
|
|
17
|
-
"@the-package-labs/idocs-astro": "^0.
|
|
18
|
-
"@the-package-labs/idocs-react": "^0.
|
|
17
|
+
"@the-package-labs/idocs-astro": "^0.4.0",
|
|
18
|
+
"@the-package-labs/idocs-react": "^0.4.0",
|
|
19
19
|
"astro": "^7.0.0",
|
|
20
20
|
"react": "^19.3.0",
|
|
21
21
|
"react-dom": "^19.3.0"
|
|
22
22
|
},
|
|
23
23
|
"devDependencies": {
|
|
24
|
-
"idocs": "^0.
|
|
24
|
+
"@the-package-labs/idocs": "^0.4.0",
|
|
25
25
|
"@types/react": "^19.2.0",
|
|
26
26
|
"@types/react-dom": "^19.2.0"
|
|
27
27
|
},
|