8.7 KiB
Publishing your site
The great thing about hosting project documentation in a git repository is
the ability to deploy it automatically when new changes are pushed. MkDocs
makes this ridiculously simple.
GitHub Pages
If you're already hosting your code on GitHub, GitHub Pages is certainly the most convenient way to publish your project documentation. It's free of charge and pretty easy to set up.
with GitHub Actions
Using GitHub Actions you can automate the deployment of your project
documentation. At the root of your repository, create a new GitHub Actions
workflow, e.g. .github/workflows/ci.yml, and copy and paste the following
contents:
=== "Material for MkDocs"
``` yaml
name: ci # (1)!
on:
push:
branches:
- master # (2)!
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configure Git Credentials
run: |
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- uses: actions/setup-python@v5
with:
python-version: 3.x
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
- uses: actions/cache@v4
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
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@v4
- name: Configure Git Credentials
run: |
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- 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: 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].
Now, when a new commit is pushed to either the master or main branches,
the static site is automatically built and deployed. Push your changes to see
the workflow in action.
If the GitHub Page doesn't show up after a few minutes, go to the settings of
your repository and ensure that the publishing source branch for your GitHub
Page is set to gh-pages.
Your documentation should shortly appear at <username>.github.io/<repository>.
with MkDocs
If you prefer to deploy your project documentation manually, you can just invoke
the following command from the directory containing the mkdocs.yml file:
mkdocs gh-deploy --force
This will build your documentation and deploy it to a branch
gh-pages in your repository. See this overview in the MkDocs
documentation for more information. For a description of the
arguments, see the documentation for the command.
GitLab Pages
If you're hosting your code on GitLab, deploying to GitLab Pages can be done
by using the GitLab CI task runner. At the root of your repository, create a
task definition named .gitlab-ci.yml and copy and paste the following
contents:
=== "Material for MkDocs"
``` yaml
pages:
stage: deploy
image: python:latest
script:
- pip install mkdocs-material
- mkdocs build --site-dir public
artifacts:
paths:
- public
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```
=== "Insiders"
``` yaml
pages:
stage: deploy
image: python:latest
script: # (1)!
- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
- mkdocs build --site-dir public
artifacts:
paths:
- public
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```
1. Remember to set the `GH_TOKEN` environment variable to the value of your
[personal access token] when deploying [Insiders], which can be done
using [masked custom variables].
Now, when a new commit is pushed to the default branch (typically master or
main), the static site is automatically built and deployed. Commit and push
the file to your repository to see the workflow in action.
Your documentation should shortly appear at <username>.gitlab.io/<repository>.
Other
Since we can't cover all possible platforms, we rely on community contributed guides that explain how to deploy websites built with Material for MkDocs to other providers: