| 1 | # How-tos -- INDEX |
| 2 | |
| 3 | Live catalog of analysis-derived how-tos for the |
| 4 | learn-site-structure skill. |
| 5 | |
| 6 | **Live-catalog rule** (also stated in `../SKILL.md` and |
| 7 | `../recipes/INDEX.md`): if an assistant is asked a concrete |
| 8 | question about how a Learn page is produced that requires |
| 9 | non-trivial analysis (multiple file reads, running ingest |
| 10 | locally, cross-referencing this repo's `map.yaml` with the |
| 11 | learn-repo output) AND the answer is not already documented |
| 12 | under one of the per-domain guides |
| 13 | (`../mapping.md`, `../pipeline.md`, `../sidebars.md`, |
| 14 | `../mdx-rules.md`, `../redirects.md`, |
| 15 | `../pitfalls-and-gotchas.md`, `../authoring-boundary.md`) or |
| 16 | the recipes (`../recipes/`), the assistant MUST author a new |
| 17 | `how-tos/<slug>.md` and add a one-line entry to this INDEX |
| 18 | BEFORE completing the task. |
| 19 | |
| 20 | This is a durable rule. Skipping it means the next assistant |
| 21 | repeats the same analysis from scratch -- a framework |
| 22 | violation. |
| 23 | |
| 24 | ## Catalog |
| 25 | |
| 26 | | Topic | Slug | Notes | |
| 27 | |---|---|---| |
| 28 | | Preview a documentation PR locally | `preview-documentation-pr-locally.md` | Isolated Learn ingest/build/browser inspection from PR source content before merge. | |
| 29 | |
| 30 | ## How to add a how-to |
| 31 | |
| 32 | 1. Create `how-tos/<slug>.md` with: |
| 33 | - A one-line summary at the top (the question being |
| 34 | answered). |
| 35 | - The answer with file:line citations into this repo or |
| 36 | the learn repo (`${NETDATA_REPOS_DIR}/learn/...`). |
| 37 | - A "How I figured this out" footer naming the files |
| 38 | read and the commands run, so the next assistant can |
| 39 | verify or extend. |
| 40 | 2. Add a row to the table above with topic, slug, and short |
| 41 | notes. |
| 42 | 3. Commit alongside the work that prompted the analysis. |
| 43 | |
| 44 | ## When NOT to add a how-to |
| 45 | |
| 46 | - The question is already covered by an existing per-domain |
| 47 | guide or recipe -- update that guide instead. |
| 48 | - The answer is a one-liner that doesn't require analysis. |
| 49 | - The answer is highly speculative or version-specific. |