Docs Learn Pr Preview

docs-learn-pr-preview

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

Always load docs-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.13 -m venv "${PREVIEW_ROOT}/venv"
"${PREVIEW_ROOT}/venv/bin/python" -m pip install \
  --require-hashes \
  -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 command and runtime Netlify uses. Both are the [build] table of static.toml in the Learn checkout (command, and NODE_VERSION, NPM_VERSION, NODE_OPTIONS under environment); read them rather than pinning values here, because the pins move with the site:

sed -n '/^\[build\]/,/^$/p' "${LEARN_COPY}/static.toml"
PUBLISH_DIR="$(sed -n '/^\[build\]/,/^$/{s/^ *publish *= *"\(.*\)"/\1/p;}' "${LEARN_COPY}/static.toml")"
[ -n "${PUBLISH_DIR}" ] || { echo "no publish key in the [build] table of static.toml" >&2; exit 1; }

Run the printed command inside ${LEARN_COPY} with the printed NODE_OPTIONS exported and Node and npm matching NODE_VERSION and NPM_VERSION (for example through npx -y -p node@<NODE_VERSION> -p npm@<NPM_VERSION> <command>). The output lands in ${LEARN_COPY}/${PUBLISH_DIR}.

Serve the static build for inspection:

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

Or run it in the background with a PID file:

python3 -m http.server 3030 --bind 127.0.0.1 --directory "${LEARN_COPY}/${PUBLISH_DIR}" \
  >"${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.