#Sidebars

The Learn site sidebar is autogenerated from the filesystem. Order is driven by sidebar_position frontmatter that ingest assigns from map.yaml traversal order.

#sidebars.js is one line

${NETDATA_REPOS_DIR}/learn/sidebars.js:12-19:

module.exports = { sidebar: [{ "type": "autogenerated", "dirName": "." }] };

Docusaurus walks docs/ and builds the entire sidebar from filesystem structure plus per-file frontmatter. There is NO manual sidebar list.

#Ordering rules

Per Docusaurus, the displayed order in each parent scope is controlled by:

1. Frontmatter sidebar_label -- set by ingest from map.yaml's meta.label.

2. Frontmatter sidebar_position -- set by automate_sidebar_position (ingest.py:2238-2299) and then re-normalized per parent scope by normalize_sidebar_positions_by_parent (ingest.py:425-519). Values are assigned in steps of 10 within each parent scope; map-derived order wins, then alphabetical fallback.

3. _category_.json (Docusaurus convention) -- written by ensure_category_json_for_dirs (ingest.py:336-382) for any subdirectory that contains .mdx files but no overview file. Format: {label, position}. Currently only one in the live tree: docs/Collecting Metrics/OpenTelemetry/_category_.json.

4. Section overview pages -- when a directory has <dir>/<dir>.mdx, it acts as the category landing page (Docusaurus convention) AND is routed to the parent URL via the duplicate-segment slug trim (mapping.md).

5. Auto-generated grid pages -- get_dir_make_file_and_recurse (ingest.py:2333-2510) creates <dir>/<dir>.mdx for any directory that contains integration pages and has no overview file. The generated MDX uses <Grid columns="4"> with <Box ...> children (the Grid_integrations component), and carries learn_status: AUTOGENERATED plus computed slug: and learn_link:.

#Special rule: "Ask Nedi" pinned to position 0

automate_sidebar_position (ingest.py:493-512) forces a top-level page whose sidebar_label is "Ask Nedi" to position 0. The "Ask Nedi" entrypoint is ${NETDATA_REPOS_DIR}/learn/docs/ask-nedi.mdx. Other top-level entries cannot occupy position 0; they get >= 10.

docs/ask-nedi.mdx is the only file currently flagged part_of_learn: True -- meaning it's hand-authored in the learn repo and survives the cleanup step. See authoring-boundary.md.

#Section landing page convention

When a directory has a file matching <dir>/<dir>.mdx:

• Docusaurus treats it as the category landing page.
• add_new_learn_path_key_to_dict (ingest.py:1862-1876) removes the duplicate dir segment from the URL.
• So docs/Collecting Metrics/Collecting Metrics.mdx is routed to /docs/collecting-metrics (parent URL), not /docs/collecting-metrics/collecting-metrics.

This is how every category gets a landing page that displays when the user clicks the parent in the sidebar.

For directories WITHOUT an overview file, a _category_.json is generated to provide a label and position (otherwise Docusaurus uses the directory name verbatim, which often has poor casing/spacing).

#Auto-grid generation

get_dir_make_file_and_recurse (ingest.py:2333-2510) walks docs/ after publication. For directories that contain integration pages (matched by their <!--startmeta blocks) but lack a <dir>/<dir>.mdx overview file:

1. Generate an MDX file with a <Grid_integrations> component listing the integrations in that directory.
2. learn_status: AUTOGENERATED is set in the frontmatter.
3. slug: and learn_link: are computed and injected.

If a directory contains EXACTLY one published integration plus zero non-integration content, the script special-cases that as content-leaf and skips the grid (ingest.py:2429-2503). Adding/removing files can flip a directory between "grid" and "leaf" presentations. See pitfalls-and-gotchas.md.

#Top-level vs nested

There is no structural difference between top-level and nested sections, except for the "Ask Nedi" position-0 rule, which applies only to the root scope. All other scopes are ordered by map traversal first, alphabetical second.

#To reorder the sidebar

You do NOT edit sidebars.js. You reorder the rows in <repo>/docs/.map/map.yaml. Ingest re-runs automate_sidebar_position, which assigns new sidebar_position values. Docusaurus rebuilds with the new order on the next ingest cycle.

#Common mistakes

• Editing sidebars.js directly. The file is one line and not consulted for ordering. Useless.
• Editing _category_.json files in the learn repo. These get overwritten on the next ingest run (safe_cleanup_learn_folders deletes ALL .json files unconditionally -- not just non-part_of_learn ones; see pitfalls-and-gotchas.md). The right fix is to put the page in map.yaml so the sidebar position comes from there.
• Setting sidebar_position: 0 in the source frontmatter. It is overwritten by ingest's automate_sidebar_position. And the value 0 is reserved for "Ask Nedi" at the top level -- any conflict gets re-stamped to >= 10.
• Empty directory expectations. Empty directories disappear from the sidebar (Docusaurus drops them). Removing the last doc in a category removes the category from the sidebar.