| 1 | # Recipe: add a new doc page to Learn |
| 2 | |
| 3 | Add a new published page on `learn.netdata.cloud` from the |
| 4 | agent repo (this repo) or any of the 6 source repos. |
| 5 | |
| 6 | ## 0. Read first |
| 7 | |
| 8 | - `../SKILL.md` -- skill overview. |
| 9 | - `../mapping.md` -- the map.yaml schema and URL computation. |
| 10 | |
| 11 | ## 1. Create the source markdown |
| 12 | |
| 13 | Place the file under a reasonable location in the source repo. |
| 14 | Path is largely cosmetic; what matters is the `map.yaml` row. |
| 15 | |
| 16 | For this repo, suggested locations: |
| 17 | - `<repo>/docs/<existing-section>/<your-page>.md` for general |
| 18 | user-facing docs; |
| 19 | - `<repo>/docs/developer-and-contributor-corner/<page>.md` for |
| 20 | developer notes; |
| 21 | - `<repo>/docs/netdata-agent/<page>.md` for agent docs; |
| 22 | - `<repo>/docs/dashboards-and-charts/<page>.md` for dashboard |
| 23 | docs. |
| 24 | |
| 25 | Author the markdown content normally. No special frontmatter |
| 26 | required; ingest will inject what it needs. |
| 27 | |
| 28 | If you absolutely must pin a stable URL across renames, add |
| 29 | `slug: /your/stable/path/here` at the very top of the file |
| 30 | (before any HTML-comment metadata block) -- but this is rare |
| 31 | and usually unnecessary because the auto-redirect mechanism |
| 32 | handles renames. |
| 33 | |
| 34 | ## 2. Add a node to map.yaml |
| 35 | |
| 36 | Open `<repo>/docs/.map/map.yaml` and add a row under the |
| 37 | appropriate parent: |
| 38 | |
| 39 | ```yaml |
| 40 | - meta: |
| 41 | label: My New Page |
| 42 | edit_url: https://github.com/netdata/netdata/edit/master/docs/<section>/<your-page>.md |
| 43 | description: Optional one-line description for SEO. |
| 44 | keywords: [keyword1, keyword2] |
| 45 | ``` |
| 46 | |
| 47 | The position of the row in the YAML determines the sidebar |
| 48 | position within the parent (sibling-relative; ingest assigns |
| 49 | `sidebar_position` in steps of 10 in traversal order). |
| 50 | |
| 51 | If you want a single-segment override of the URL slug |
| 52 | (different from the label), add `path: <slug>` under the |
| 53 | `meta` block. |
| 54 | |
| 55 | ## 3. Test locally |
| 56 | |
| 57 | From the learn repo: |
| 58 | |
| 59 | ```bash |
| 60 | cd ${NETDATA_REPOS_DIR}/learn |
| 61 | . venv/bin/activate # if not already |
| 62 | python3 ingest/ingest.py --local-repo netdata:<repo> \ |
| 63 | --ignore-on-prem-repo --fail-links-netdata |
| 64 | yarn start # browse at http://localhost:3000 |
| 65 | ``` |
| 66 | |
| 67 | Check: |
| 68 | - Your new page appears in the sidebar under the expected |
| 69 | parent. |
| 70 | - The URL is what you expected |
| 71 | (`/docs/<learn_rel_path>/<sidebar_label>` lowercased). |
| 72 | - Links from / to your page resolve. |
| 73 | |
| 74 | ## 4. Open the docs PR in this repo |
| 75 | |
| 76 | Single PR with two commits (or one): |
| 77 | 1. The new `.md` file under `<repo>/docs/`. |
| 78 | 2. The map.yaml change adding the node. |
| 79 | |
| 80 | Reviewers check: |
| 81 | - The map.yaml row has all required fields (`label`, |
| 82 | `edit_url`). |
| 83 | - The `edit_url` matches the schema regex |
| 84 | (`^https://github\.com/netdata/<repo>/edit/<branch>/.+\.(md|mdx)$`). |
| 85 | - The page is in a sensible parent in the tree. |
| 86 | |
| 87 | ## 5. After merge |
| 88 | |
| 89 | `${NETDATA_REPOS_DIR}/learn/.github/workflows/ingest.yml` |
| 90 | fires within 3 hours (or you can `workflow_dispatch` it |
| 91 | immediately). Ingest opens an "Ingest New Documentation" PR |
| 92 | in the learn repo. A learn-repo maintainer reviews and merges |
| 93 | it. Netlify deploys within minutes. |
| 94 | |
| 95 | End-to-end timing: 0-3 hours of cron + manual review/merge + |
| 96 | minutes of Netlify deploy. |
| 97 | |
| 98 | ## 6. Verify on production |
| 99 | |
| 100 | After deploy, check: |
| 101 | - `https://learn.netdata.cloud/docs/<your-rel-path>/<your-label>` |
| 102 | resolves. |
| 103 | - The page renders correctly (no MDX errors). |
| 104 | - Sidebar position is what you expected. |
| 105 | - Page metadata (title, description, keywords) is populated |
| 106 | from your `meta` block. |
| 107 | |
| 108 | ## Common mistakes |
| 109 | |
| 110 | - **Forgetting the map.yaml row.** The page won't be |
| 111 | published. There's no warning -- ingest silently skips |
| 112 | source files not in the map. |
| 113 | - **Wrong `edit_url` format.** Schema validation fails the |
| 114 | whole ingest run with exit code 2. Check the regex. |
| 115 | - **Source path implies the URL.** It does NOT. The URL is |
| 116 | computed from `meta.label` + `learn_rel_path`. Don't expect |
| 117 | the source filesystem path to influence routing. |
| 118 | - **Hand-editing `${NETDATA_REPOS_DIR}/learn/docs/<page>.mdx` |
| 119 | directly.** Wiped on next ingest. Use `part_of_learn: True` |
| 120 | if you really need a hand-authored exception. |
| 121 | - **Wrong source repo for the content.** If your content is |
| 122 | about Netdata Cloud On-Prem, edit |
| 123 | `${NETDATA_REPOS_DIR}/netdata-cloud-onprem/`, not this repo. |
| 124 | But the map.yaml row goes in THIS repo. |