*: content revamp

These changes mostly entail:
* workflow to check for new theme releases,
* improved synchronization logic,
* better reference defintions in generated content,
* serve minified JS,
* higher degree of automation.

Fixes: prometheus-operator/prometheus-operator#6046

Signed-off-by: Pranshu Srivastava <[email protected]>

.github/workflows/hugo-theme-release.yml

@@ -0,0 +1,26 @@
+name: Hugo Theme Release
+
+on:
+  schedule:
+    # Check every week.
+    - cron: '0 0 * * 0'
+
+jobs:
+  check-theme-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Check for new theme release
+        run: |
+          # Get the latest release tag downstream.
+          cd themes/doks
+          git fetch --tags
+          latest_tag=$(git describe --tags `git rev-list --tags --max-count=1` | cut -d. -f1)
+          current_tag=$(git describe --tags | cut -d. -f1)
+          if [ "$latest_tag" != "$current_tag" ]; then
+            repository=$(git config --get remote.origin.url)
+            echo "[OUTDATED] $repository: $latest_tag/$current_tag"
+            exit 1
+          else
+            echo "[UP-TO-DATE] No new theme release available."
+          fi

.gitignore

@@ -1,35 +1,22 @@
+# Build artifacts to ignore.
+
 /public/
 /repos/kube-prometheus
 /repos/prometheus-operator
 /resources/_gen/
 /static/img
 /.hugo_build.lock
 
-# Generated content to ignore (sorted alphabetically)
+# Generated content to ignore.
 
 /content/adopters.md
-/content/docs/kube/developing-prometheus-rules-and-grafana-dashboards.md
-/content/docs/kube/exposing-prometheus-alertmanager-grafana-ingress.md
-/content/docs/kube/kube-prometheus-on-kubeadm.md
-/content/docs/kube/blackbox-exporter.md
-/content/docs/kube/deploy-kind.md
-/content/docs/kube/monitoring-external-etcd.md
-/content/docs/kube/monitoring-other-namespaces.md
-/content/docs/user-guides/getting-started.md
-/content/docs/user-guides/alerting.md
-/content/docs/user-guides/webhook.md
-/content/docs/user-guides/prometheus-agent.md
-/content/docs/user-guides/scrapeconfig.md
-/content/docs/operator/api.md
-/content/docs/operator/compatibility.md
-/content/docs/operator/custom-metrics-elements.png
-/content/docs/operator/design.md
-/content/docs/operator/high-availability.md
-/content/docs/operator/operator.md
-/content/docs/operator/rbac-crd.md
-/content/docs/operator/rbac.md
-/content/docs/operator/storage.md
-/content/docs/operator/strategic-merge-patch.md
-/content/docs/operator/thanos.md
-/content/docs/operator/troubleshooting.md
+/content/docs/kube/*
+/content/docs/operator/*
 /content/docs/prologue/contributing.md
+/content/docs/user-guides/*
+
+# Exempt _index.md files from the above rules.
+
+!/content/docs/kube/_index.md
+!/content/docs/operator/_index.md
+!/content/docs/user-guides/_index.md

Makefile

@@ -1,15 +1,19 @@
-all: theme synchronize public
-
-.PHONY: synchronize
-synchronize:
-	bash synchronize.sh
+all: theme synchronize build
 
 .PHONY: theme
 theme:
-	cd themes/doks/ && \
+	@cd themes/doks/ && \
 	npm install && \
 	rm -rf content
 
-.PHONY: public
-public:
+.PHONY: synchronize
+synchronize:
+	bash -x synchronize.sh
+
+.PHONY: build
+build:
 	hugo
+
+.PHONY: serve
+serve:
+	hugo serve

config.yaml

@@ -3,8 +3,3 @@ languageCode: "en-us"
 title: "Prometheus Operator"
 
 theme: doks
-
-# Disable minification of JS code to workaround
-# https://github.com/h-enk/doks/issues/716
-minify:
-  disableJS: true

synchronize.sh

@@ -1,54 +1,98 @@
 #!/usr/bin/env bash
 
-set -xe
+# -e: Exit immediately if a command exits with a non-zero status.
+# -o pipefail: Causes a pipeline to return the exit status of the last command in the pipe that returned a non-zero return value.
+set -eo pipefail
 
+# Remove artefacts.
 rm -rf repos/
+
+# Create directories.
 mkdir repos/
 
-if [[ -z "$USE_LOCAL_REPOSITORIES" ]]; then
+# Clone repos or use local copies.
+if [[ -n "$PO_PATH" ]] && [[ -d "$PO_PATH" ]]; then
+  ln -s "$PO_PATH" repos/prometheus-operator
+else
   git clone https://github.com/prometheus-operator/prometheus-operator -b main --depth 1 repos/prometheus-operator
-  git clone https://github.com/prometheus-operator/kube-prometheus -b main --depth 1 repos/kube-prometheus
+fi
+
+if [[ -n "$KUBE_PROMETHEUS_PATH" ]] && [[ -d "$KUBE_PROMETHEUS_PATH" ]]; then
+  ln -s "$KUBE_PROMETHEUS_PATH" repos/kube-prometheus
 else
-  ln -s ../../prometheus-operator repos/prometheus-operator
-  ln -s ../../kube-prometheus repos/kube-prometheus
+  git clone https://github.com/prometheus-operator/kube-prometheus -b main --depth 1 repos/kube-prometheus
 fi
 
+# Show pinned revisions.
 for r in repos/prometheus-operator repos/kube-prometheus; do
-  echo "$r -> ""$(cd $r && git rev-parse HEAD)"
+  echo "$r@""$(cd $r && git rev-parse HEAD)"
+done
+
+# Copy dependant sections and metadata.
+cp -f repos/prometheus-operator/ADOPTERS.md content/adopters.md
+cp -f repos/prometheus-operator/CONTRIBUTING.md content/docs/prologue/contributing.md
+cp -fr repos/prometheus-operator/Documentation/img static/img
+cp -fr repos/prometheus-operator/Documentation/user-guides/ content/docs/user-guides/
+cp -fr repos/prometheus-operator/Documentation/ content/docs/operator/
+cp -fr repos/kube-prometheus/docs/ content/docs/kube/
+
+# One-off fixes so as to not break links.
+cp -f repos/prometheus-operator/Documentation/user-guides/storage.md content/docs/operator/storage.md
+cp -f repos/prometheus-operator/Documentation/user-guides/strategic-merge-patch.md content/docs/operator/strategic-merge-patch.md
+cp -f repos/kube-prometheus/docs/customizations/developing-prometheus-rules-and-grafana-dashboards.md content/docs/kube/developing-prometheus-rules-and-grafana-dashboards.md
+cp -f repos/kube-prometheus/docs/customizations/exposing-prometheus-alertmanager-grafana-ingress.md content/docs/kube/exposing-prometheus-alertmanager-grafana-ingress.md
+
+
+
+# Remove invalid files without front matter.
+find content/docs -type f -name "*.md" -print0 | while IFS= read -r -d '' file; do
+  # Prevent awk from failing the script if the file is empty.
+  set +e
+  # For each line in the file:
+  # * BEGIN: Set p to 0 and exitcode to 0.
+  # * !p && NF: If p is 0 and the number of fields is not 0 (i.e. the line is not empty):
+  #   * if ($0 != "---"): If the line is not "---", set exitcode to 1 and exit.
+  #   * else: Set p to 1 and skip to the next line.
+  # * p && /---/: If p is 1 and the line is "---", set p to 2.
+  # * END: If p is not 2, set exitcode to 1.
+  # Note how p is used to move from the first part of the conditional to the next (p && ..., otherwise it will keep checking the first condition until EOF).
+  awk 'BEGIN {p=0; exitcode=0} !p && NF { if ($0 != "---") {exitcode=1; exit} else {p=1; next} } p && /---/ {p=2} END {if (p != 2) exitcode=1; exit exitcode}' "${file}" > /dev/null
+  EXITCODE=$?
+  set -e
+  # Prepend zero-length front matter if the file is invalid.
+  if [ "$EXITCODE" -ne 0 ]; then
+    TMPFILE=$(mktemp)
+    TITLE=$(\
+    # Remove .md extension.
+    basename "${file}" .md |\
+    # Replace dashes with spaces.
+    sed 's/-/ /g' |\
+    # First, positive lookbehind from non-whitespace character for a whitespace.
+    # Then, convert each word to lowercase.
+    # Finally, convert the first letter of each word to uppercase and add a whitespace.
+    perl -ne 'print ucfirst(lc($_))." " for split /(?<=\S)\s+/')
+    echo -e "---\ntitle: ${TITLE}\n---\n" > "$TMPFILE"
+    cat "$file" >> "$TMPFILE"
+    mv "$TMPFILE" "$file"
+  fi
+done
+
+# Prevent grep from failing the script.
+set +e
+
+# Sanitize links by replacing immediate filenames with relative (to /docs references).
+find ./content/docs -name "*.md" | while IFS= read -r file
+do
+    # Extract markdown links (in the format [text](link.md)) from the current file.
+    grep -oE '\]\([^/)]*\.md\)' "${file}" | while IFS= read -r link
+    do
+        dirName=$(dirname "${file}")
+        sanitizedLink=$(echo "${link}" | tr -d "]()" | sed 's/\.md//')
+        original="](${sanitizedLink}.md)"
+        sanitizedLinkWithPath="${dirName}/${sanitizedLink}"
+        modified="](/docs/${sanitizedLinkWithPath#./content/docs/}/)"
+        sed -i '' -e "s|${original}|${modified}|g" "${file}"
+    done
 done
 
-# main section + images
-cp repos/prometheus-operator/ADOPTERS.md content/adopters.md
-cp -r repos/prometheus-operator/Documentation/img static/img
-
-# prologue section
-cp repos/prometheus-operator/CONTRIBUTING.md content/docs/prologue/contributing.md
-
-# user guides section
-cp repos/prometheus-operator/Documentation/user-guides/getting-started.md content/docs/user-guides/getting-started.md
-cp repos/prometheus-operator/Documentation/user-guides/alerting.md content/docs/user-guides/alerting.md
-cp repos/prometheus-operator/Documentation/user-guides/prometheus-agent.md content/docs/user-guides/prometheus-agent.md
-cp repos/prometheus-operator/Documentation/user-guides/scrapeconfig.md content/docs/user-guides/scrapeconfig.md
-cp repos/prometheus-operator/Documentation/user-guides/webhook.md content/docs/user-guides/webhook.md
-
-# prometheus-operator section
-cp repos/prometheus-operator/Documentation/api.md content/docs/operator/api.md
-cp repos/prometheus-operator/Documentation/operator.md content/docs/operator/operator.md
-cp repos/prometheus-operator/Documentation/compatibility.md content/docs/operator/compatibility.md
-cp repos/prometheus-operator/Documentation/design.md content/docs/operator/design.md
-cp repos/prometheus-operator/Documentation/high-availability.md content/docs/operator/high-availability.md
-cp repos/prometheus-operator/Documentation/rbac-crd.md content/docs/operator/rbac-crd.md
-cp repos/prometheus-operator/Documentation/rbac.md content/docs/operator/rbac.md
-cp repos/prometheus-operator/Documentation/thanos.md content/docs/operator/thanos.md
-cp repos/prometheus-operator/Documentation/troubleshooting.md content/docs/operator/troubleshooting.md
-cp repos/prometheus-operator/Documentation/user-guides/storage.md content/docs/operator/storage.md
-cp repos/prometheus-operator/Documentation/user-guides/strategic-merge-patch.md content/docs/operator/strategic-merge-patch.md
-
-# kube-prometheus section
-cp repos/kube-prometheus/docs/blackbox-exporter.md content/docs/kube/blackbox-exporter.md
-cp repos/kube-prometheus/docs/deploy-kind.md content/docs/kube/deploy-kind.md
-cp repos/kube-prometheus/docs/customizations/developing-prometheus-rules-and-grafana-dashboards.md content/docs/kube/developing-prometheus-rules-and-grafana-dashboards.md
-cp repos/kube-prometheus/docs/customizations/exposing-prometheus-alertmanager-grafana-ingress.md content/docs/kube/exposing-prometheus-alertmanager-grafana-ingress.md
-cp repos/kube-prometheus/docs/kube-prometheus-on-kubeadm.md content/docs/kube/kube-prometheus-on-kubeadm.md
-cp repos/kube-prometheus/docs/monitoring-external-etcd.md content/docs/kube/monitoring-external-etcd.md
-cp repos/kube-prometheus/docs/monitoring-other-namespaces.md content/docs/kube/monitoring-other-namespaces.md
+set -e