Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/netdata/netdata --skill docs-learn-site-structureAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
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.

