Aller au contenu

Publication du site sur Internet

Pour rendre votre site disponible sur Internet, vous avez plusieurs solutions :

Je vais décrire ici la méthode pour utiliser les GitHub Pages et pour les Gitlab Pages, mais toutes les options ci-dessus sont possibles avec MkDocs.

Github Pages

Pour utiliser GitHub Pages, vous devez héberger votre projet dans un dépôt git de GitHub.

Créez ensuite un dossier .github à la racine de votre projet

Ajoutez-y les fichiers suivants pour définir l’action Mkdocs edu builder:

actions/mkdocs-edu/action.yml
# action.yml
name: 'Mkdocs edu builder'
description: 'Builds a Mkdocs website for HEIA-FR'
inputs:
  site-dir:
    description: 'public build directory'
    required: false
    default: '../public'
  config-file:
    description: 'config file'
    required: false
    default: 'config/mkdocs.yml'

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.site-dir }}
    - ${{ inputs.config-file }}
actions/mkdocs-edu/Dockerfile
FROM python:bullseye

# Install additional software
RUN apt-get update && \
    export DEBIAN_FRONTEND=noninteractive && \
    apt-get -y install --no-install-recommends \
  ghostscript \
  imagemagick \
  zip

# Make sure that ImageMagick can convert PDF to images
RUN sed -i '/disable ghostscript format types/,+6d' \
    /etc/ImageMagick-6/policy.xml

# Install Poetry
RUN pip install poetry

# Install entrypoint
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
actions/mkdocs-edu/entrypoint.sh
#!/bin/bash -l

set -o errexit
set -o pipefail
set -o nounset
# set -o xtrace

site_dir="${1:-public}"
config="${2:-config/mkdocs.yml}"

# Install mkdocs from .devcontainer in a sub-shell
cp -a .devcontainer/mkdocs-edu /
(cd /mkdocs-edu && poetry config virtualenvs.create false && poetry install)

python --version
mkdocs --version

mkdocs build --clean --config-file ${config} --site-dir ${site_dir}

Ainsi que le fichier suivant pour le workflow :

workflows/website.yml
name: publish-websites

on:
  workflow_dispatch:
  push:
    branches:
      - 'main'
    tags:
      - 'v*'

jobs:
  build-and-push-pages:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Build mkdocs site
        uses: ./.github/actions/mkdocs-edu

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Lors du prochain push avec ces nouveaux fichiers, l’action de github créera une nouvelle branche avec le contenu de votre site statique.

Afin de publier cette branche dans GitHub Pages, allez dans Settings → Pages et choisissez la branche gh-pages comme source de votre site :

settings

Après avoir sauvé cette configuration, modifiez encore le fichier config/mkdocs.yml avec l’URL que vous avez dans les settings :

config/mkdocs.yml
site_name: My Education Site
site_url: https://heia-fr.github.io/mkdocs-edu-howto/
...

Faites un commit et un push et votre site devrait être publié à l’URL adéquate.

Grâce aux GitHub Actions, votre site sera automatiquement publié lors de chaque push de la branche main du projet ou lors du push d’un tag commençant par “v”.

Gitlab Pages

Pour utiliser GitLab Pages, vous devez héberger votre projet dans un dépôt git de GitLab.

Créez ensuite un fichier .gitlab-ci.yml à la racine de votre projet avec le contenu suivant :

.gitlab-ci.yml
image: python:bullseye

pages:
  script:
    - |
      apt-get update && \
        export DEBIAN_FRONTEND=noninteractive && \
        apt-get -y install --no-install-recommends \
      ghostscript \
      imagemagick \
      libpango-1.0-0 \
      libpangoft2-1.0-0 \
      python3-brotli \
      python3-cffi \
      python3-pip \
      zip
    - sed -i '/disable ghostscript format types/,+6d' /etc/ImageMagick-6/policy.xml
    - pip install poetry
    - (cd .devcontainer/mkdocs-edu && poetry config virtualenvs.create false && poetry install)
    - python --version
    - mkdocs --version
    - mkdocs build --clean --config-file config/mkdocs.yml --site-dir ../public

  artifacts:
    paths:
      - public
  only:
    - main

Lors du prochain push avec ce nouveau fichier, le CI/CD de gitlab publiera votre site.

Allez dans Settings → Pages pour découvrir l’URL de votre site.

Modifiez le fichier config/mkdocs.yml avec cet URL.

config/mkdocs.yml
site_name: My Education Site
site_url: https://heia-fr.gitlab.io/mkdocs-edu-howto/
...

Faites un commit et un push pour activer le changement.

Grâce au GitLab CI/CD, votre site sera automatiquement publié lors de chaque push de la branche main du projet.