| 1 | # Authoring boundary |
| 2 | |
| 3 | Where do you EDIT a doc to make it appear on Learn? It depends. |
| 4 | This guide draws the boundary between content owned by ingest |
| 5 | (do NOT edit in the learn repo) and content hand-authored |
| 6 | directly in the learn repo. |
| 7 | |
| 8 | ## Owned by ingest -- DO NOT edit in the learn repo |
| 9 | |
| 10 | The cleanup step at `ingest.py:1038-1064` walks |
| 11 | `${NETDATA_REPOS_DIR}/learn/docs/` and removes every |
| 12 | `.md` / `.mdx` / `.json` that does NOT carry |
| 13 | `part_of_learn: True`. Anything in `docs/` is wiped and |
| 14 | regenerated each run, EXCEPT files explicitly marked as |
| 15 | hand-authored. |
| 16 | |
| 17 | Specifically: |
| 18 | |
| 19 | - `${NETDATA_REPOS_DIR}/learn/docs/**` -- every file except |
| 20 | those marked `part_of_learn: True`. Currently only |
| 21 | `${NETDATA_REPOS_DIR}/learn/docs/ask-nedi.mdx` is so |
| 22 | flagged. |
| 23 | |
| 24 | - `${NETDATA_REPOS_DIR}/learn/netlify.toml` -- fully |
| 25 | regenerated by `autogenerateRedirects.main` |
| 26 | (`ingest.py:2932`). Hand edits are overwritten. |
| 27 | |
| 28 | - `${NETDATA_REPOS_DIR}/learn/LegacyLearnCorrelateLinksWithGHURLs.json` |
| 29 | -- appended to on each run. Hand edits to existing entries |
| 30 | ARE preserved (because they're values in a dict that gets |
| 31 | read and re-emitted), but new entries get added each ingest. |
| 32 | This is the file you DO edit for manual unpublish surgery |
| 33 | (see `redirects.md`). |
| 34 | |
| 35 | - `${NETDATA_REPOS_DIR}/learn/ingest/generated_map.yaml` -- |
| 36 | recomputed each run; committed for diff visibility. |
| 37 | |
| 38 | - `${NETDATA_REPOS_DIR}/learn/ingest/one_commit_back_file-dict.yaml` |
| 39 | -- written each run as the next run's diff baseline. |
| 40 | |
| 41 | ## Hand-authored in the learn repo -- safe to edit |
| 42 | |
| 43 | These files live in the learn repo and are the maintainer's |
| 44 | responsibility: |
| 45 | |
| 46 | - `${NETDATA_REPOS_DIR}/learn/docusaurus.config.js` -- site |
| 47 | config, plugins, theme. |
| 48 | - `${NETDATA_REPOS_DIR}/learn/sidebars.js` -- one-line |
| 49 | autogen config. |
| 50 | - `${NETDATA_REPOS_DIR}/learn/babel.config.js`, |
| 51 | `${NETDATA_REPOS_DIR}/learn/tailwind.config.js`, |
| 52 | `${NETDATA_REPOS_DIR}/learn/postcss.config.js` -- build |
| 53 | config. |
| 54 | - `${NETDATA_REPOS_DIR}/learn/static.toml` -- the static |
| 55 | section of redirects (gets copied verbatim into |
| 56 | `netlify.toml`). |
| 57 | - `${NETDATA_REPOS_DIR}/learn/docs/ask-nedi.mdx` -- the only |
| 58 | hand-authored page in `docs/` (carries `part_of_learn: True`). |
| 59 | - `${NETDATA_REPOS_DIR}/learn/src/**` -- React pages, |
| 60 | components, theme overrides, css, custom Docusaurus plugins. |
| 61 | - `${NETDATA_REPOS_DIR}/learn/static/**` -- favicons, fonts, |
| 62 | Swagger UI, robots.txt, ahrefs verification, etc. |
| 63 | - `${NETDATA_REPOS_DIR}/learn/ingest/ingest.py` and the ingest |
| 64 | helpers (`ingest/autogenerateRedirects.py`, |
| 65 | `ingest/autogenerateSupportedIntegrationsPage.py`, |
| 66 | `ingest/check_learn_links.py`). |
| 67 | - `${NETDATA_REPOS_DIR}/learn/versioning/remove_edit_links.py` |
| 68 | -- manual versioning helper. |
| 69 | - `${NETDATA_REPOS_DIR}/learn/package.json`, |
| 70 | `${NETDATA_REPOS_DIR}/learn/yarn.lock`, |
| 71 | `${NETDATA_REPOS_DIR}/learn/vitest.config.js`. |
| 72 | - `${NETDATA_REPOS_DIR}/learn/.github/**` -- workflows. |
| 73 | - `${NETDATA_REPOS_DIR}/learn/LegacyLearnCorrelateLinksWithGHURLs.json` |
| 74 | -- specifically for **manual unpublish surgery**, per |
| 75 | `<repo>/docs/.map/README.md:96-104`. |
| 76 | |
| 77 | ## Source repos -- this is where most authoring happens |
| 78 | |
| 79 | For documentation content, edits go in the SOURCE repo (almost |
| 80 | always `netdata/netdata`, this repo). Specifically: |
| 81 | |
| 82 | - **Doc body**: `<repo>/docs/<...>/<file>.md`. Path is |
| 83 | largely cosmetic; what matters is the entry in |
| 84 | `map.yaml`. |
| 85 | - **Map**: `<repo>/docs/.map/map.yaml`. Required for |
| 86 | publication. |
| 87 | - **README files for collectors**: NOT hand-edited. They are |
| 88 | generated by the integrations pipeline (see the |
| 89 | `integrations-lifecycle` skill) and copied into the learn |
| 90 | tree by ingest's integration-placeholder mechanism. |
| 91 | |
| 92 | ## What if I want a page that LIVES in the learn repo? |
| 93 | |
| 94 | Set `part_of_learn: True` in the page's frontmatter. The |
| 95 | cleanup step at `ingest.py:1038-1064` will preserve it on |
| 96 | every ingest run. Currently `docs/ask-nedi.mdx` is the only |
| 97 | page using this flag. |
| 98 | |
| 99 | This is the right answer for: |
| 100 | - Pages that don't have a natural home in any source repo |
| 101 | (e.g. site-meta pages, "About" pages, the home page). |
| 102 | - Highly-customized pages with React components that don't |
| 103 | belong in a markdown source. |
| 104 | |
| 105 | ## Cross-repo authoring |
| 106 | |
| 107 | Pages published from non-`netdata/netdata` source repos: |
| 108 | |
| 109 | | Source repo | What lives there | Edit-flow | |
| 110 | |---|---|---| |
| 111 | | `netdata/netdata` | Most docs and integration metadata | This repo (you're here). | |
| 112 | | `netdata/netdata-cloud-onprem` | On-prem doc pages | Edit there; ingest pulls into `Netdata Cloud On-Prem` category. | |
| 113 | | `netdata/.github` | `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md` | Edit there. Branch is `main`, not `master`. | |
| 114 | | `netdata/agent-service-discovery` | Service-discovery docs | Edit there. | |
| 115 | | `netdata/netdata-grafana-datasource-plugin` | Grafana datasource docs | Edit there. | |
| 116 | | `netdata/helmchart` | Kubernetes Helm chart docs | Edit there. | |
| 117 | |
| 118 | For each: the source repo's docs need a corresponding entry in |
| 119 | `<repo>/docs/.map/map.yaml` (in this repo) -- the map is |
| 120 | cross-repo even though it lives in `netdata/netdata`. Adding |
| 121 | or moving a page in a different source repo still requires a |
| 122 | map.yaml change in this repo. |
| 123 | |
| 124 | ## Decision tree: where to edit |
| 125 | |
| 126 | Question: I want to edit/add a page. Where? |
| 127 | |
| 128 | 1. **Is it an integration page?** (`<plugin-dir>/integrations/<slug>.md` |
| 129 | or a notification README under |
| 130 | `src/health/notifications/...`) |
| 131 | -> NO, it's generated. Edit the source `metadata.yaml` and |
| 132 | re-run the integrations pipeline (see the |
| 133 | `integrations-lifecycle` skill). |
| 134 | |
| 135 | 2. **Is it a doc page in this repo's `<repo>/docs/`?** |
| 136 | -> Edit the `.md` file directly in this repo. If it's a new |
| 137 | file, add a row to `<repo>/docs/.map/map.yaml`. If it |
| 138 | already has a row in map.yaml, no map change needed unless |
| 139 | you're moving / renaming. |
| 140 | |
| 141 | 3. **Is it the Ask Nedi entrypoint?** |
| 142 | -> Edit `${NETDATA_REPOS_DIR}/learn/docs/ask-nedi.mdx` |
| 143 | directly. It's `part_of_learn: True` and survives |
| 144 | ingest. |
| 145 | |
| 146 | 4. **Is it from a sibling Netdata-org repo (cloud-onprem, |
| 147 | .github, agent-service-discovery, grafana-datasource, |
| 148 | helmchart)?** |
| 149 | -> Edit the file in that repo. Then ensure |
| 150 | `<repo>/docs/.map/map.yaml` has a corresponding row (in |
| 151 | THIS repo, even though the source is elsewhere). |
| 152 | |
| 153 | 5. **Is it a styling/UI/build/redirect change?** |
| 154 | -> Edit in the learn repo (`docusaurus.config.js`, |
| 155 | `tailwind.config.js`, `static.toml`, `src/`, `static/`). |
| 156 | |
| 157 | 6. **Is it a sidebar reorder?** |
| 158 | -> Edit `<repo>/docs/.map/map.yaml` in THIS repo. Reorder |
| 159 | the rows. The sidebar autogeneration follows map traversal |
| 160 | order. |
| 161 | |
| 162 | ## Anti-patterns to flag in review |
| 163 | |
| 164 | - **Editing `${NETDATA_REPOS_DIR}/learn/docs/<page>.mdx` |
| 165 | without `part_of_learn: True`.** Will be wiped on next |
| 166 | ingest. The right fix is to edit the source `.md` in the |
| 167 | appropriate repo and ensure `map.yaml` references it. |
| 168 | - **Editing `netlify.toml` directly.** Regenerated each |
| 169 | ingest. Edit `static.toml` for static redirects, or rely on |
| 170 | the auto-redirect mechanism (move/rename in `map.yaml`). |
| 171 | - **Editing `sidebars.js`.** It's one line. Useless. Edit |
| 172 | `map.yaml` to reorder. |
| 173 | - **Editing `_category_.json` files in the learn repo.** They |
| 174 | are wiped each ingest by `safe_cleanup_learn_folders`. |
| 175 | Either set the page in `map.yaml` so the position comes |
| 176 | from there, or pre-author the `_category_.json` in the |
| 177 | source repo and arrange for ingest to copy it (currently |
| 178 | no such mechanism; needs feature work). |
| 179 | - **Editing `LegacyLearnCorrelateLinksWithGHURLs.json` for |
| 180 | anything OTHER than manual unpublish surgery.** Existing |
| 181 | entries are stable across ingest runs, but the maintainer |
| 182 | who added the entry is responsible for it. |
| 183 | - **Editing `ingest.js` or `ingest.md`.** Both are LEGACY. |
| 184 | The live orchestrator is `ingest/ingest.py`. See |
| 185 | `pitfalls-and-gotchas.md`. |