Publish on GitHub pages

Author: mekanix

.github/workflows/pages.yml

@@ -0,0 +1,56 @@
+name: Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install \
+            mkdocs \
+            mkdocs-material \
+            mkdocs-awesome-pages-plugin \
+            pymdown-extensions
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -11,3 +11,4 @@ project.mk
 vars.mk
 
 site
+site/

README.md

@@ -1 +1,33 @@
-# doc
+# Freenit documentation
+
+This repository is prepared for publishing on GitHub Pages with MkDocs.
+
+## Local development
+
+Install the MkDocs dependencies and run:
+
+```sh
+mkdocs serve
+```
+
+To validate the generated site locally:
+
+```sh
+mkdocs build --strict
+```
+
+## GitHub Pages deployment
+
+This repository is named `freenit-framework.github.io`, so it behaves like a GitHub user/organization Pages repository.
+
+The MkDocs deployment guide explains that user/organization Pages deployments with `mkdocs gh-deploy` are intended to publish into a dedicated Pages repository/branch separate from the source repository. Because this repository stores the MkDocs source on `master`, deploying the built site back into that same branch with `mkdocs gh-deploy` would be the wrong workflow here.
+
+Instead, publishing is handled by GitHub Actions in [`.github/workflows/pages.yml`](/home/meka/repos/freenit-framework.github.io/.github/workflows/pages.yml). On each push to `master`, the workflow:
+
+1. installs MkDocs and the required plugins,
+2. builds the site with `mkdocs build --strict`,
+3. deploys the generated `site/` output to GitHub Pages.
+
+## One-time GitHub configuration
+
+In the GitHub repository settings, set Pages to use `GitHub Actions` as the source.

mkdocs.yml

@@ -1,4 +1,7 @@
 site_name: Freenit
+site_url: https://freenit-framework.github.io/
+repo_url: https://github.com/freenit-framework/freenit-framework.github.io
+repo_name: freenit-framework/freenit-framework.github.io
 theme:
   name: material
   logo: img/logo.png