From c23fbdfc843eb9cd29298696b29a410def5e915d Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 18:30:39 +0200 Subject: [PATCH 01/33] Improve GitHub Actions workflows --- .github/workflows/build.yml | 1 + .github/workflows/documentation.yml | 26 +++++++++++--------------- 2 files changed, 12 insertions(+), 15 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 3dabde071..23b0bb1cb 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -78,6 +78,7 @@ jobs: uses: actions/setup-python@v4 with: python-version: ${{ env.PYTHON_VERSION }} + cache: pip - name: Set up Python dependencies run: pip install --upgrade build twine diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 8fca7b29f..e793e7eb9 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -45,15 +45,12 @@ jobs: 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 - 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- path: .cache restore-keys: | mkdocs-material- @@ -63,15 +60,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 @@ -95,3 +85,9 @@ jobs: run: | mkdocs gh-deploy --force mkdocs --version + + - name: Save build cache + uses: actions/cache/save@v3 + with: + key: mkdocs-material-${{ hashfiles('.cache/**') }} + path: .cache From 74d4b3b1e59723d5a817326030b541fc49b88c26 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 18:46:51 +0200 Subject: [PATCH 02/33] Test direct GitHub Pages deployment --- .github/workflows/documentation.yml | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index e793e7eb9..caae8b485 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -50,7 +50,7 @@ jobs: - name: Set up build cache uses: actions/cache/restore@v3 with: - key: mkdocs-material- + key: mkdocs-material-${{ hashfiles('.cache/**') }} path: .cache restore-keys: | mkdocs-material- @@ -78,14 +78,26 @@ 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: Fix 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 + + - name: Deploy to GitHub Pages + uses: actions/deploy-pages@v2 + - name: Save build cache uses: actions/cache/save@v3 with: From 76a995e4ac469a05219ef3475641b2fb0d87b9d7 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 18:50:29 +0200 Subject: [PATCH 03/33] Test direct GitHub Pages deployment --- .github/workflows/documentation.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index caae8b485..acd388e45 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -94,6 +94,8 @@ jobs: - name: Upload to GitHub Pages uses: actions/upload-pages-artifact@v2 + with: + path: site - name: Deploy to GitHub Pages uses: actions/deploy-pages@v2 From b367f405250f1ad657c5029e44f3451e47a3d55e Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 18:53:41 +0200 Subject: [PATCH 04/33] Test direct GitHub Pages deployment --- .github/workflows/documentation.yml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index acd388e45..ee84d3dd1 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -29,6 +29,7 @@ env: permissions: contents: write + id-token: write jobs: documentation: @@ -86,12 +87,6 @@ jobs: mkdocs build --clean mkdocs --version - - name: Fix 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: From 7bde9e7215eb90aeb3cdff88156f8cd2920b7229 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 18:58:47 +0200 Subject: [PATCH 05/33] Test direct GitHub Pages deployment --- .github/workflows/documentation.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index ee84d3dd1..df572e1e5 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -87,6 +87,12 @@ jobs: 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: From 4840c2da12040e4580430145c893dbc391aa16ca Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:02:45 +0200 Subject: [PATCH 06/33] Test direct GitHub Pages deployment --- .github/workflows/documentation.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index df572e1e5..35a1792c5 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -30,6 +30,7 @@ env: permissions: contents: write id-token: write + pages: write jobs: documentation: From acb803f80c0d9bedb9b9e8ba7aaf4638d4407429 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:11:07 +0200 Subject: [PATCH 07/33] Test direct GitHub Pages deployment --- .github/workflows/documentation.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 35a1792c5..eda10261e 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -100,7 +100,8 @@ jobs: path: site - name: Deploy to GitHub Pages - uses: actions/deploy-pages@v2 + # uses: actions/deploy-pages@v2 + uses: Bluefissure/deploy-pages@d929e03 - name: Save build cache uses: actions/cache/save@v3 From 96ccea52a758119219ddb7890e807fd642615c63 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:12:07 +0200 Subject: [PATCH 08/33] Test direct GitHub Pages deployment --- .github/workflows/documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index eda10261e..ff66f9bea 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -101,7 +101,7 @@ jobs: - name: Deploy to GitHub Pages # uses: actions/deploy-pages@v2 - uses: Bluefissure/deploy-pages@d929e03 + uses: Bluefissure/deploy-pages@d929e03378611c913632ff3608164b9d1adc4a3f - name: Save build cache uses: actions/cache/save@v3 From ade1fe9c1465cc6cc709e0234de4ce89a0af6363 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:19:42 +0200 Subject: [PATCH 09/33] Test direct GitHub Pages deployment --- .github/workflows/documentation.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index ff66f9bea..6776162d2 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -42,6 +42,10 @@ jobs: uses: actions/checkout@v4 with: fetch-depth: 0 + sparse-checkout: | + docs + includes + material/overrides - name: Set up Python runtime uses: actions/setup-python@v4 @@ -101,6 +105,7 @@ jobs: - name: Deploy to GitHub Pages # uses: actions/deploy-pages@v2 + # https://github.com/orgs/community/discussions/67961 uses: Bluefissure/deploy-pages@d929e03378611c913632ff3608164b9d1adc4a3f - name: Save build cache From 188d395ac77b61935c1514529976fa58cf4042a7 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:22:21 +0200 Subject: [PATCH 10/33] Test direct GitHub Pages deployment --- material/overrides/hooks/translations.py | 2 +- src/overrides/hooks/translations.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/material/overrides/hooks/translations.py b/material/overrides/hooks/translations.py index 6a523f698..35b8c2d9c 100644 --- a/material/overrides/hooks/translations.py +++ b/material/overrides/hooks/translations.py @@ -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 glob("material/templates/partials/languages/*.html"): with open(path, "r", encoding = "utf-8") as f: data = f.read() diff --git a/src/overrides/hooks/translations.py b/src/overrides/hooks/translations.py index 6a523f698..35b8c2d9c 100644 --- a/src/overrides/hooks/translations.py +++ b/src/overrides/hooks/translations.py @@ -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 glob("material/templates/partials/languages/*.html"): with open(path, "r", encoding = "utf-8") as f: data = f.read() From 159b28cd64347789cf0c43fde24c519c2d9b318e Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:30:57 +0200 Subject: [PATCH 11/33] Test direct GitHub Pages deployment --- material/overrides/hooks/translations.py | 4 ++-- src/overrides/hooks/translations.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/material/overrides/hooks/translations.py b/material/overrides/hooks/translations.py index 35b8c2d9c..661fd18e1 100644 --- a/material/overrides/hooks/translations.py +++ b/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("material/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() diff --git a/src/overrides/hooks/translations.py b/src/overrides/hooks/translations.py index 35b8c2d9c..661fd18e1 100644 --- a/src/overrides/hooks/translations.py +++ b/src/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("material/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() From 97e2e8497a5f6efeecc5c1aba1bfabc720014dc9 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:32:29 +0200 Subject: [PATCH 12/33] Test direct GitHub Pages deployment --- .github/workflows/documentation.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 6776162d2..78a69e5b8 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -46,6 +46,7 @@ jobs: docs includes material/overrides + src/templates/partials/languages - name: Set up Python runtime uses: actions/setup-python@v4 From 8fa269b635848a651518f703bccfad82c14d4171 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:40:43 +0200 Subject: [PATCH 13/33] Split workflow into build and check --- .github/workflows/build.yml | 39 +++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 23b0bb1cb..7fd2c0de2 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -36,7 +36,37 @@ permissions: contents: read jobs: - npm: + npm-build: + name: Build sources + 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: Build project + run: | + npm run build + git diff --name-only + + npm-check: + name: Check sources runs-on: ubuntu-latest steps: @@ -62,12 +92,8 @@ jobs: - name: Check project run: npm run check - - name: Build project - run: | - npm run build - git diff --name-only - pypi: + name: Publish Python package runs-on: ubuntu-latest steps: @@ -94,6 +120,7 @@ jobs: run: twine upload --disable-progress-bar -u ${PYPI_USERNAME} -p ${PYPI_PASSWORD} dist/* docker: + name: Publish Docker image runs-on: ubuntu-latest steps: From 64827f409bac61c22334c794b0eecdcc5981293a Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:42:56 +0200 Subject: [PATCH 14/33] Split workflow into build and check --- .github/workflows/build.yml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 7fd2c0de2..1d7da3032 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -37,7 +37,6 @@ permissions: jobs: npm-build: - name: Build sources runs-on: ubuntu-latest steps: @@ -66,7 +65,6 @@ jobs: git diff --name-only npm-check: - name: Check sources runs-on: ubuntu-latest steps: @@ -92,8 +90,7 @@ jobs: - name: Check project run: npm run check - pypi: - name: Publish Python package + python: runs-on: ubuntu-latest steps: @@ -120,7 +117,6 @@ jobs: run: twine upload --disable-progress-bar -u ${PYPI_USERNAME} -p ${PYPI_PASSWORD} dist/* docker: - name: Publish Docker image runs-on: ubuntu-latest steps: From adc59cad33ab779b95cb674be3bd5f80efeb4767 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 19:47:48 +0200 Subject: [PATCH 15/33] Test caching of deps in CI --- .github/workflows/build.yml | 3 +++ .github/workflows/documentation.yml | 3 +++ 2 files changed, 6 insertions(+) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 1d7da3032..d79361370 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -102,6 +102,9 @@ jobs: 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 diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 78a69e5b8..622c61680 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -53,6 +53,9 @@ jobs: with: python-version: ${{ env.PYTHON_VERSION }} cache: pip + cache-dependency-path: | + pyproject.toml + requirements.txt - name: Set up build cache uses: actions/cache/restore@v3 From 466b38654bba64b0f8a4fe1811906bfc61c9c729 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 20:48:12 +0200 Subject: [PATCH 16/33] Added blog post on git sparse-checkout --- docs/blog/posts/git-sparse-checkout.md | 97 ++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/blog/posts/git-sparse-checkout.md diff --git a/docs/blog/posts/git-sparse-checkout.md b/docs/blog/posts/git-sparse-checkout.md new file mode 100644 index 000000000..e5cb8bc2f --- /dev/null +++ b/docs/blog/posts/git-sparse-checkout.md @@ -0,0 +1,97 @@ +--- +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 the wonderful +[`git-revision-date-localized`][git-revision-date-localized] plugin to display +[document contributors] 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], we were able to bring down checkout time 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 + [document contributors]: ../../setup/adding-a-git-repository.md#document-contributors + + + +## 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. From d3d8964c63b90b8fddef8fbf84f363418aeb5331 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 20:51:23 +0200 Subject: [PATCH 17/33] Switch back to GitHub's deploy action --- .github/workflows/documentation.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 622c61680..0e9b17cd0 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -108,9 +108,7 @@ jobs: path: site - name: Deploy to GitHub Pages - # uses: actions/deploy-pages@v2 - # https://github.com/orgs/community/discussions/67961 - uses: Bluefissure/deploy-pages@d929e03378611c913632ff3608164b9d1adc4a3f + uses: actions/deploy-pages@v2 - name: Save build cache uses: actions/cache/save@v3 From b276146fc7c03bf89a46e628d59c792faa825e82 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 21:01:14 +0200 Subject: [PATCH 18/33] Added git-committers plugin to blog post --- docs/blog/posts/git-sparse-checkout.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/blog/posts/git-sparse-checkout.md b/docs/blog/posts/git-sparse-checkout.md index e5cb8bc2f..b4fd6ce05 100644 --- a/docs/blog/posts/git-sparse-checkout.md +++ b/docs/blog/posts/git-sparse-checkout.md @@ -18,17 +18,20 @@ 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 the wonderful -[`git-revision-date-localized`][git-revision-date-localized] plugin to display -[document contributors] 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], we were able to bring down checkout time to 2 seconds. +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], +we were able to bring down checkout time 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 From 950d1e41fb540a29fd785d00e73a1c5ae5e0a2f1 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 22 Sep 2023 21:02:51 +0200 Subject: [PATCH 19/33] Documentation --- docs/blog/posts/git-sparse-checkout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/posts/git-sparse-checkout.md b/docs/blog/posts/git-sparse-checkout.md index b4fd6ce05..e16b2a6ae 100644 --- a/docs/blog/posts/git-sparse-checkout.md +++ b/docs/blog/posts/git-sparse-checkout.md @@ -24,7 +24,7 @@ wonderful [`git-committers`][git-committers] and [`git-revision-date-localized`] [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], -we were able to bring down checkout time to 2 seconds. +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 From b1ee79b2620140722f0d9962d00cd47e4ff583a3 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 23 Sep 2023 09:30:15 +0200 Subject: [PATCH 20/33] Fixed out-of-sync ARIA attributes in navigation --- src/templates/assets/javascripts/components/sidebar/index.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/templates/assets/javascripts/components/sidebar/index.ts b/src/templates/assets/javascripts/components/sidebar/index.ts index 66bfe0919..82f3d03e9 100644 --- a/src/templates/assets/javascripts/components/sidebar/index.ts +++ b/src/templates/assets/javascripts/components/sidebar/index.ts @@ -24,6 +24,7 @@ import { Observable, Subject, animationFrameScheduler, + asyncScheduler, auditTime, combineLatest, defer, @@ -36,6 +37,7 @@ import { ignoreElements, map, mergeMap, + observeOn, takeUntil, tap, withLatestFrom @@ -202,6 +204,7 @@ export function mountSidebar( .pipe( mergeMap(label => fromEvent(label, "click") .pipe( + observeOn(asyncScheduler), map(() => label), takeUntil(done$) ) From 11b1c55ba11d5468ce7cc6d5468769253a1df644 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 23 Sep 2023 09:30:56 +0200 Subject: [PATCH 21/33] Improved navigation spacing with flex layout --- src/templates/assets/stylesheets/main/components/_nav.scss | 6 +----- .../assets/stylesheets/main/components/_status.scss | 1 - 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/src/templates/assets/stylesheets/main/components/_nav.scss b/src/templates/assets/stylesheets/main/components/_nav.scss index 8f68e2c85..89df734ff 100644 --- a/src/templates/assets/stylesheets/main/components/_nav.scss +++ b/src/templates/assets/stylesheets/main/components/_nav.scss @@ -93,6 +93,7 @@ // Navigation link &__link { display: flex; + gap: px2rem(8px); align-items: flex-start; margin-top: 0.625em; transition: color 125ms; @@ -131,11 +132,6 @@ flex-shrink: 0; height: 1.3em; fill: currentcolor; - - // Adjust spacing of next child - + * { - margin-inline-start: px2rem(8px); - } } // Navigation link on focus/hover diff --git a/src/templates/assets/stylesheets/main/components/_status.scss b/src/templates/assets/stylesheets/main/components/_status.scss index 4289654af..9e0960218 100644 --- a/src/templates/assets/stylesheets/main/components/_status.scss +++ b/src/templates/assets/stylesheets/main/components/_status.scss @@ -36,7 +36,6 @@ // Status .md-status { - margin-left: px2rem(4px); // Status icon &::after { From 62bd70a6d2b8ba91e163f8fdd039a202496a2fa5 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 23 Sep 2023 09:31:29 +0200 Subject: [PATCH 22/33] Fixed overflowing navigation on non-breaking words --- src/templates/assets/stylesheets/main/components/_nav.scss | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/templates/assets/stylesheets/main/components/_nav.scss b/src/templates/assets/stylesheets/main/components/_nav.scss index 89df734ff..4a3f341bf 100644 --- a/src/templates/assets/stylesheets/main/components/_nav.scss +++ b/src/templates/assets/stylesheets/main/components/_nav.scss @@ -173,6 +173,9 @@ // Stretch first child &:first-child { flex-grow: 1; + // Hack: if a very long word is used, it can push the arrow out of sight. + // Setting this property contains the text - see https://t.ly/E02vp + min-width: 0; } } From 208ac1ac3a8d60f56e12efa63d24d4fd8c1ae9e5 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 23 Sep 2023 09:31:48 +0200 Subject: [PATCH 23/33] Added smooth transition to sidebar navigation --- .../stylesheets/main/components/_nav.scss | 26 ++++++++++++++++--- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/src/templates/assets/stylesheets/main/components/_nav.scss b/src/templates/assets/stylesheets/main/components/_nav.scss index 4a3f341bf..b04501dc5 100644 --- a/src/templates/assets/stylesheets/main/components/_nav.scss +++ b/src/templates/assets/stylesheets/main/components/_nav.scss @@ -385,7 +385,7 @@ background-color: transparent; } - // Toggle for nested navigation + // Hide nested navigation &__toggle ~ & { display: flex; opacity: 0; @@ -522,14 +522,32 @@ } } - // Hide toggle for nested navigation + // Hide nested navigation &__toggle ~ & { - display: none; + display: grid; + grid-template-rows: 0fr; + visibility: collapse; + opacity: 0; + transition: + grid-template-rows 250ms cubic-bezier(0.86, 0, 0.07, 1), + opacity 250ms, + visibility 0ms 250ms; + + // Navigation list + > .md-nav__list { + overflow: hidden; + } } // Show nested navigation when toggle is active or indeterminate &__toggle:is(:checked, :indeterminate) ~ & { - display: block; + grid-template-rows: 1fr; + visibility: visible; + opacity: 1; + transition: + grid-template-rows 250ms cubic-bezier(0.86, 0, 0.07, 1), + opacity 150ms 100ms, + visibility 0ms; } // Hide navigation title in nested navigation From 8e019d23b6106c37ce92744ceae176eba0c7cb6a Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 23 Sep 2023 09:32:10 +0200 Subject: [PATCH 24/33] Fixed navigation expander not being focusable with keyboard --- src/templates/partials/nav-item.html | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/templates/partials/nav-item.html b/src/templates/partials/nav-item.html index 6fdfd1912..3bc14aa55 100644 --- a/src/templates/partials/nav-item.html +++ b/src/templates/partials/nav-item.html @@ -158,7 +158,12 @@ {% if nav_item.children | length > 1 %} -