# 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`.
