Feedback on the "Publishing your Site" GitHub Actions section (Possible adjustment ideas)

[Andre601]

This is some small feedback on the GitHub Actions section in the "Publishing your site" page, which while already fairly good, could perhaps receive some smaller improvements.

Overall are there only 3 things I would like to address here.

The first one is the first step:

      - uses: actions/checkout@v4

This setup has the issue, that a fetch-depth of 1 is used by default, meaning only a shallow fetch is being performed.
This can cause problems if a user is using MkDocs plugins that utilize git to fetch information (Commit history). A prime example would be the git-localized-revision-date plugin, which would print warnings about inaccurate commit history.

It should be addressed (possibly in an annotation) that this problem could be caused and that a fix would be to apply a fetch-depth of 0:

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

The second point is on the step right afterwards:

      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com

This step is for the most part not necessary. The checkout action should've set up the git configuration already and most if not all actions required don't need a user setup. I assume this step is needed due to the reliance on the gh-deploy command of MkDocs?
If that is the case, then the next point would be a recommended change to consider for sure.

The final point is to not recommend the usage of mkdocs gh-deploy in GitHub Actions, especially given that it is mentioned later on anyways as its own section.
Instead, a direct deployment to GitHub Pages should be done here. This, however, would require some multiple adjustments to the example file like this (less condensed for better readability):

name: ci

on:
  push:
    branches:
      - master 
      - main

permissions:
  contents: read  # Adjusted from 'write'
  pages: write    # Added
  id-token: write # Added

# Used to avoid concurrency issues
concurrency:
  group: github-pages
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }} # Retrieved from deploy-pages action
    steps:
      - uses: actions/checkout@v4
      # Removed Git Credentials setup (Redundant)
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs build                      # Adjusted from 'mkdocs gh-deploy'
      - uses: actions/configure-pages@v5       # Added
      - uses: actions/upload-pages-artifact@v3 # Added
        with:
          path: 'site/'
      - uses: actions/deploy-pages@v4          # Added
        id: deployment

This setup would bring several benefits to the user:

• Pages are available imediatally after this action completed, since it won't require a separate workflow to deploy from a branch
• No separate branch is made for the sole purpose of hosting the site content.
• Other things could be done after page build and before deploy, which wouldn't be possible through gh-deploy.

This actions setup, while a bit bigger, would offer a better use of GitHub Actions.

I hope the changes can be considered.