Publishing Your Site

Publishing your site

You can choose either automatic mode or manual mode, depending on your scenario. Both are very simple to operate.

Automatic - Via Workflow⚓︎

Automatic - Via Workflow

Many cloud servers support automatic deployment via workflows, which greatly simplifies the deployment process, you only need to push your source documents to a cloud repository to complete automatic deployment.

GitHub Pages⚓︎

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:

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-materialx-${{ env.cache_id }}
          path: ~/.cache # (4)!
          restore-keys: |
            mkdocs-materialx-
      - run: pip install mkdocs-materialx # (5)!
      - run: mkdocs gh-deploy --force

You can change the name to your liking.
At some point, GitHub renamed master to main. If your default branch
is named master, you can safely remove main, vice versa.
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.
Some MaterialX for MkDocs plugins use caching to speed up repeated
builds, and store the results in the ~/.cache directory.
This is the place to install further MkDocs plugins or Markdown
extensions with pip to be used during the build:
```
pip install \
  mkdocs-materialx \
  mkdocs-awesome-pages-plugin \
  ...
```

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>.

To publish your site on a custom domain, please refer to the MkDocs documentation.

Manual Deployment⚓︎

Manual Deployment

If you want to deploy your site without uploading source documents to a cloud repository (for sensitive documentation), you can instead upload only your locally built HTML site (site/) to a cloud server. The process is very straightforward.

GitHub Pages⚓︎

GitHub Pages

Navigate to your project directory in the terminal and run the following commands. No prior build is required - the commands will automatically build and upload your site:

MkDocsProperDocs

mkdocs gh-deploy --force

properdocs 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⚓︎

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:

.gitlab-ci.yml

pages:
  stage: deploy
  image: python:latest
  script:
    - pip install mkdocs-materialx
    - mkdocs build --site-dir public
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - ~/.cache/ # (1)!
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Some MaterialX for MkDocs plugins use caching to speed up
repeated builds, and store the results in the ~/.cache directory.

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 is not published under <username>.gitlab.io/<repository> by default since GitLab 17.4 ¹.
However, if you prefer a cleaner URL structure, such as <username>.gitlab.io/<repository>, you need to adjust your configuration.

To switch from a unique domain to the traditional URL structure, follow these steps:

Locate Your Repository
Go to Settings › Pages in the repository menu.
In the Unique domain settings section, uncheck the box labeled
Use unique domain.
Click Save changes to apply the update.

Now you can reach your documentation under <username>.gitlab.io/<repository>.

Other Platforms

In the server dashboard of your chosen platform, select file upload deployment, then select and upload the project's site directory.

Netlify⚓︎

The manual deployment interface for Netlify is shown below:

Release notes for Gitlab 17.4 ↩