Add Preview CI

.dockerignore

@@ -1 +1,5 @@
-_site
+.git
+.venv
+_site
+site
+__pycache__

.github/workflows/preview.yml

@@ -0,0 +1,53 @@
+name: Build preview
+
+on:
+  pull_request:
+  push:
+    branches:
+      - prepare-mkdocs-ci
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: preview-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: recursive
+
+      - name: Regenerate Organizations API documentation
+        run: sudo make graphql-docs
+
+      - name: Check generated documentation is current
+        run: |
+          git status --short --untracked-files=all -- .graphqlrc.yml graphql src/docs/integratie/org-api
+          test -z "$(git status --porcelain --untracked-files=all -- .graphqlrc.yml graphql src/docs/integratie/org-api)"
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.12.12
+          cache: pip
+
+      - name: Install dependencies
+        run: python -m pip install -r requirements.txt
+
+      - name: Check submodules are clean
+        run: git submodule foreach --recursive 'test -z "$(git status --porcelain)"'
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - name: Upload preview artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: site-${{ github.sha }}
+          path: site/
+          if-no-files-found: error
+          retention-days: 14

Dockerfile

@@ -1,6 +1,11 @@
-FROM jekyll/jekyll:3
-RUN gem install bundler -v 2.4.22
-COPY Gemfile Gemfile.lock ./
-RUN bundle install
+FROM python:3.12.12-slim-bookworm
+
+WORKDIR /docs
+
+COPY requirements.txt ./
+RUN python -m pip install --no-cache-dir -r requirements.txt
+
 COPY . .
-ENTRYPOINT ["bundle", "exec", "jekyll", "serve", "--host", "0.0.0.0"]
+
+EXPOSE 8000
+CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]

README.md

@@ -2,44 +2,52 @@
 
 This repository generates [https://developer.meemoo.be/](https://developer.meemoo.be/).
 
-## Build the docs locally
+## Run the docs locally
 
-First, [install Ruby 2.7.](https://www.ruby-lang.org/en/documentation/installation/)
-
-Next, install [Jekyll](https://jekyllrb.com/) and other dependencies from the `Gemfile` with 
+Install Python 3.12, then run:
 
 ```bash
-bundle install
+git submodule update --init --recursive
+python3.12 -m venv .venv
+. .venv/bin/activate
+python -m pip install -r requirements.txt
+mkdocs serve
 ```
 
-Finally, run
+Open `http://127.0.0.1:8000` to browse the docs.
+
+## Run the docs with Docker
+
+Build and run the preview image:
 
 ```bash
-bundle exec jekyll serve
+docker build -t meemoo-docs .
+docker run --rm -it -p 8000:8000 meemoo-docs
 ```
 
-## Build the docs via Docker
+Open `http://127.0.0.1:8000`. This image is for local preview only; production serves the static `site/` artifact.
 
-First, make sure that [Docker is installed](https://docs.docker.com/get-docker/).
+## Update the Organizations API documentation
 
-Next, build the Docker image:
+[Install Docker](https://docs.docker.com/get-docker/), then regenerate the committed Markdown from the current schema snapshot:
 
 ```bash
-docker build -t meemoo-docs .
+make graphql-docs
 ```
 
-Then, start the container serving the docs:
+To refresh the schema snapshot first, provide the URL of the introspection JSON:
 
 ```bash
-docker container run --rm -it -p 4000:4000 meemoo-docs
+make graphql-schema SCHEMA_URL=https://example.test/schema.json
+make graphql-docs
 ```
 
-Finally, go to `http://127.0.0.1:4000` using your preferred browser to browse the docs.
+Commit changes to `graphql/schema.json`, `graphql/introduction.md`, and the generated files under `src/docs/integratie/org-api/` together. Node.js and npm run inside `graphql/Dockerfile`; they are not host prerequisites.
 
 ## Convert legacy files
 
-Get pandoc
+Install Pandoc, then run:
 
-```
+```bash
 pandoc -s <file> -t markdown -o ./docs/output.md --wrap=none
 ```

graphql/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:22.15.0-alpine
+FROM node:24-alpine
 
 WORKDIR /app
 COPY package.json package-lock.json ./