Aller au contenu

Publication du site sur Internet

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

Je décris 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

Attention

La technique expliquée ici est une nouvelle manière de publier sur GitHub Pages. Cette technique est encore en Bêta, mais elle est plus simple à utiliser que la technique précédente et fonctionne déjà très bien.

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

Modifiez les paramètres des GitHub Pages en cliquant le menu Settings → Pages et définissez GitHub Actions comme source :

settings

Créez ensuite les dossiers .github et .github/workflows à la racine de votre projet

Ajoutez-y le fichiers de suivant:

.github/workflows/website.yml
name: publish-websites

on:
  workflow_dispatch:
  push:
  pull_request:

env:
  LECTURE_WEEK: 999
  SHOW_SOLUTION: 999

jobs:
  # Build site
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Set up Python 3
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install Poetry
        run: python -m pip install poetry==1.6.1
      - name: Cache the virtualenv
        uses: actions/cache@v3
        with:
          path: ./.venv
          key: ${{ runner.os }}-venv-${{ hashFiles('**/poetry.lock') }}
      - name: Install dependencies
        run: poetry install --no-root
      - name: Build site
        run: poetry run mkdocs build -d public
      - name: Upload pages artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: public

  # Deploy site to Github pages
  deploy:
    needs: build
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    permissions:
      # to deploy to Pages
      pages: write
      # to verify the deployment originates from an appropriate source
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Lors du prochain push avec ces nouveaux fichiers, l’action de github publiera le contenu de votre site sur GitHub Pages.

Vous obtenez l’URL à laquelle le site a été publié, en retournant dans Settings → Pages :

settings

ou en consultant le résultat de l’action :

result

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

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.

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:3.11-bookworm

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

cache:
  paths:
    - ".venv/"

before_script:
  - |
    apt-get update && \
      export DEBIAN_FRONTEND=noninteractive && \
      apt-get -y install --no-install-recommends \
    python3-brotli \
    python3-cffi \
    python3-pip \
    zip
  - pip install poetry==1.6.1
  - poetry install --no-root

# Build and publish main branch to GitLab pages
pages:
  stage: deploy
  script:
    - poetry run mkdocs build -d public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

# Build without publishing to detect breaking changes on non-main branches
test:
  stage: test
  script:
    - poetry run mkdocs build -d test
  artifacts:
    paths:
      - test
  rules:
    - if: $CI_COMMIT_BRANCH != "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 mkdocs.yml avec cette URL.

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.