.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

CHANGELOG

@@ -1,3 +1,24 @@
+mkdocs-material-9.4.2 (2023-09-25)
+
+  * Updated Slovenian translations
+  * Added animation to sidebar navigation expansion and collapse
+  * Added support for auto-replacement of document head for instant navigation
+  * Improved compatibility of new emoji extension with Python < 3.10
+  * Switched regex dependency to use minimal version
+  * Refactored alignment and spacing of sidebar navigation
+  * Fixed expansion button not focusable via keyboard in sidebar navigation
+  * Fixed viewport offset restoration on first load when using instant navigation
+  * Fixed accidental highlight of non-clickable elements in blog plugin sidebar
+  * Fixed #6041: Blog plugin crashes when nav is defined and blog not included
+  * Fixed #5972: Blog plugin ignores section index pages in paginated views
+  * Fixed #5954: Repeated click on anchor ignored when using instant navigation
+  * Fixed #5742: Keyboard navigation broken when using instant navigation
+
+  Updated templates
+
+  * partials/nav-item.html
+  * blog-post.html
+
 mkdocs-material-9.4.1 (2023-09-22)
 
   * Improved colors and contrast in dark mode

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.

docs/changelog/index.md

@@ -2,6 +2,27 @@
 
 ## Material for MkDocs
 
+### 9.4.2 <small>September 25, 2023</small> { id="9.4.2" }
+
+- Updated Slovenian translations
+- Added animation to sidebar navigation expansion and collapse
+- Added support for auto-replacement of document head for instant navigation
+- Improved compatibility of new emoji extension with Python < 3.10
+- Switched regex dependency to use minimal version
+- Refactored alignment and spacing of sidebar navigation
+- Fixed expansion button not focusable via keyboard in sidebar navigation
+- Fixed viewport offset restoration on first load when using instant navigation
+- Fixed accidental highlight of non-clickable elements in blog plugin sidebar
+- Fixed #6041: Blog plugin crashes when `nav` is defined and blog not included
+- Fixed #5972: Blog plugin ignores section index pages in paginated views
+- Fixed #5954: Repeated click on anchor ignored when using instant navigation
+- Fixed #5742: Keyboard navigation broken when using instant navigation
+
+__Updated templates__ ([diff](https://github.com/squidfunk/mkdocs-material/compare/9.4.1...master))
+
+- `partials/nav-item.html`
+- `blog-post.html`
+
 ### 9.4.1 <small>September 22, 2023</small> { id="9.4.1" }
 
 - Improved colors and contrast in dark mode

docs/schema/assets/icons.json

@@ -9552,6 +9552,8 @@
     "octicons/file-zip-24",
     "octicons/filter-16",
     "octicons/filter-24",
+    "octicons/filter-remove-16",
+    "octicons/filter-remove-24",
     "octicons/fiscal-host-16",
     "octicons/flame-16",
     "octicons/flame-24",
@@ -9974,6 +9976,7 @@
     "simple/adonisjs",
     "simple/adp",
     "simple/adroll",
+    "simple/adventofcode",
     "simple/adyen",
     "simple/aerlingus",
     "simple/aeroflot",
@@ -10173,6 +10176,7 @@
     "simple/authelia",
     "simple/authy",
     "simple/autodesk",
+    "simple/autodeskrevit",
     "simple/autohotkey",
     "simple/automattic",
     "simple/autoprefixer",
@@ -10540,6 +10544,7 @@
     "simple/deno",
     "simple/denon",
     "simple/dependabot",
+    "simple/dependencycheck",
     "simple/derspiegel",
     "simple/designernews",
     "simple/deutschebahn",
@@ -11434,6 +11439,7 @@
     "simple/mobx",
     "simple/mobxstatetree",
     "simple/mocha",
+    "simple/mockserviceworker",
     "simple/modin",
     "simple/modrinth",
     "simple/modx",

material/__init__.py

@@ -18,4 +18,4 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
-__version__ = "9.4.1"
+__version__ = "9.4.2"

material/extensions/emoji.py

@@ -18,6 +18,8 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
+from __future__ import annotations
+
 import codecs
 import functools
 import material