@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 124 lines 4.05 KB
Rendered Raw
1 # Recipe: add a new doc page to Learn
2
3 Add a new published page on `learn.netdata.cloud` from the
4 agent repo (this repo) or any of the 6 source repos.
5
6 ## 0. Read first
7
8 - `../SKILL.md` -- skill overview.
9 - `../mapping.md` -- the map.yaml schema and URL computation.
10
11 ## 1. Create the source markdown
12
13 Place the file under a reasonable location in the source repo.
14 Path is largely cosmetic; what matters is the `map.yaml` row.
15
16 For this repo, suggested locations:
17 - `<repo>/docs/<existing-section>/<your-page>.md` for general
18 user-facing docs;
19 - `<repo>/docs/developer-and-contributor-corner/<page>.md` for
20 developer notes;
21 - `<repo>/docs/netdata-agent/<page>.md` for agent docs;
22 - `<repo>/docs/dashboards-and-charts/<page>.md` for dashboard
23 docs.
24
25 Author the markdown content normally. No special frontmatter
26 required; ingest will inject what it needs.
27
28 If you absolutely must pin a stable URL across renames, add
29 `slug: /your/stable/path/here` at the very top of the file
30 (before any HTML-comment metadata block) -- but this is rare
31 and usually unnecessary because the auto-redirect mechanism
32 handles renames.
33
34 ## 2. Add a node to map.yaml
35
36 Open `<repo>/docs/.map/map.yaml` and add a row under the
37 appropriate parent:
38
39 ```yaml
40 - meta:
41 label: My New Page
42 edit_url: https://github.com/netdata/netdata/edit/master/docs/<section>/<your-page>.md
43 description: Optional one-line description for SEO.
44 keywords: [keyword1, keyword2]
45 ```
46
47 The position of the row in the YAML determines the sidebar
48 position within the parent (sibling-relative; ingest assigns
49 `sidebar_position` in steps of 10 in traversal order).
50
51 If you want a single-segment override of the URL slug
52 (different from the label), add `path: <slug>` under the
53 `meta` block.
54
55 ## 3. Test locally
56
57 From the learn repo:
58
59 ```bash
60 cd ${NETDATA_REPOS_DIR}/learn
61 . venv/bin/activate # if not already
62 python3 ingest/ingest.py --local-repo netdata:<repo> \
63 --ignore-on-prem-repo --fail-links-netdata
64 yarn start # browse at http://localhost:3000
65 ```
66
67 Check:
68 - Your new page appears in the sidebar under the expected
69 parent.
70 - The URL is what you expected
71 (`/docs/<learn_rel_path>/<sidebar_label>` lowercased).
72 - Links from / to your page resolve.
73
74 ## 4. Open the docs PR in this repo
75
76 Single PR with two commits (or one):
77 1. The new `.md` file under `<repo>/docs/`.
78 2. The map.yaml change adding the node.
79
80 Reviewers check:
81 - The map.yaml row has all required fields (`label`,
82 `edit_url`).
83 - The `edit_url` matches the schema regex
84 (`^https://github\.com/netdata/<repo>/edit/<branch>/.+\.(md|mdx)$`).
85 - The page is in a sensible parent in the tree.
86
87 ## 5. After merge
88
89 `${NETDATA_REPOS_DIR}/learn/.github/workflows/ingest.yml`
90 fires within 3 hours (or you can `workflow_dispatch` it
91 immediately). Ingest opens an "Ingest New Documentation" PR
92 in the learn repo. A learn-repo maintainer reviews and merges
93 it. Netlify deploys within minutes.
94
95 End-to-end timing: 0-3 hours of cron + manual review/merge +
96 minutes of Netlify deploy.
97
98 ## 6. Verify on production
99
100 After deploy, check:
101 - `https://learn.netdata.cloud/docs/<your-rel-path>/<your-label>`
102 resolves.
103 - The page renders correctly (no MDX errors).
104 - Sidebar position is what you expected.
105 - Page metadata (title, description, keywords) is populated
106 from your `meta` block.
107
108 ## Common mistakes
109
110 - **Forgetting the map.yaml row.** The page won't be
111 published. There's no warning -- ingest silently skips
112 source files not in the map.
113 - **Wrong `edit_url` format.** Schema validation fails the
114 whole ingest run with exit code 2. Check the regex.
115 - **Source path implies the URL.** It does NOT. The URL is
116 computed from `meta.label` + `learn_rel_path`. Don't expect
117 the source filesystem path to influence routing.
118 - **Hand-editing `${NETDATA_REPOS_DIR}/learn/docs/<page>.mdx`
119 directly.** Wiped on next ingest. Use `part_of_learn: True`
120 if you really need a hand-authored exception.
121 - **Wrong source repo for the content.** If your content is
122 about Netdata Cloud On-Prem, edit
123 `${NETDATA_REPOS_DIR}/netdata-cloud-onprem/`, not this repo.
124 But the map.yaml row goes in THIS repo.