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 namePERSONAL_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 theGITHUB_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 theGITHUB_DOMAIN
environment variable.
- 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 by default will be placed inside the/docs
folder. - Using the
CUSTOM_DOCS
environment variable will change this folder, and should match thedocs_dir
in yourmkdocs.yml
file.
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 havemkdocs.yml
in a pathdocs/mkdocs.yml
. Without populating this, the deployment assumes thatmkdocs.yml
is on the root folder.
- Some Python packages require C bindings. These packages can be installed using the
EXTRA_PACKAGES
variable. TheEXTRA_PACKAGES
variable will be passed to theapk add
command of Alpine Linux before runningpip 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 arequirements.txt
file. In the sample above you need to add the linemkdocs-codeinclude-plugin
. Then you need to link the file using theREQUIREMENTS
variable.
name: Publish MkDocs Site via GitHub Pages
on:
push:
branches:
- main
jobs:
build:
name: Deploy docs
runs-on: ubuntu-latest
steps:
- name: Checkout main
uses: actions/checkout@v2
- name: Deploy docs
uses: mhausenblas/mkdocs-deploy-gh-pages@master
# Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CUSTOM_DOMAIN: optionaldomain.com
CUSTOM_DOCS: coolfolder # Only used if CUSTOM_DOMAIN and a custom 'docs_dir' are set
CONFIG_FILE: folder/mkdocs.yml
EXTRA_PACKAGES: build-base
REQUIREMENTS: folder/requirements.txt
# GITHUB_DOMAIN: github.myenterprise.com