How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/netdata/netdata --skill docs-learn-site-structureBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Learn site structure
A page on learn.netdata.cloud is a node in this repository's docs/.map/map.yaml, rendered by the ingest of the netdata/learn repository into a Docusaurus site that Netlify deploys. This skill states what an author or reviewer here relies on; the how-to-publish procedure is docs/.map/README.md, and the mechanics live in the learn repository.
Apply AGENTS.md#skill-selection. Review the affected publication contract and existing evidence; recipe instructions do not require a new SOW or authorize deletion, publication, ingest or a local preview. Use the task and symptom routes below, including their dependencies when a change reaches another surface.
Learn-side facts carry the revision at which they were checked. Before relying on a claim affected by the task, inspect that contract at the relevant available Learn revision and report any evidence gap. repo-mirror-sources supplies the read-only checkout/revision workflow; loading this skill does not request a mirror refresh.
Owners
| Owner | What it decides |
|---|---|
docs/.map/README.md#steps-to-publish | the publish and unpublish procedure, meta fields, path reconstruction, the placeholder node, the local test command |
docs/.map/map.schema.json | node shapes, required fields, the edit_url pattern, the integration_kind members |
docs/.map/validate_map_schema.py | the three custom map rules (no duplicate edit_url; a leaf needs an edit_url; a netdata/netdata edit_url names an existing file) |
.github/workflows/trigger-learn-update.yml | which pushes to master here dispatch the learn ingest |
.github/workflows/check-markdown.yml | the PR gate here that regenerates integrations, runs the map validator, and runs the real ingest with --fail-links-netdata |
netdata/learn: ingest/ingest.py, ingest/autogenerateRedirects.py, static.toml, .github/workflows/ingest.yml, README.md, AGENTS.md | everything the site does with a mapped file; facts in this skill are verified against netdata/learn @ c3a16edd5ee4dc819976ef162c9afaff4b9b968c and cite the symbol, never a line |
.agents/sensitive-data-discipline.md#allowed-alternatives | how paths into the learn repository are written in committed text (${NETDATA_REPOS_DIR}/learn/...; .agents/ENV.md documents the key) |
Sibling skills: integrations-lifecycle produces the integration pages that ingest splices in through placeholders; collectors-metadata-yaml owns the author-side MDX safety rules for metadata.yaml text; docs-learn-pr-preview builds the site locally from a PR and loads this skill first; repo-mirror-sources maintains the checkout under ${NETDATA_REPOS_DIR} that the learn paths refer to.
Tasks
| Task | Read |
|---|---|
| review a page, mapping or pipeline change | the affected task/symptom references below and current owner evidence; no recipe execution solely for review |
| add a page | ./recipes/add-doc-page.md, then ./mapping.md |
| move a page to another section | ./recipes/move-doc-page.md, ./redirects.md |
| rename a page (label or URL) | ./recipes/rename-doc-page.md, ./mapping.md#file-path-and-slug |
| delete or unpublish a page | ./recipes/delete-doc-page.md, docs/.map/README.md#unpublishing-files |
| decide where an edit belongs | ./authoring-boundary.md |
| understand or debug what ran in CI | ./pipeline.md |
| a mapped page renders empty | ./how-tos/repairing-empty-mapped-pages.md |
| links from integration descriptions to Learn | ./how-tos/integration-card-description-links.md |
Symptom to file: page missing on Learn or URL not what was expected: ./mapping.md#the-join-key; ingest exited 2 or the map validator failed: ./mapping.md#what-is-checked-and-by-what; exited 3: ./redirects.md; traceback naming resolve_publish_path_collisions or populate_integrations: ./mapping.md; MDX build error or a page cut off: ./mdx-rules.md; sidebar order, missing category, or a grid that turned into a page: ./sidebars.md; old URL 404 or redirect loop: ./redirects.md; a change vanished from docs/ in the learn repository: ./authoring-boundary.md.
Rules
Enforced by code (the file names the tool and the effect):
map.yamlmust validate againstdocs/.map/map.schema.json; ingest exits 2 otherwise
(./mapping.md#what-is-checked-and-by-what).
- A duplicate
edit_url, a leaf without one, or anetdata/netdataedit_urlthat names no file fails
docs/.map/validate_map_schema.py, which .github/workflows/check-markdown.yml runs after generating the integration pages; run it before opening a map PR (./mapping.md#what-is-checked-and-by-what).
- A published path or slug collision that involves a non-integration page aborts ingest (
ValueError);
integration duplicates are suffixed automatically (./mapping.md#file-path-and-slug).
- A redirect catalogue entry that resolves to nothing and is neither covered nor retired aborts ingest with exit 3
(./redirects.md).
- A broken link or anchor in a mapped page fails
.github/workflows/check-markdown.ymlon the PR here, and the
learn ingest under --fail-links (./pipeline.md#verification-before-merging-here).
- Every
.mdand.mdxunder learndocs/withoutpart_of_learn: True, and every.jsonunconditionally, is
deleted at the start of each full ingest (./authoring-boundary.md).
Hand-reviewed, because no code checks them:
- Every published page has a
map.yamlnode withlabelandedit_url; a file without a node is silently skipped,
and a node of another repository whose URL matches no file is silently unpublished (./mapping.md#the-join-key).
- Keep
edit_urlunchanged when moving a page; the redirect catalogue is anchored to it (./redirects.md). - A label decides the URL; choose labels that survive
_sanitize_mdx_filename_sourcewithout colliding with a
sibling (./mapping.md#file-path-and-slug).
- Cross-references are repository-relative
.mdpaths, neverlearn.netdata.cloudURLs
(./mapping.md#links-between-pages).
- Text that MDX reads as a tag (
<word>,<before a digit, generics) is wrapped in inline code or rephrased
(./mdx-rules.md).
- Learn paths in committed text use the
${NETDATA_REPOS_DIR}/learn/...form; facts about learn code carry the
owner/repo @ commit they were verified against.

