This GitHub action will deploy your MkDocs site as GitHub Pages, using the Material theme. It assumes that an mkdocs.yml file is present in the top-level directory and the source files (Markdown, etc.) are in the docs/ folder. You can use mhausenblas/mkdocs-template as a template.
Before you start, make sure you enable GitHub pages via the repo settings.
There are two methods for generating and building your gh-pages branch: use either a PERSONAL_TOKEN which is loaded with a personal access token containing repo privileges, or using GITHUB_TOKEN which is a token provided by the GITHUB API with sufficient privileges to perform repo-related operations.
Generate a personal access token (scope repo) and create a secret in your repository settings with the name PERSONAL_TOKEN and the value of the token generated.
Note that this is an account-level token that has access to update any repo owned by you, so be sure to avoid sharing it.
This action supports building and deploying with a GITHUB_TOKEN. This token is automatically generated by Github Actions when a workflow runs so it is convenient.
It is more secure than a personal token, since you never actually see the value of the GITHUB_TOKEN and also the GITHUB_TOKEN is scoped to only work for a single repo.
You may need to give the GITHUB_TOKEN write permission. Go to your repository's Settings > Actions > General > Workflow Permissions and select Read and write permissions.
Note that for this approach, Github Pages will be enabled in Settings but you will not have a URL displayed or environment tab yet. So change the Github Pages settings to another target and then back again to gh-pages (if that is your branch to serve) - then you will see a URL. This step is only needed on the first deploy and no action is needed later on.
In case this action should be used in a Github Enterprise environment you can overwrite the github.com domain with your corresponding Github Enterprise domain name by specifying the GITHUB_DOMAIN environment variable.
In case you want to push to another repository than origin define GITHUB_ORIGIN. Needs building with PERSONAL_TOKEN.
MkDocs can be deployed to github pages using a custom domain, if you populate a CUSTOM_DOMAIN environment variable. This will generate a CNAME file, which will be placed inside the /docs folder.
https://www.mkdocs.org/user-guide/deploying-your-docs/#custom-domains
This action supports deployment of mkdocs with different file path , if you populate a CONFIG_FILE environment variable. This is important if you have mkdocs file in another folder such as if you have mkdocs.yml in a path docs/mkdocs.yml. Without populating this, the deployment assumes that mkdocs.yml is on the root folder.
Some Python packages require C bindings. These packages can be installed using the EXTRA_PACKAGES variable. The EXTRA_PACKAGES variable will be passed to the apk add command of Alpine Linux before running pip install to install the Python packages.
If you use some mkdocs plugins like codeinclude then you need to define it as dependency in the typical python way with a requirements.txt file. In the sample above you need to add the line mkdocs-codeinclude-plugin. Then you need to link the file using the REQUIREMENTS variable.
name: Publish docs via GitHub Pages
on:
push:
branches:
- main
jobs:
build:
name: Deploy docs
runs-on: ubuntu-latest
steps:
- name: Checkout main
uses: actions/checkout@v4
with:
token: ${{ secrets.PAT_TOKEN }} # Uses Personal Access Token (PAT) for checkout, needed to push to another repository
- name: Deploy docs
uses: andi34/mkdocs-deploy-gh-pages@master
# Or use andi34/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# PERSONAL_TOKEN: ${{ secrets.PAT_TOKEN }}
CUSTOM_DOMAIN: optionaldomain.com
CONFIG_FILE: folder/mkdocs.yml
EXTRA_PACKAGES: build-base
# GITHUB_DOMAIN: github.myenterprise.com
# GITHUB_ORIGIN: destination-repository-username/destination-repository-name
REQUIREMENTS: folder/requirements.txt