netdata/netdata

docs-learn-site-structure

Change, review or troubleshoot Learn publication, docs/.map mapping, page URLs, redirects, sidebars, MDX and ingest/CI behavior.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. 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-structure

Before 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.
Original skill document

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

OwnerWhat it decides
docs/.map/README.md#steps-to-publishthe publish and unpublish procedure, meta fields, path reconstruction, the placeholder node, the local test command
docs/.map/map.schema.jsonnode shapes, required fields, the edit_url pattern, the integration_kind members
docs/.map/validate_map_schema.pythe 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.ymlwhich pushes to master here dispatch the learn ingest
.github/workflows/check-markdown.ymlthe 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.mdeverything 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-alternativeshow 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

TaskRead
review a page, mapping or pipeline changethe 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.yaml must validate against docs/.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 a netdata/netdata edit_url that 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.yml on the PR here, and the

learn ingest under --fail-links (./pipeline.md#verification-before-merging-here).

  • Every .md and .mdx under learn docs/ without part_of_learn: True, and every .json unconditionally, 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.yaml node with label and edit_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_url unchanged 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_source without colliding with a

sibling (./mapping.md#file-path-and-slug).

  • Cross-references are repository-relative .md paths, never learn.netdata.cloud URLs

(./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.

from this repository

More skills

All skills
netdata
Community

collectors-authoring

Author, modify, or review Netdata collectors across Go, IBM, C, Rust and external plugins. Start here for collector lifecycle, metric identity, missing data, cost, cardinality, SNMP/Prometheus profiles, statsd, logs, topology, flow/OTEL ingestion and Functions. Routes to domain and framework guidance. Operator queries use the query skills.

1h installs
2
GitHub stars
81.3K
Updated
Nov 4
netdata
Community

collectors-go-design

Design or review go.d collector and discoverer contracts, including capability scope, options, metric meaning and identity, vnodes, Functions, ownership, remote writes and durable state. Also author or review DynCfg configschema.json forms. Contract-preserving fixes and migrations use framework guidance; integration prose uses the metadata skill.

1h installs
2
GitHub stars
81.3K
Updated
Nov 4
netdata
Community

collectors-go-framework-v2

Implement, migrate or review Go go.d framework V2 collectors, CollectorV2 lifecycle, metrix metric stores, charts.yaml authoring (defaults, families, ordering, statesets, labels), charttpl/chartengine, Functions and host scopes/vnodes. Use affected contracts and source owners; collector product/config design uses collectors-go-design.

1h installs
2
GitHub stars
81.3K
Updated
Nov 4
netdata
Community

collectors-metadata-yaml

Write, review, or explain collector metadata.yaml content and integration-page wording across collector families, including ibm.d docgen sources. Use for field meaning, readability, defaults, discovery, permissions, costs, metrics, setup, and alerts. Generator mechanics belong to integrations-lifecycle; DynCfg form wording belongs to collectors-go-design/config-schema.md.

1h installs
2
GitHub stars
81.3K
Updated
Nov 4