Refactor CI on documentation

.github/workflows/check_doc.yaml

@@ -0,0 +1,63 @@
+name: Check Documentation
+
+on:
+  pull_request:
+    branches:
+      - '*'
+    paths:
+      - '.github/workflows/check_doc.yaml'
+      - 'docs/**'
+
+jobs:
+
+  docs:
+    name: lint, build and verify
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Install markdownlint
+        run: |
+          npm install --global markdownlint@0.29.0 markdownlint-cli@0.35.0
+
+      - name: Lint
+        run: ./docs/scripts/lint.sh docs
+
+      - name: Setup python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: "./docs/requirements.txt"
+
+      - name: Build documentation
+        working-directory: ./docs
+        run: |
+          pip install -r requirements.txt
+          mkdocs build --strict
+
+      - name: Setup ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+
+      - name: Install html-proofer
+        run: |
+          gem install nokogiri --version 1.18.6 --no-document -- --use-system-libraries
+          gem install html-proofer --version 5.0.10 --no-document -- --use-system-libraries
+        env:
+          NOKOGIRI_USE_SYSTEM_LIBRARIES: "true"
+
+      # Comes from https://github.com/gjtorikian/html-proofer?tab=readme-ov-file#caching-with-continuous-integration
+      - name: Cache HTMLProofer
+        uses: actions/cache@v4
+        with:
+          path: tmp/.htmlproofer
+          key: ${{ runner.os }}-htmlproofer
+
+      - name: Verify
+        run: ./docs/scripts/verify.sh docs/site

.github/workflows/check_doc.yml

@@ -1,25 +0,0 @@
-name: Check Documentation
-
-on:
-  pull_request:
-    branches:
-      - '*'
-
-jobs:
-
-  docs:
-    name: Check, verify and build documentation
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Check out code
-        uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-
-      - name: Check documentation
-        run: make docs-pull-images docs
-        env:
-          # These variables are not passed to workflows that are triggered by a pull request from a fork.
-          DOCS_VERIFY_SKIP: ${{ vars.DOCS_VERIFY_SKIP }}
-          DOCS_LINT_SKIP: ${{ vars.DOCS_LINT_SKIP }}

docs/content/deprecation/releases.md

@@ -34,7 +34,7 @@ Below is a non-exhaustive list of versions and their maintenance status:
 
 This page is maintained and updated periodically to reflect our roadmap and any decisions affecting the end of support for Traefik Proxy.
 
-Please refer to our migration guides for specific instructions on upgrading between versions, an example is the [v2 to v3 migration guide](../migration/v2-to-v3.md).
+Please refer to our migration guides for specific instructions on upgrading between versions.
 
 !!! important "All target dates for end of support or feature removal announcements may be subject to change."
 

docs/mkdocs.yml

@@ -2,18 +2,19 @@ site_name: Traefik
 site_description: Traefik Documentation
 site_author: traefik.io
 site_url: https://doc.traefik.io/traefik
-dev_addr: 0.0.0.0:8000
+dev_addr: localhost:8000
 
 repo_name: 'GitHub'
 repo_url: 'https://github.com/traefik/traefik'
 
 docs_dir: 'content'
 
-product: proxy
 
-# https://squidfunk.github.io/mkdocs-material/
+# Use custom version of mkdocs-material
+# See https://github.com/traefik/mkdocs-material
 theme:
   name: 'traefik-labs'
+  product: proxy
   language: en
   include_sidebar: true
   favicon: assets/img/traefikproxy-icon-color.png
@@ -165,7 +166,6 @@ nav:
           - 'Instana': 'observability/tracing/instana.md'
           - 'Haystack': 'observability/tracing/haystack.md'
           - 'Elastic': 'observability/tracing/elastic.md'
-          - 'OpenTelemetry': 'observability/tracing/opentelemetry.md'
   - 'Security':
         - 'Request Path': 'security/request-path.md'
         - 'Content-Length': 'security/content-length.md'

docs/readme.md

@@ -16,3 +16,15 @@
 
 [pymdown-extensions]: https://facelessuser.github.io/pymdown-extensions "PyMdown Extensions"
 [pymdown-extensions-src]: https://github.com/facelessuser/pymdown-extensions "PyMdown Extensions - Sources"
+
+## Build locally without docker
+
+```sh
+# Pre-requisite: python3, pip and virtualenv
+DOCS="/tmp/traefik-docs"
+mkdir "$DOCS"
+virtualenv "$DOCS"
+source "$DOCS/bin/activate"
+pip install -r requirements.txt
+mkdocs serve # or mkdocs build
+```

docs/scripts/lint.sh

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 # This script will run a couple of linter on the documentation
 
 set -eu
@@ -6,14 +6,14 @@ set -eu
 # We want to run all linters before returning success (exit 0) or failure (exit 1)
 # So this variable holds the global exit code
 EXIT_CODE=0
-readonly BASE_DIR=/app
+readonly BASE_DIR="${1:-/app}"
 
 echo "== Linting Markdown"
 # Uses the file ".markdownlint.json" for setup
 cd "${BASE_DIR}" || exit 1
 
-LINTER_EXCLUSIONS="$(find "${BASE_DIR}/content" -type f -name '.markdownlint.json')"
-GLOBAL_LINT_OPTIONS="--config ${BASE_DIR}/.markdownlint.json"
+LINTER_EXCLUSIONS="$(find "content" -type f -name '.markdownlint.json')"
+GLOBAL_LINT_OPTIONS="--config .markdownlint.json"
 
 # Lint the specific folders (containing linter specific rulesets)
 for LINTER_EXCLUSION in ${LINTER_EXCLUSIONS}
@@ -24,6 +24,6 @@ do
 done
 
 # Lint all the content, excluding the previously done`
-eval markdownlint "${GLOBAL_LINT_OPTIONS}" "${BASE_DIR}/content/**/*.md" || EXIT_CODE=1
+eval markdownlint "${GLOBAL_LINT_OPTIONS}" "content/**/*.md" || EXIT_CODE=1
 
 exit "${EXIT_CODE}"