Authoring boundary

Where do you EDIT a doc to make it appear on Learn? It depends. This guide draws the boundary between content owned by ingest (do NOT edit in the learn repo) and content hand-authored directly in the learn repo.

Owned by ingest -- DO NOT edit in the learn repo

The cleanup step at ingest.py:1038-1064 walks ${NETDATA_REPOS_DIR}/learn/docs/ and removes every .md / .mdx / .json that does NOT carry part_of_learn: True. Anything in docs/ is wiped and regenerated each run, EXCEPT files explicitly marked as hand-authored.

Specifically:

• ${NETDATA_REPOS_DIR}/learn/docs/** -- every file except those marked part_of_learn: True. Currently only ${NETDATA_REPOS_DIR}/learn/docs/ask-nedi.mdx is so flagged.

• ${NETDATA_REPOS_DIR}/learn/netlify.toml -- fully regenerated by autogenerateRedirects.main (ingest.py:2932). Hand edits are overwritten.

• ${NETDATA_REPOS_DIR}/learn/LegacyLearnCorrelateLinksWithGHURLs.json -- appended to on each run. Hand edits to existing entries ARE preserved (because they're values in a dict that gets read and re-emitted), but new entries get added each ingest. This is the file you DO edit for manual unpublish surgery (see redirects.md).

• ${NETDATA_REPOS_DIR}/learn/ingest/generated_map.yaml -- recomputed each run; committed for diff visibility.

• ${NETDATA_REPOS_DIR}/learn/ingest/one_commit_back_file-dict.yaml -- written each run as the next run's diff baseline.

Hand-authored in the learn repo -- safe to edit

These files live in the learn repo and are the maintainer's responsibility:

• ${NETDATA_REPOS_DIR}/learn/docusaurus.config.js -- site config, plugins, theme.
• ${NETDATA_REPOS_DIR}/learn/sidebars.js -- one-line autogen config.
• ${NETDATA_REPOS_DIR}/learn/babel.config.js, ${NETDATA_REPOS_DIR}/learn/tailwind.config.js, ${NETDATA_REPOS_DIR}/learn/postcss.config.js -- build config.
• ${NETDATA_REPOS_DIR}/learn/static.toml -- the static section of redirects (gets copied verbatim into netlify.toml).
• ${NETDATA_REPOS_DIR}/learn/docs/ask-nedi.mdx -- the only hand-authored page in docs/ (carries part_of_learn: True).
• ${NETDATA_REPOS_DIR}/learn/src/** -- React pages, components, theme overrides, css, custom Docusaurus plugins.
• ${NETDATA_REPOS_DIR}/learn/static/** -- favicons, fonts, Swagger UI, robots.txt, ahrefs verification, etc.
• ${NETDATA_REPOS_DIR}/learn/ingest/ingest.py and the ingest helpers (ingest/autogenerateRedirects.py, ingest/autogenerateSupportedIntegrationsPage.py, ingest/check_learn_links.py).
• ${NETDATA_REPOS_DIR}/learn/versioning/remove_edit_links.py -- manual versioning helper.
• ${NETDATA_REPOS_DIR}/learn/package.json, ${NETDATA_REPOS_DIR}/learn/yarn.lock, ${NETDATA_REPOS_DIR}/learn/vitest.config.js.
• ${NETDATA_REPOS_DIR}/learn/.github/** -- workflows.
• ${NETDATA_REPOS_DIR}/learn/LegacyLearnCorrelateLinksWithGHURLs.json -- specifically for manual unpublish surgery, per <repo>/docs/.map/README.md:96-104.

Source repos -- this is where most authoring happens

For documentation content, edits go in the SOURCE repo (almost always netdata/netdata, this repo). Specifically:

• Doc body: <repo>/docs/<...>/<file>.md. Path is largely cosmetic; what matters is the entry in map.yaml.
• Map: <repo>/docs/.map/map.yaml. Required for publication.
• README files for collectors: NOT hand-edited. They are generated by the integrations pipeline (see the integrations-lifecycle skill) and copied into the learn tree by ingest's integration-placeholder mechanism.

What if I want a page that LIVES in the learn repo?

Set part_of_learn: True in the page's frontmatter. The cleanup step at ingest.py:1038-1064 will preserve it on every ingest run. Currently docs/ask-nedi.mdx is the only page using this flag.

This is the right answer for:

• Pages that don't have a natural home in any source repo (e.g. site-meta pages, "About" pages, the home page).
• Highly-customized pages with React components that don't belong in a markdown source.

Cross-repo authoring

Pages published from non-netdata/netdata source repos:

Source repo	What lives there	Edit-flow
netdata/netdata	Most docs and integration metadata	This repo (you're here).
netdata/netdata-cloud-onprem	On-prem doc pages	Edit there; ingest pulls into Netdata Cloud On-Prem category.
netdata/.github	CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md	Edit there. Branch is main, not master.
netdata/agent-service-discovery	Service-discovery docs	Edit there.
netdata/netdata-grafana-datasource-plugin	Grafana datasource docs	Edit there.
netdata/helmchart	Kubernetes Helm chart docs	Edit there.

For each: the source repo's docs need a corresponding entry in <repo>/docs/.map/map.yaml (in this repo) -- the map is cross-repo even though it lives in netdata/netdata. Adding or moving a page in a different source repo still requires a map.yaml change in this repo.

Decision tree: where to edit

Question: I want to edit/add a page. Where?

1. Is it an integration page? (<plugin-dir>/integrations/<slug>.md or a notification README under src/health/notifications/...) -> NO, it's generated. Edit the source metadata.yaml and re-run the integrations pipeline (see the integrations-lifecycle skill).

2. Is it a doc page in this repo's <repo>/docs/? -> Edit the .md file directly in this repo. If it's a new file, add a row to <repo>/docs/.map/map.yaml. If it already has a row in map.yaml, no map change needed unless you're moving / renaming.

3. Is it the Ask Nedi entrypoint? -> Edit ${NETDATA_REPOS_DIR}/learn/docs/ask-nedi.mdx directly. It's part_of_learn: True and survives ingest.

4. Is it from a sibling Netdata-org repo (cloud-onprem, .github, agent-service-discovery, grafana-datasource, helmchart)? -> Edit the file in that repo. Then ensure <repo>/docs/.map/map.yaml has a corresponding row (in THIS repo, even though the source is elsewhere).

5. Is it a styling/UI/build/redirect change? -> Edit in the learn repo (docusaurus.config.js, tailwind.config.js, static.toml, src/, static/).

6. Is it a sidebar reorder? -> Edit <repo>/docs/.map/map.yaml in THIS repo. Reorder the rows. The sidebar autogeneration follows map traversal order.

Anti-patterns to flag in review

• Editing ${NETDATA_REPOS_DIR}/learn/docs/<page>.mdx without part_of_learn: True. Will be wiped on next ingest. The right fix is to edit the source .md in the appropriate repo and ensure map.yaml references it.
• Editing netlify.toml directly. Regenerated each ingest. Edit static.toml for static redirects, or rely on the auto-redirect mechanism (move/rename in map.yaml).
• Editing sidebars.js. It's one line. Useless. Edit map.yaml to reorder.
• Editing _category_.json files in the learn repo. They are wiped each ingest by safe_cleanup_learn_folders. Either set the page in map.yaml so the position comes from there, or pre-author the _category_.json in the source repo and arrange for ingest to copy it (currently no such mechanism; needs feature work).
• Editing LegacyLearnCorrelateLinksWithGHURLs.json for anything OTHER than manual unpublish surgery. Existing entries are stable across ingest runs, but the maintainer who added the entry is responsible for it.
• Editing ingest.js or ingest.md. Both are LEGACY. The live orchestrator is ingest/ingest.py. See pitfalls-and-gotchas.md.