Reloaded MkDocs Workflow

This is a simple action that can be used to create an MkDocs page and upload it to GitHub Pages.

.github/workflows/mkdocs.yml:

name: MkDocs Build and Deploy

on:
  workflow_dispatch:
  push:
    branches: [ main ]
    paths:
      - "mkdocs.yml"
      - "docs/**"
  pull_request:
    branches: [ main ]
    paths:
      - "mkdocs.yml"
      - "docs/**"

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    steps:
      - name: Deploy MkDocs
        uses: Reloaded-Project/devops-mkdocs@v1
        with:
          requirements: ./docs/requirements.txt
          publish-to-pages: ${{ github.event_name == 'push' }}
          checkout-current-repo: true

To use this action in your own repository:

1. Create a new workflow file (e.g., .github/workflows/mkdocs.yml) in your repository.
2. Copy the example usage code from above into the new workflow file.
3. If you have additional Python dependencies, create a requirements.txt file in your docs directory and list them there.

Ensure your MkDocs configuration file is named mkdocs.yml and located in the root of your repository (or update the config-file parameter in the workflow).

By default, the example workflow runs on:

• Pushes to the main branch that modify the mkdocs.yml file or files in the docs/ directory.
• Pull requests targeting the main branch that modify the mkdocs.yml file or files in the docs/ directory.
• Manual runs triggered via the workflow_dispatch event.

Modify the on section of the workflow as needed for your desired trigger conditions.

Find more examples in the tests.

- name: Deploy MkDocs
  uses: Reloaded-Project/devops-mkdocs@v1
  with:
    mkdocs-version: '9.5.24'

- name: Deploy MkDocs
  uses: Reloaded-Project/devops-mkdocs@v1
  with:
    pre-build-command: touch pre-build-bash-executed.txt
    pre-build-command-shell: bash

- name: Deploy MkDocs
  uses: Reloaded-Project/devops-mkdocs@v1
  with:
    output-directory: custom_site_dir

After a successful run, the generated static site will be available on the GitHub Pages site for your repository.

To find the URL:

1. Navigate to your repository on GitHub.
2. Go to the "Settings" tab.
3. Click on "Pages" in the side navigation.
4. The GitHub Pages URL will be listed at the top, in the format https://<user>.github.io/<repo>/.

Previous actions for MkDocs that I've used relied on virtualization, such as Docker. This was slow and sometimes inflexible, for example, the Docker image may not have the latest version of MkDocs if not configured properly.

This action directly invokes pip and python on the host machine for improved performance and flexibility.

Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request in this repository.

This project is licensed under the MIT License. See the LICENSE file for details.