@cryptotaxi247 / netdata-1 / commits / 642c28544

Enhance README with publishing instructions for docs (#20952)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: ilyam8 <ilya@netdata.cloud>

Fotis Voutsas committed Sep 17, 2025 at 09:07 UTC 642c2854497e0d218ef962f742a5ea0fac868580
1 file changed +69 -12
docs/.map/README.md
+69 -12
@@ -1,23 +1,80 @@
1 -# map.csv
1 +# How to Publish Docs on Learn
2
3 -This is the map that Learn uses to properly arrange files.
3 +Publishing documentation to [Learn](https://github.com/netdata/learn) involves a few key steps. Follow this guide carefully to avoid broken links or failed builds.
4
5 -## custom_edit_url
5 +:warning: **Before You Begin**
6
7 -This column has the link for the github file you want to use, due to having files from other repos apart from netdata/netdata, use full **EDIT** link here. This link will be used when someone presses the edit button on Learn.
7 +- If you plan to unpublish a file, see [Unpublishing Files](#unpublishing-files) first. It requires extra steps.
8 +- If you make large changes or move multiple docs, you must test with a local deployment of Learn.
9
9 -## sidebar_Label
10 +## Steps to Publish
11
11 -The label that the doc will have on the sidebar.
12 +### Quick Checklist
13
13 -## learn_status
14 +| Step | Action | Output |
15 +|-------|-----------------------------------------------------------------------------------------|----------------------------------------------------------------|
16 +| **1** | Edit `map.csv` alongside your doc changes. Fill in all 4 columns (description can be left empty) correctly. | Docs mapped with proper sidebar labels, paths, and edit links. |
17 +| **2** | Test locally with the `ingest.py` script. Optionally run a full local Learn deployment. | Confirms no broken links or build errors. |
18 +| **3** | Merge the Docs PR (requires approval). | Docs + `map.csv` merged into the repo. |
19 +| **4** | Inspect the automatic Learn ingest PR. Check files + deploy preview. | Verified preview of Learn with changes. |
20 +| **5** | Merge the Learn ingest PR. | Docs officially live on Learn. |
21
15 -`Published` or `Unpublished`.
22 +### 1. Edit `map.csv`
23
17 -## learn_rel_path
24 +All docs must be mapped in the [map.csv](https://github.com/netdata/netdata/blob/master/docs/.map/map.csv) file. Each row has five columns:
25
19 -This is the path that the file must go to, use uppercase letters, spaces and separate with slashes.
26 +| Column | Purpose | Notes |
27 +|-----------------------|-------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
28 +| **custom\_edit\_url** | Full GitHub **Edit** link for the file. Used for the "Edit this page" button. | Must use the full link (supports repos beyond `netdata/netdata`). |
29 +| **sidebar\_label** | The label shown in the sidebar. | To make a category: the **overview** page’s `sidebar_label` **must match** `learn_rel_path` (lowercase). <br>👉 Every folder must have an overview page. |
30 +| **learn\_status** | `Published` or `Unpublished`. | If `Unpublished`, see [Unpublishing Files](#unpublishing-files). |
31 +| **learn\_rel\_path** | The location path on Learn. | Use **uppercase letters** and **spaces**. Example: `Netdata Agent/Installation/Linux`. <br>👉 Every level requires an overview page. |
32 +| **description** | Legacy metadata description. | Rarely used today. |
33
21 -## description
34 +Example row in `map.csv`:
35
23 -This column is sort of legacy, it is meant to populate a `description` metadata field.
36 +```csv
37 +custom_edit_url,sidebar_label,learn_status,learn_rel_path,description
38 +https://github.com/netdata/netdata/edit/master/docs/installation/linux.md,Linux,Published,"Netdata Agent/Installation/Linux","How to install Netdata Agent on Linux"
39 +```
40 +
41 +### 2. Test the Changes
42 +
43 +Before merging, **always test the map file**.
44 +
45 +1. Clone [Learn](https://github.com/netdata/learn) locally.
46 +2. Prepare environment and dependencies (see [ingest instructions](https://github.com/netdata/learn#ingest-and-process-documentation-files)).
47 +3. Run the ingest command:
48 + ```bash
49 + python3 ingest/ingest.py --repos OWNEROFREPO/netdata:YOURBRANCH
50 + ```
51 +4. Inspect the ingested changes.
52 +5. (Optional, advanced) [Deploy Learn](https://github.com/netdata/learn#local-deploy-of-learn) locally to confirm it builds correctly.
53 +
54 +### 3. Merge the Docs PR
55 +
56 +- Submit your PR with the updated docs **and** `map.csv`.
57 +- Get at least one approval.
58 +- **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.
59 +
60 +### 4. Merge the Learn Ingest PR
61 +
62 +Once your docs PR is merged:
63 +
64 +1. The ingest action triggers in [netdata/learn](https://github.com/netdata/learn).
65 +2. A PR is created automatically.
66 +3. Inspect the changes.
67 +4. Wait for the deploy preview.
68 +5. Check the deploy preview carefully.
69 +6. If everything looks good → merge.
70 +
71 +🍻 Done!
72 +
73 +## Unpublishing Files
74 +
75 +If you **delete**, **move**, or **unpublish** a file, redirects may break.
76 +
77 +1. Open [LegacyLearnCorrelateLinksWithGHURLs.json](https://github.com/netdata/learn/blob/master/LegacyLearnCorrelateLinksWithGHURLs.json).
78 +2. Search (`Ctrl+F`) for the old GitHub link.
79 +3. Update the entry to a relevant new location.
80 +4. If no suitable replacement exists → remove the entry.