ci: deploy mkdocs on gh pages

Author: camilamaia

.github/workflows/deploy-pages.yml

@@ -0,0 +1,56 @@
+name: Deploy documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - hub-conhecimento
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 #v7.0.0
+
+      - name: Setup Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 #v6.3.0
+        with:
+          python-version: '3.13'
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 #v8.2.0
+        with:
+          version: latest
+
+      - name: Install dependencies
+        run: uv sync --group dev --no-install-project
+
+      - name: Build documentation
+        run: uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 #v5.0.0
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 #v5.0.0

Makefile

@@ -18,6 +18,11 @@ clean:
 	@echo "Cleaning generated files..."
 	@rm -rf site
 
+.PHONY: deploy
+deploy:
+	@echo "Deploying documentation to GitHub Pages..."
+	@uv run mkdocs gh-deploy --force
+
 .PHONY: format
 format:
 	@uv run ruff format .

RELEASING.md

@@ -0,0 +1,59 @@
+# Deploy do site
+
+Este projeto publica a documentação com MkDocs no GitHub Pages.
+
+[English Version](RELEASING_EN.md)
+
+## Pré-requisitos
+
+- Repositório público no GitHub
+- Acesso para habilitar GitHub Pages
+- Dependências do projeto instaladas com `uv`
+
+## Build local
+
+Para validar o site localmente, rode:
+
+```bash
+uv sync --group dev --no-install-project
+uv run mkdocs build
+```
+
+Para subir um servidor local:
+
+```bash
+uv run mkdocs serve
+```
+
+## Deploy automático
+
+O fluxo de publicação está configurado para rodar no GitHub Actions sempre que houver push nas branches `main` e `hub-conhecimento`.
+
+O workflow gera o site estático e publica o conteúdo no GitHub Pages.
+
+## Deploy manual
+
+Também é possível publicar manualmente com:
+
+```bash
+make deploy
+```
+
+Esse comando executa:
+
+```bash
+uv run mkdocs gh-deploy --force
+```
+
+## Configuração no GitHub
+
+1. Acesse as configurações do repositório no GitHub.
+2. Entre em "Pages".
+3. Em "Build and deployment", selecione "GitHub Actions".
+4. Faça o push das alterações para disparar o deploy.
+
+A URL pública esperada é:
+
+```text
+https://cumbucadev.github.io/NOSS/
+```

RELEASING_EN.md

@@ -0,0 +1,59 @@
+# Site deployment
+
+This project publishes the documentation with MkDocs on GitHub Pages.
+
+[Versão em Português](RELEASING.md)
+
+## Prerequisites
+
+- Public repository on GitHub
+- Permission to enable GitHub Pages
+- Project dependencies installed with `uv`
+
+## Local build
+
+To validate the site locally, run:
+
+```bash
+uv sync --group dev --no-install-project
+uv run mkdocs build
+```
+
+To start a local server:
+
+```bash
+uv run mkdocs serve
+```
+
+## Automatic deployment
+
+The publication workflow is configured to run in GitHub Actions whenever there is a push to the `main` and `hub-conhecimento` branches.
+
+The workflow builds the static site and publishes it to GitHub Pages.
+
+## Manual deployment
+
+You can also publish manually with:
+
+```bash
+make deploy
+```
+
+This command runs:
+
+```bash
+uv run mkdocs gh-deploy --force
+```
+
+## GitHub configuration
+
+1. Open the repository settings on GitHub.
+2. Go to "Pages".
+3. In "Build and deployment", select "GitHub Actions".
+4. Push the changes to trigger the deployment.
+
+The expected public URL is:
+
+```text
+https://cumbucadev.github.io/NOSS/
+```

mkdocs.yml

@@ -1,4 +1,5 @@
 site_name: NOSS
+site_url: https://cumbucadev.github.io/NOSS/
 repo_url: https://github.com/cumbucadev/NOSS
 repo_name: cumbucadev/NOSS
 edit_uri: edit/main/docs/