| 1 | # Recipes -- INDEX |
| 2 | |
| 3 | Step-by-step recipes for the most common tasks an author / |
| 4 | maintainer performs against the Learn site. |
| 5 | |
| 6 | | Recipe | When to use | |
| 7 | |---|---| |
| 8 | | `add-doc-page.md` | Adding a brand-new page to Learn. | |
| 9 | | `move-doc-page.md` | Moving a page to a different sidebar location (different parent). | |
| 10 | | `rename-doc-page.md` | Renaming a page (changes URL slug). | |
| 11 | | `delete-doc-page.md` | Unpublishing a page. The only recipe that requires manual surgery. | |
| 12 | |
| 13 | ## Common preamble for all recipes |
| 14 | |
| 15 | Every recipe assumes the source repo (almost always |
| 16 | `netdata/netdata`, this repo) is your edit target. The map |
| 17 | file `<repo>/docs/.map/map.yaml` is the lever. |
| 18 | |
| 19 | ### Quick mental model |
| 20 | |
| 21 | 1. **What changes appears on Learn:** anything you add to / |
| 22 | modify in / remove from `<repo>/docs/.map/map.yaml`, |
| 23 | plus the corresponding `.md` files in source repos. |
| 24 | 2. **When changes appear:** ingest CI runs every 3 hours |
| 25 | (cron) plus on push to learn-repo master plus on manual |
| 26 | dispatch. So after merging your docs PR to |
| 27 | `netdata/netdata` master, expect a 0-3-hour delay before |
| 28 | the ingest PR opens in the learn repo. |
| 29 | 3. **Maintainer step in learn repo:** review and merge the |
| 30 | auto-opened "Ingest New Documentation" PR. Netlify |
| 31 | deploys within minutes. |
| 32 | |
| 33 | ### Test locally before pushing |
| 34 | |
| 35 | The cheapest way to verify your `map.yaml` change works: |
| 36 | |
| 37 | ```bash |
| 38 | cd ${NETDATA_REPOS_DIR}/learn |
| 39 | |
| 40 | # Set up venv once. |
| 41 | python3 -m venv venv && . venv/bin/activate |
| 42 | pip install -r .learn_environment/ingest-requirements.txt |
| 43 | |
| 44 | # Test against your local netdata clone. |
| 45 | python3 ingest/ingest.py --local-repo netdata:<repo> \ |
| 46 | --ignore-on-prem-repo --fail-links-netdata |
| 47 | ``` |
| 48 | |
| 49 | After ingest produces output in |
| 50 | `${NETDATA_REPOS_DIR}/learn/docs/`, browse it with the dev |
| 51 | server: |
| 52 | |
| 53 | ```bash |
| 54 | cd ${NETDATA_REPOS_DIR}/learn |
| 55 | yarn start # runs Docusaurus dev server, opens browser |
| 56 | ``` |
| 57 | |
| 58 | ## When in doubt |
| 59 | |
| 60 | 1. Read `../mapping.md` for the source-to-URL computation. |
| 61 | 2. Read `../pipeline.md` for what runs in CI. |
| 62 | 3. Read `../authoring-boundary.md` to confirm where to edit. |
| 63 | 4. Read `../pitfalls-and-gotchas.md` BEFORE assuming the |
| 64 | pipeline does the obvious thing. |
| 65 | 5. If you encountered a question that this catalog doesn't |
| 66 | cover and you had to investigate to answer it, AUTHOR a |
| 67 | how-to under `../how-tos/<slug>.md` and add it to |
| 68 | `../how-tos/INDEX.md`. This rule is mandatory; see |
| 69 | `../SKILL.md` "Live how-to rule". |