From 86fbd9a2e76364a976b9c39d651783db6e2a78e8 Mon Sep 17 00:00:00 2001 From: Daniel Webber Date: Thu, 14 Sep 2023 22:53:40 +0800 Subject: [PATCH 1/5] Add CI Configuration part for `enable creation date` --- docs/setup/adding-a-git-repository.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index df8fb9390..d38a366b6 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -229,6 +229,9 @@ The following configuration options are supported: enable_creation_date: true ``` + !!! note + To make this configuration work properly on your documentation site, you also need to do the CI configuration as described in the [git-revision-date-localized](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments) documentation. + [`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+git-revision-date-localized.fallback_to_build_date } : :octicons-milestone-24: Default: `false` – Enables falling back to From 8c1ead363095c4fca774af0aa7454ce6b44553b7 Mon Sep 17 00:00:00 2001 From: Daniel Webber Date: Thu, 14 Sep 2023 23:19:53 +0800 Subject: [PATCH 2/5] Add example with Github Actions --- docs/setup/adding-a-git-repository.md | 101 ++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index d38a366b6..be6b9bb22 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -232,6 +232,107 @@ The following configuration options are supported: !!! note To make this configuration work properly on your documentation site, you also need to do the CI configuration as described in the [git-revision-date-localized](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments) documentation. + [With Github Actions](../publishing-your-site.md#with-github-actions): + + === "Material for MkDocs" + + ``` yaml hl_lines="14 15" + name: ci # (1)! + on: + push: + branches: + - master # (2)! + - main + permissions: + contents: write + jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)! + - uses: actions/cache@v3 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install mkdocs-material # (4)! + - run: mkdocs gh-deploy --force + ``` + + 1. You can change the name to your liking. + + 2. At some point, GitHub renamed `master` to `main`. If your default branch + is named `master`, you can safely remove `main`, vice versa. + + 3. Store the `cache_id` environmental variable to access it later during cache + `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`. + + - The `--utc` option makes sure that each workflow runner uses the same time zone. + - The `%V` format assures a cache update once a week. + - You can change the format to `%F` to have daily cache updates. + + You can read the [manual page] to learn more about the formatting options of the `date` command. + + 4. This is the place to install further [MkDocs plugins] or Markdown + extensions with `pip` to be used during the build: + + ``` sh + pip install \ + mkdocs-material \ + mkdocs-awesome-pages-plugin \ + ... + ``` + + === "Insiders" + + ``` yaml hl_lines="15 16" + name: ci + on: + push: + branches: + - master + - main + permissions: + contents: write + jobs: + deploy: + runs-on: ubuntu-latest + if: github.event.repository.fork == false + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v3 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: apt-get install pngquant # (1)! + - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git + - run: mkdocs gh-deploy --force + env: + GH_TOKEN: ${{ secrets.GH_TOKEN }} # (2)! + ``` + + 1. This step is only necessary if you want to use the + [built-in optimize plugin] to automatically compress images. + + 2. Remember to set the `GH_TOKEN` environment variable to the value of your + [personal access token] when deploying [Insiders], which can be done + using [GitHub secrets]. + [`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+git-revision-date-localized.fallback_to_build_date } : :octicons-milestone-24: Default: `false` – Enables falling back to From 9c8ff640848c9b9fc1baa0dc97b965131add69dc Mon Sep 17 00:00:00 2001 From: Daniel Webber Date: Thu, 14 Sep 2023 23:21:40 +0800 Subject: [PATCH 3/5] Change content --- docs/setup/adding-a-git-repository.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index be6b9bb22..d861bbfe5 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -230,7 +230,7 @@ The following configuration options are supported: ``` !!! note - To make this configuration work properly on your documentation site, you also need to do the CI configuration as described in the [git-revision-date-localized](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments) documentation. + If you are deploying through a CI system, please do the CI configuration as described in the [git-revision-date-localized](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments) documentation. [With Github Actions](../publishing-your-site.md#with-github-actions): From a26863a3f48a9d329987cec34a402cf55e663bdd Mon Sep 17 00:00:00 2001 From: Daniel Webber Date: Fri, 15 Sep 2023 10:42:26 +0800 Subject: [PATCH 4/5] Clarify --- docs/setup/adding-a-git-repository.md | 103 +------------------------- 1 file changed, 1 insertion(+), 102 deletions(-) diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index d861bbfe5..735df7033 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -230,108 +230,7 @@ The following configuration options are supported: ``` !!! note - If you are deploying through a CI system, please do the CI configuration as described in the [git-revision-date-localized](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments) documentation. - - [With Github Actions](../publishing-your-site.md#with-github-actions): - - === "Material for MkDocs" - - ``` yaml hl_lines="14 15" - name: ci # (1)! - on: - push: - branches: - - master # (2)! - - main - permissions: - contents: write - jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 - - uses: actions/setup-python@v4 - with: - python-version: 3.x - - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)! - - uses: actions/cache@v3 - with: - key: mkdocs-material-${{ env.cache_id }} - path: .cache - restore-keys: | - mkdocs-material- - - run: pip install mkdocs-material # (4)! - - run: mkdocs gh-deploy --force - ``` - - 1. You can change the name to your liking. - - 2. At some point, GitHub renamed `master` to `main`. If your default branch - is named `master`, you can safely remove `main`, vice versa. - - 3. Store the `cache_id` environmental variable to access it later during cache - `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`. - - - The `--utc` option makes sure that each workflow runner uses the same time zone. - - The `%V` format assures a cache update once a week. - - You can change the format to `%F` to have daily cache updates. - - You can read the [manual page] to learn more about the formatting options of the `date` command. - - 4. This is the place to install further [MkDocs plugins] or Markdown - extensions with `pip` to be used during the build: - - ``` sh - pip install \ - mkdocs-material \ - mkdocs-awesome-pages-plugin \ - ... - ``` - - === "Insiders" - - ``` yaml hl_lines="15 16" - name: ci - on: - push: - branches: - - master - - main - permissions: - contents: write - jobs: - deploy: - runs-on: ubuntu-latest - if: github.event.repository.fork == false - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 - - uses: actions/setup-python@v4 - with: - python-version: 3.x - - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV - - uses: actions/cache@v3 - with: - key: mkdocs-material-${{ env.cache_id }} - path: .cache - restore-keys: | - mkdocs-material- - - run: apt-get install pngquant # (1)! - - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git - - run: mkdocs gh-deploy --force - env: - GH_TOKEN: ${{ secrets.GH_TOKEN }} # (2)! - ``` - - 1. This step is only necessary if you want to use the - [built-in optimize plugin] to automatically compress images. - - 2. Remember to set the `GH_TOKEN` environment variable to the value of your - [personal access token] when deploying [Insiders], which can be done - using [GitHub secrets]. + If you are deploying through a CI system, you might need to adjust your CI settings when fetching the code. For more information, see [git-revision-date-localized](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments). [`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+git-revision-date-localized.fallback_to_build_date } From ace053fbb1042ca771a1371bf91a8f21a60ad815 Mon Sep 17 00:00:00 2001 From: Daniel Webber Date: Fri, 15 Sep 2023 10:56:00 +0800 Subject: [PATCH 5/5] Clarify --- docs/setup/adding-a-git-repository.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index c4597b650..65ec48379 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -222,6 +222,9 @@ The following configuration options are supported: enable_creation_date: true ``` + !!! note + If you are deploying through a CI system, you might need to adjust your CI settings when fetching the code. For more information, see [git-revision-date-localized](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments). + : Enables falling back to