Merge branch 'master' into fix/instant-loading

Author: squidfunk

.github/workflows/build.yml

@@ -36,7 +36,7 @@ permissions:
   contents: read
 
 jobs:
-  npm:
+  npm-build:
     runs-on: ubuntu-latest
     steps:
 
@@ -59,15 +59,38 @@ jobs:
         if: steps.cache.outputs.cache-hit != 'true'
         run: npm install
 
-      - name: Check project
-        run: npm run check
-
       - name: Build project
         run: |
           npm run build
           git diff --name-only
 
-  pypi:
+  npm-check:
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js runtime
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Set up Node.js dependency cache
+        uses: actions/cache@v3
+        id: cache
+        with:
+          key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          path: node_modules
+
+      - name: Set up Node.js dependencies
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: npm install
+
+      - name: Check project
+        run: npm run check
+
+  python:
     runs-on: ubuntu-latest
     steps:
 
@@ -78,6 +101,10 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            requirements.txt
 
       - name: Set up Python dependencies
         run: pip install --upgrade build twine

.github/workflows/documentation.yml

@@ -29,6 +29,8 @@ env:
 
 permissions:
   contents: write
+  id-token: write
+  pages: write
 
 jobs:
   documentation:
@@ -40,20 +42,25 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          sparse-checkout: |
+            docs
+            includes
+            material/overrides
+            src/templates/partials/languages
 
       - name: Set up Python runtime
         uses: actions/setup-python@v4
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Set the date environmental variable
-        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            requirements.txt
 
       - name: Set up build cache
-        uses: actions/cache@v3
-        id: cache
+        uses: actions/cache/restore@v3
         with:
-          key: mkdocs-material-${{ env.cache_id }}
+          key: mkdocs-material-${{ hashfiles('.cache/**') }}
           path: .cache
           restore-keys: |
             mkdocs-material-
@@ -63,15 +70,8 @@ jobs:
 
       - name: Install Python dependencies
         run: |
-          pip install \
-            "cairosvg>=2.5" \
-            "mkdocs-git-committers-plugin-2>=1.1.1" \
-            "mkdocs-git-revision-date-localized-plugin>=1.0" \
-            "mkdocs-minify-plugin>=0.3" \
-            "mkdocs-rss-plugin>=1.2" \
-            "mkdocs-redirects>=1.0" \
-            "lxml" \
-            "pillow<10"
+          pip install mkdocs-material
+          pip install mkdocs-material[recommended,git,imaging]
 
       - name: Install Insiders build
         if: github.event.repository.fork == false
@@ -88,10 +88,30 @@ jobs:
           rm -rf material
           cp -r mkdocs-material-insiders/material material
 
-      - name: Deploy documentation
+      - name: Build documentation
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
         run: |
-          mkdocs gh-deploy --force
+          mkdocs build --clean
           mkdocs --version
+
+      - name: Adjust permissions
+        run: |
+          chmod -c -R +rX site/ | while read line; do
+            echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+
+      - name: Upload to GitHub Pages
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v2
+
+      - name: Save build cache
+        uses: actions/cache/save@v3
+        with:
+          key: mkdocs-material-${{ hashfiles('.cache/**') }}
+          path: .cache

docs/blog/posts/git-sparse-checkout.md

@@ -0,0 +1,100 @@
+---
+date: 2023-09-22
+authors: [squidfunk]
+categories:
+  - Build
+  - Performance
+links:
+  - publishing-your-site.md#with-github-actions
+  - creating-your-site.md#building-your-site
+---
+
+# Using `git sparse-checkout` for faster documentation builds
+
+__Leveraging `git sparse-checkout` in GitHub Actions enabled us to speed up
+documentation builds in our repository, cutting checkout times from 20 to 30
+seconds to just 2 seconds.__
+
+Developing an efficient approach to build documentation in CI workflows is
+essential, especially when working in large repositories with thousands of
+commits, like ours. Of course, we want to build documentation quickly and
+efficiently, ensuring fast and productive workflows. When using both the
+wonderful [`git-committers`][git-committers] and [`git-revision-date-localized`]
+[git-revision-date-localized] plugins to display [document contributors] and
+[dates] at the bottom of each page, we are required to set `fetch-depth: 0`,
+which resulted in checkout times of 20 to 30 seconds on our repository. By
+leveraging [`git sparse-checkout`][git sparse-checkout] within [GitHub Actions],
+check out time was brought down to 2 seconds.
+
+  [git sparse-checkout]: https://git-scm.com/docs/git-sparse-checkout
+  [GitHub Actions]: ../../publishing-your-site.md#with-github-actions
+  [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+  [git-committers]: https://github.com/ojacques/mkdocs-git-committers-plugin-2
+  [document contributors]: ../../setup/adding-a-git-repository.md#document-contributors
+  [dates]: ../../setup/adding-a-git-repository.md#document-dates
+
+<!-- more -->
+
+## A Primer
+
+[`git sparse-checkout`][git sparse-checkout] allows you to check out only a
+subset of the files in a repository, making it incredibly useful for large
+repositories where a full checkout takes long and includes many files that are
+not relevant when building documentation.
+
+## GitHub Actions
+
+To enable [`git sparse-checkout`][git sparse-checkout] within [GitHub Actions]
+and ensure that you are only building the documentation that you need, add the
+following lines to your workflow file:
+
+``` yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+    sparse-checkout: |
+      docs
+      includes
+```
+
+[`git sparse-checkout`][git sparse-checkout] always checks out all files
+residing in the repository’s root. This means that regardless of the specified
+paths or directories for sparse checkout, the files located in the root of the
+repository will always be included in the checkout process.
+
+Thus, you only need to specify the directories that are necessary for building
+documentation. In our case, we only need the `docs` and `includes` folders,
+but if you need additional directories, you can just add them to the end of the
+list. A complete example workflow for [GitHub Actions]:
+
+``` yaml hl_lines="13-18"
+name: documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          sparse-checkout: |
+            docs
+            includes
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force
+```
+
+## Conclusion
+
+That's all there is! We're super happy with the results and hope that this will
+help you to speed up your documentation builds in [GitHub Actions] as well. As
+always, feel free to share your thoughts and experiences in the comments below.

material/overrides/hooks/translations.py

@@ -21,7 +21,7 @@
 import os
 import re
 
-from glob import glob
+from glob import iglob
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.structure.pages import Page
 from urllib.parse import urlencode, urlparse
@@ -40,7 +40,7 @@ def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files):
     # Collect all existing languages
     names: dict[str, str] = {}
     known: dict[str, dict[str, str]] = {}
-    for path in glob("src/templates/partials/languages/*.html"):
+    for path in iglob("src/templates/partials/languages/*.html"):
         with open(path, "r", encoding = "utf-8") as f:
             data = f.read()