| 1 | # Preview a documentation PR locally |
| 2 | |
| 3 | Question: how do you build Learn locally from a PR's docs content and inspect |
| 4 | it in a browser before merging? |
| 5 | |
| 6 | Use an isolated preview directory. Do not run ingest directly in a dirty Learn |
| 7 | checkout because ingest cleans and regenerates `docs/`. |
| 8 | |
| 9 | ## Evidence |
| 10 | |
| 11 | - `${NETDATA_REPOS_DIR}/learn/ingest/ingest.py:2632` defines `--local-repo`. |
| 12 | - `${NETDATA_REPOS_DIR}/learn/ingest/ingest.py:2790` cleans the ingest temp |
| 13 | folder and `${NETDATA_REPOS_DIR}/learn/ingest/ingest.py:2793` cleans the |
| 14 | Learn `docs/` tree before publishing. |
| 15 | - `${NETDATA_REPOS_DIR}/learn/ingest/ingest.py:2808` copies a local source repo |
| 16 | into the ingest temp folder when `--local-repo netdata:<path>` is used. |
| 17 | - `${NETDATA_REPOS_DIR}/learn/.learn_environment/ingest-requirements.txt:1` |
| 18 | lists the Python dependencies for ingest. |
| 19 | - `${NETDATA_REPOS_DIR}/learn/package.json:8` defines the Docusaurus build |
| 20 | script. |
| 21 | - `${NETDATA_REPOS_DIR}/learn/netlify.toml:5` pins the Netlify runtime to |
| 22 | Node `22.14.0`, Yarn, and `NODE_OPTIONS=--max_old_space_size=4096`. |
| 23 | |
| 24 | ## Procedure |
| 25 | |
| 26 | 1. Pick the PR source repo and the Learn checkout: |
| 27 | |
| 28 | ```bash |
| 29 | REPO_ROOT="$(git rev-parse --show-toplevel)" |
| 30 | PR_NUMBER="<pr-number>" |
| 31 | LEARN_REPO="${NETDATA_REPOS_DIR}/learn" |
| 32 | PREVIEW_ROOT="${TMPDIR:-/tmp}/netdata-learn-preview-pr-${PR_NUMBER}-$(date +%Y%m%d%H%M%S)" |
| 33 | SOURCE_COPY="${PREVIEW_ROOT}/netdata-source" |
| 34 | LEARN_COPY="${PREVIEW_ROOT}/learn" |
| 35 | ``` |
| 36 | |
| 37 | 2. Copy the PR source into an isolated directory: |
| 38 | |
| 39 | ```bash |
| 40 | mkdir -p "${SOURCE_COPY}" |
| 41 | git -C "${REPO_ROOT}" ls-files -co --exclude-standard -z \ |
| 42 | | rsync -a --from0 --files-from=- --ignore-missing-args "${REPO_ROOT}/" "${SOURCE_COPY}/" |
| 43 | ``` |
| 44 | |
| 45 | This includes tracked files and intentional untracked files that are not |
| 46 | ignored by Git, while still excluding ignored build and scratch output. |
| 47 | |
| 48 | 3. Clone the local Learn checkout into the preview directory: |
| 49 | |
| 50 | ```bash |
| 51 | git clone --branch "$(git -C "${LEARN_REPO}" branch --show-current)" \ |
| 52 | --single-branch "${LEARN_REPO}" "${LEARN_COPY}" |
| 53 | git -C "${LEARN_COPY}" rev-parse HEAD |
| 54 | ``` |
| 55 | |
| 56 | 4. Install ingest dependencies: |
| 57 | |
| 58 | ```bash |
| 59 | python3 -m venv "${PREVIEW_ROOT}/venv" |
| 60 | "${PREVIEW_ROOT}/venv/bin/python" -m pip install --upgrade pip |
| 61 | "${PREVIEW_ROOT}/venv/bin/python" -m pip install \ |
| 62 | -r "${LEARN_COPY}/.learn_environment/ingest-requirements.txt" |
| 63 | ``` |
| 64 | |
| 65 | 5. Reuse Learn `node_modules` when compatible: |
| 66 | |
| 67 | ```bash |
| 68 | ln -s "${LEARN_REPO}/node_modules" "${LEARN_COPY}/node_modules" |
| 69 | ``` |
| 70 | |
| 71 | 6. Run ingest with the PR content and fail on broken links from `netdata`: |
| 72 | |
| 73 | ```bash |
| 74 | cd "${LEARN_COPY}" |
| 75 | "${PREVIEW_ROOT}/venv/bin/python" ingest/ingest.py \ |
| 76 | --local-repo "netdata:${SOURCE_COPY}" \ |
| 77 | --ignore-on-prem-repo \ |
| 78 | --use_plain_https \ |
| 79 | --fail-links-netdata |
| 80 | ``` |
| 81 | |
| 82 | 7. Build with the Netlify-pinned runtime: |
| 83 | |
| 84 | ```bash |
| 85 | NODE_OPTIONS=--max_old_space_size=4096 \ |
| 86 | npx -y -p node@22.14.0 -p yarn@1.22.22 yarn build |
| 87 | ``` |
| 88 | |
| 89 | 8. Serve and inspect: |
| 90 | |
| 91 | ```bash |
| 92 | python3 -m http.server 3030 --bind 127.0.0.1 --directory "${LEARN_COPY}/build" |
| 93 | ``` |
| 94 | |
| 95 | Open changed pages, generated integration pages, and the affected category |
| 96 | index. Confirm HTTP 200, the expected H1, no 404 page, and no MDX/runtime |
| 97 | error. |
| 98 | |
| 99 | ## Reporting |
| 100 | |
| 101 | Report these facts: |
| 102 | |
| 103 | - Learn branch and commit used. |
| 104 | - Ingest command and exit status. |
| 105 | - Build command and exit status. |
| 106 | - Browser-inspected URLs and status. |
| 107 | - PR-specific warnings/failures. |
| 108 | - Pre-existing site-wide warnings separately. |
| 109 | |
| 110 | ## How I Figured This Out |
| 111 | |
| 112 | Read `${NETDATA_REPOS_DIR}/learn/ingest/ingest.py`, |
| 113 | `${NETDATA_REPOS_DIR}/learn/package.json`, |
| 114 | `${NETDATA_REPOS_DIR}/learn/netlify.toml`, and |
| 115 | `${NETDATA_REPOS_DIR}/learn/.learn_environment/ingest-requirements.txt`. |
| 116 | Validated the flow by building an isolated Learn preview from a Network Flows |
| 117 | documentation PR, running ingest with `--fail-links-netdata`, running |
| 118 | `yarn build`, serving the static build, and checking representative pages in a |
| 119 | browser. |