ContextQMD
Back to Netdata

How to Publish Docs on Learn

docs/.map/README.md

2.10.36.4 KB
Original Source

How to Publish Docs on Learn

Publishing documentation to Learn involves a few key steps. Follow this guide carefully to avoid broken links or failed builds.

:warning: Before You Begin

  • If you plan to unpublish a file, see Unpublishing Files first. It requires extra steps.
  • If you make large changes or move multiple docs, you must test with a local deployment of Learn.

Steps to Publish

Quick Checklist

StepActionOutput
1Edit map.yaml alongside your doc changes. Update nodes and ordering as needed.Docs mapped with proper sidebar labels, paths, and edit links.
2Test locally with the ingest.py script. Optionally run a full local Learn deployment.Confirms no broken links or build errors.
3Merge the Docs PR (requires approval).Docs + map.yaml merged into the repo.
4Inspect the automatic Learn ingest PR. Check files + deploy preview.Verified preview of Learn with changes.
5Merge the Learn ingest PR.Docs officially live on Learn.

1. Edit map.yaml

All docs must be mapped in the map.yaml file. The file is an ordered navigation tree under the top-level sidebar: key.

Each node is either:

  • A doc node (with a meta object)
  • A category node (with meta + items)
  • An integration placeholder (type: integration_placeholder)

meta fields

FieldPurposeNotes
labelThe label shown in the sidebar.For category overview pages, this should match the sidebar position. Categories are defined by having items.
pathSingle path segment override (optional).Used when the document's Learn path segment differs from the tree structure. Example: OpenTelemetry (not a full path). If omitted, the path is derived from the tree hierarchy.
edit_urlFull GitHub Edit link for the file. Used for the "Edit this page" button.Must use the full link (supports repos beyond netdata/netdata). Can be omitted only for nodes with integration_placeholder children (the integrations themselves will have edit URLs).
keywordsList of keywords for search.Example: ["install", "linux"]
descriptionLegacy metadata description.Rarely used today.

Path Reconstruction

The full Learn path for each document is automatically reconstructed by walking the tree hierarchy and concatenating parent labels. The path field in meta is only needed when a document's path segment differs from its tree position.

For example, a document appearing under "Collecting Metrics" in the sidebar with path: OpenTelemetry will have Learn path OpenTelemetry instead of Collecting Metrics/OpenTelemetry Metrics.

Integration placeholder node

yaml
- type: integration_placeholder
  integration_kind: collectors

Placeholders are positional: the ingest pipeline replaces them in-place with generated integration entries while preserving list order.

Example node

yaml
- meta:
    label: "Linux"
    edit_url: "https://github.com/netdata/netdata/edit/master/docs/installation/linux.md"
    description: "How to install Netdata Agent on Linux"
    keywords:
      - "install"
      - "linux"

2. Test the Changes

Before merging, always test the map file.

  1. Clone Learn locally.

  2. Prepare environment and dependencies (see ingest instructions).

  3. Run the ingest command:

    bash
    python3 ingest/ingest.py --repos OWNEROFREPO/netdata:YOURBRANCH

  4. Inspect the ingested changes.

  5. (Optional, advanced) Deploy Learn locally to confirm it builds correctly.

3. Merge the Docs PR

  • Submit your PR with the updated docs and map.yaml.
  • Get at least one approval.
  • Reviewers expect you to have tested already. Don’t rely on them to test. Please also mention it if you have done testing, so it is clear.

4. Merge the Learn Ingest PR

Once your docs PR is merged:

  1. The ingest action triggers in netdata/learn.
  2. A PR is created automatically.
  3. Inspect the changes.
  4. Wait for the deploy preview.
  5. Check the deploy preview carefully.
  6. If everything looks good → merge.

🍻 Done!

Unpublishing Files

If you delete, move, or unpublish a file, redirects may break.

  1. Open LegacyLearnCorrelateLinksWithGHURLs.json.
  2. Search (Ctrl+F) for the old GitHub link.
  3. Update the entry to a relevant new location.
  4. If no suitable replacement exists → remove the entry.