learn-pr-preview

Build and inspect a local Learn site from a PR's documentation content without dirtying the real Learn checkout.

Always load learn-site-structure first. If the PR touches metadata.yaml or generated integration pages, also load integrations-lifecycle.

Rules

• Trigger only on an explicit preview/build/inspect request.
• Do not run ingest directly in a dirty Learn worktree.
• Use an isolated preview directory under /tmp or the repo's gitignored

.local/.

• Record the Learn branch and commit used for the preview.
• Copy PR source content into an isolated source directory. Prefer committed

PR content; if validating uncommitted work, copy tracked modified files and only intentional untracked docs files after checking git status --short.

• Save any preview server PID and kill only that PID when stopping it.
• Treat site-wide warnings as evidence, but separate pre-existing global Learn

warnings from PR-specific Network Flows or docs warnings.

Workflow

Set paths:

REPO_ROOT="$(git rev-parse --show-toplevel)"
PR_NUMBER="<pr-number>"
LEARN_REPO="${NETDATA_REPOS_DIR}/learn"
PREVIEW_ROOT="${TMPDIR:-/tmp}/netdata-learn-preview-pr-${PR_NUMBER}-$(date +%Y%m%d%H%M%S)"
SOURCE_COPY="${PREVIEW_ROOT}/netdata-source"
LEARN_COPY="${PREVIEW_ROOT}/learn"

Create isolated copies:

mkdir -p "${SOURCE_COPY}"
git -C "${REPO_ROOT}" ls-files -co --exclude-standard -z \
  | rsync -a --from0 --files-from=- --ignore-missing-args "${REPO_ROOT}/" "${SOURCE_COPY}/"

git clone --branch "$(git -C "${LEARN_REPO}" branch --show-current)" \
  --single-branch "${LEARN_REPO}" "${LEARN_COPY}"
git -C "${LEARN_COPY}" rev-parse HEAD

Install ingest dependencies in the isolated preview:

python3 -m venv "${PREVIEW_ROOT}/venv"
"${PREVIEW_ROOT}/venv/bin/python" -m pip install --upgrade pip
"${PREVIEW_ROOT}/venv/bin/python" -m pip install \
  -r "${LEARN_COPY}/.learn_environment/ingest-requirements.txt"

If the real Learn checkout has compatible node_modules, symlink it to avoid a fresh install:

ln -s "${LEARN_REPO}/node_modules" "${LEARN_COPY}/node_modules"

Run ingest with the PR source:

cd "${LEARN_COPY}"
"${PREVIEW_ROOT}/venv/bin/python" ingest/ingest.py \
  --local-repo "netdata:${SOURCE_COPY}" \
  --ignore-on-prem-repo \
  --use_plain_https \
  --fail-links-netdata

Build with the Netlify-pinned runtime:

NODE_OPTIONS=--max_old_space_size=4096 \
  npx -y -p [email protected] -p [email protected] yarn build

Serve the static build for inspection:

python3 -m http.server 3030 --bind 127.0.0.1 --directory "${LEARN_COPY}/build"

Or run it in the background with a PID file:

python3 -m http.server 3030 --bind 127.0.0.1 --directory "${LEARN_COPY}/build" \
  >"${PREVIEW_ROOT}/http.log" 2>&1 &
echo "$!" > "${PREVIEW_ROOT}/http.pid"

Inspect representative pages in a browser. For docs PRs, check:

• the changed hand-authored pages;
• generated integration pages affected by metadata.yaml;
• the category index page;
• at least one page that previously failed ingest, MDX, or link checks.

Report:

• Learn branch and commit used;
• ingest command and exit status;
• build command and exit status;
• inspected URLs and HTTP/browser status;
• PR-specific warnings or failures;
• pre-existing global warnings separately.