feat(docs): integrate MkDocs with GitHub Pages deployment

Author: apiad

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc +%V)" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocstrings[python]
+      - run: mkdocs gh-deploy --force

makefile

@@ -1,6 +1,12 @@
-.PHONY: all test lint format
+.PHONY: all test lint format docs-serve docs-build
 
 all: test lint
 
 test:
 	@echo "Running tests..."
+
+docs-serve:
+	@mkdocs serve
+
+docs-build:
+	@mkdocs build

mkdocs.yml

@@ -0,0 +1,53 @@
+site_name: Gemini CLI Opinionated Framework
+site_url: https://apiad.github.io/starter
+repo_url: https://github.com/apiad/starter
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - search.suggest
+    - search.highlight
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          setup_commands:
+            - import sys
+            - sys.path.append(".")
+
+nav:
+  - Home: index.md
+  - Setup & Deployment: deploy.md
+  - Architecture & Design: design.md
+  - Development & Contribution: develop.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg

plans/mkdocs-integration.md

@@ -0,0 +1,53 @@
+# Execution Plan: MkDocs Integration for GitHub Pages
+
+This plan outlines the steps to integrate MkDocs into the project for automatic GitHub Pages deployment via CI/CD.
+
+### Objective
+Provide a professional, web-based documentation portal at `https://apiad.github.io/starter` that is automatically synchronized with the codebase via CI/CD.
+
+### Architectural Impact
+- Introduces MkDocs as a static site generator for project documentation.
+- Extends the GitHub Actions CI/CD pipeline to automatically build and deploy the `docs/` folder to GitHub Pages.
+- Enhances local development tooling (`makefile`) to easily build and preview documentation.
+
+### File Operations
+- **`mkdocs.yml`** (Create): Core configuration file for MkDocs.
+- **`.github/workflows/docs.yml`** (Create): GitHub Actions workflow for CI/CD deployment.
+- **`docs/index.md`** (Modify): Add a prominent "Setup" or "Quick Start" section.
+- **`makefile`** (Modify): Add `docs-serve` and `docs-build` commands.
+- **`TASKS.md`** (Update): Add the new task to the appropriate section.
+- **`journal/`** (Update): Add a journal entry to log the completion of this integration.
+
+### Step-by-Step Execution
+
+**Step 1: Create `mkdocs.yml`**
+Create a `mkdocs.yml` file in the repository root with the following configuration:
+- `site_name`: Gemini CLI Opinionated Framework
+- `site_url`: `https://apiad.github.io/starter`
+- `theme`: Material theme with dark mode support and search enabled.
+- `plugins`: Include `search` and `mkdocstrings` (with Python handler).
+- `nav`: Map the navigation to the existing `docs/` structure.
+
+**Step 2: Setup CI/CD Deployment**
+Create `.github/workflows/docs.yml` to automate deployment:
+- Trigger on `push` to the `main` branch.
+- Deploy to the `gh-pages` branch using `mkdocs gh-deploy --force`.
+
+**Step 3: Refine `docs/index.md`**
+- Add a prominent "Quick Start" section right after the philosophy to bring visibility to the primary installation command.
+- Ensure the Markdown is compatible with MkDocs Material.
+
+**Step 4: Update `makefile`**
+Add the following targets:
+- `docs-serve`: For local live-reloading preview.
+- `docs-build`: To generate the static site locally.
+
+**Step 5: Log Progress**
+- Update `TASKS.md`: Add an entry under the Archive for MkDocs integration.
+- Update the latest journal entry in `journal/` to log the changes.
+
+### Testing Strategy
+1. **Local Preview:** Run `make docs-serve` locally. Verify rendering, theme, and navigation.
+2. **Build Verification:** Run `make docs-build` to ensure the site builds without warnings.
+3. **CI/CD Testing:** Push to `main` and verify the GitHub Actions workflow completion.
+4. **Live Site Verification:** Visit `https://apiad.github.io/starter`.