1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-24 21:35:00 +01:00
mkdocs-material/docs/publishing-your-site.md
Uwe Schmidt dcb23d9a20
Update publishing-your-site.md
Remove fetch-depth for checkout action (revert)

Also update Insiders workflow.
2024-02-01 12:24:20 +01:00

239 lines
8.7 KiB
Markdown

# 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.
[GitHub Pages]: https://pages.github.com/
### 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>`.
[GitHub Actions]: https://github.com/features/actions
[MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
[personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[Insiders]: insiders/index.md
[built-in optimize plugin]: plugins/optimize.md
[GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
[publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
[manual page]: https://man7.org/linux/man-pages/man1/date.1.html
### 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].
[this overview in the MkDocs documentation]: https://www.mkdocs.org/user-guide/deploying-your-docs/#project-pages
[the documentation for the command]: https://www.mkdocs.org/user-guide/cli/#mkdocs-gh-deploy
## 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:
<div class="mdx-columns" markdown>
- [:simple-azuredevops: Azure][Azure]
- [:simple-cloudflarepages: Cloudflare Pages][Cloudflare Pages]
- [:simple-digitalocean: DigitalOcean][DigitalOcean]
- [:material-airballoon-outline: Fly.io][Flyio]
- [:simple-netlify: Netlify][Netlify]
- [:simple-vercel: Vercel][Vercel]
- [:simple-codeberg: Codeberg Pages][Codeberg Pages]
</div>
[GitLab Pages]: https://gitlab.com/pages
[GitLab CI]: https://docs.gitlab.com/ee/ci/
[masked custom variables]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
[default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html
[Azure]: https://bawmedical.co.uk/t/publishing-a-material-for-mkdocs-site-to-azure-with-automatic-branch-pr-preview-deployments/763
[Cloudflare Pages]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-cloudflare/
[DigitalOcean]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-digitalocean-app-platform/
[Flyio]: https://documentation.breadnet.co.uk/cloud/fly/mkdocs-on-fly/
[Netlify]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-netlify/
[Vercel]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-vercel/
[Codeberg Pages]: https://andre601.ch/blog/2023/11-05-using-codeberg-pages/