Merge branch 'master' into fix/instant-loading

.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:/timvink/mkdocs-git-revision-date-localized-plugin
+ [git-committers]: https:/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()