Plan: GitLab Pages Documentation Site¶

Publish project documentation to GitLab Pages using MkDocs Material with a dual-theme approach: an Enderman-inspired dark purple Minecraft theme for mod documentation, and a clean dark professional theme for project governance pages.

Goal¶

Automatically build and deploy a themed documentation site to GitLab Pages on every push to main that modifies documentation files. The repository remains the single source of truth; the Pages site is a read-only, styled mirror.

Branch¶

feature/docs-site — branched from main

Overview¶

flowchart TD
    PUSH["Push to main<br/>with doc changes"] --> CI_JOB["pages CI job"]
    CI_JOB --> COPY["Copy root-level .md files<br/>into docs/ directory"]
    COPY --> REWRITE["Fix relative links<br/>in copied files"]
    REWRITE --> BUILD["mkdocs build<br/>generates static HTML"]
    BUILD --> DEPLOY["GitLab Pages<br/>serves the site"]

Theming Approach¶

Single MkDocs Material site with per-page CSS scoping. The base theme is a dark professional look. Mod documentation pages opt into the Minecraft Enderman theme via YAML front matter.

Base Theme — Dark Professional¶

Applies to all pages by default. Clean, modern dark mode using MkDocs Material's slate scheme.

Scheme: slate — dark background
Primary: deep-purple — #7E56C2
Accent: teal — #009485
Font: Default Roboto
No Minecraft styling — standard Material Design

Used for: Contributing, Development Guidelines, Security Policy, Code of Conduct, License, Changelog

Minecraft Theme — Enderman / End Dimension¶

Applies only to pages with theme: minecraft in their YAML front matter. Layered on top of the dark base via CSS scoping.

Color palette inspiration — The End dimension and Enderman:

Element	Color	Hex	Inspiration
Headings	Ender purple	#C77DFF	Enderman eyes / End portal
Table headers	Deep obsidian purple	#4A148C	Obsidian blocks
Table header text	Ender glow	#E0B0FF	End crystal glow
Code block background	Void tint	rgba(126, 86, 194, 0.12)	End void
Code text	Light purple	#CE93D8	Chorus flower
Links on hover	Bright ender	#EA80FC	Ender pearl flash
Admonition borders	End stone accent	#9C27B0	Purpur block
Mermaid node fill	Deep purple	#4A148C	Obsidian
Mermaid node text	White	#FFFFFF	—
Mermaid arrows	Ender teal	#009485	Ender eye teal
Mermaid secondary	Dark purple	#6A1B9A	Purpur pillar

Minecraft emojis used in navigation and headings:

Emoji	Meaning	Used For
⛏️	Pickaxe	Home / main landing
🔮	Ender crystal	Architecture
🧱	Bricks	Development Guide
⚙️	Gear	CI/CD, Configuration
🚀	Rocket	Releasing
🐛	Bug	Debug Logging
🌈	Rainbow	Shader Compatibility
📦	Package	About / mod description
📋	Clipboard	Changelog
🔒	Lock	Security
🤝	Handshake	Contributing, Code of Conduct
📏	Ruler	Guidelines

Page Theme Assignments¶

Page	Theme	Front Matter
Home / Index	🎮 Minecraft	`theme: minecraft`
About — mod description	🎮 Minecraft	`theme: minecraft`
Architecture	🎮 Minecraft	`theme: minecraft`
Development Guide	🎮 Minecraft	`theme: minecraft`
CI/CD Pipeline	🎮 Minecraft	`theme: minecraft`
Configuration	🎮 Minecraft	`theme: minecraft`
Releasing	🎮 Minecraft	`theme: minecraft`
Debug Logging	🎮 Minecraft	`theme: minecraft`
Shader Compatibility	🎮 Minecraft	`theme: minecraft`
Contributing	📋 Professional	(no front matter)
Development Guidelines	📋 Professional	(no front matter)
Changelog	📋 Professional	(no front matter)
Security Policy	📋 Professional	(no front matter)
Code of Conduct	📋 Professional	(no front matter)
License	📋 Professional	(no front matter)

File Changes¶

New Files¶

File	Description
`mkdocs.yml`	MkDocs Material site configuration — theme, nav, extensions, palette
`docs/stylesheets/minecraft.css`	Enderman/End-themed CSS scoped to `.minecraft-theme` wrapper
`docs/overrides/main.html`	Template override — wraps Minecraft pages in theme container, injects Mermaid config
`docs/assets/logo.png`	Site logo for header — from existing `branding/` assets
`docs/assets/favicon.png`	Browser tab icon — from existing `branding/` assets

Modified Files¶

File	Change
`.gitlab-ci.yml`	Add `pages` stage and `pages` job
`docs/ci-cd.md`	Document the new Pages stage, job, and trigger rules; update pipeline diagram
`docs/index.md`	Add note that the documentation site is auto-generated
`docs/*.md` (mod pages)	Add `theme: minecraft` YAML front matter to 9 mod documentation pages

Detailed Steps¶

Step 1: Create `mkdocs.yml`¶

Site configuration at the project root:

site_name: Ansible Crafting
site_description: Craft from every chest in the room
site_url: https://starshadow.gitlab.io/games/minecraft/minecraft-ansible-crafting/

repo_url: https://gitlab.com/starshadow/games/minecraft/minecraft-ansible-crafting
repo_name: GitLab

theme:
  name: material
  custom_dir: docs/overrides
  palette:
    - scheme: slate
      primary: deep purple
      accent: teal
      toggle:
        icon: material/weather-night
        name: Switch to light mode
    - scheme: default
      primary: deep purple
      accent: teal
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
  logo: assets/logo.png
  favicon: assets/favicon.png
  icon:
    repo: fontawesome/brands/gitlab
  features:
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy

extra_css:
  - stylesheets/minecraft.css

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - toc:
      permalink: true
  - tables
  - attr_list
  - md_in_html

nav:
  - ⛏️ Home: index.md
  - 📦 About: about.md
  - 🔮 Mod Documentation:
    - 🏗️ Architecture: architecture.md
    - 🧱 Development Guide: development.md
    - ⚙️ CI/CD Pipeline: ci-cd.md
    - ⚡ Configuration: configuration.md
    - 🚀 Release Process: releasing.md
    - 🐛 Debug Logging: debug-logging.md
    - 🌈 Shader Compatibility: shader-compatibility.md
  - 📋 Project:
    - 🤝 Contributing: contributing.md
    - 📏 Development Guidelines: development-guidelines.md
    - 📋 Changelog: changelog.md
    - 🔒 Security: security.md
    - 🤝 Code of Conduct: code-of-conduct.md

Step 2: Create `docs/stylesheets/minecraft.css`¶

Enderman/End-themed CSS scoped to .minecraft-theme:

/* ==========================================================================
   Minecraft Enderman Theme — scoped to pages with theme: minecraft front matter
   Only affects content inside the .minecraft-theme wrapper div.
   ========================================================================== */

/* Headings — Ender purple glow */
.minecraft-theme h1,
.minecraft-theme h2,
.minecraft-theme h3 {
  color: #C77DFF !important;
}

.minecraft-theme h1 {
  border-bottom: 2px solid rgba(199, 125, 255, 0.3);
  padding-bottom: 0.3em;
}

/* Tables — Obsidian/End stone styling */
.minecraft-theme .md-typeset table:not(.highlighttable) th {
  background-color: #4A148C;
  color: #E0B0FF;
  border-color: #6A1B9A;
}

.minecraft-theme .md-typeset table:not(.highlighttable) td {
  border-color: rgba(126, 86, 194, 0.3);
}

.minecraft-theme .md-typeset table:not(.highlighttable) tr:hover td {
  background-color: rgba(126, 86, 194, 0.08);
}

/* Code — Void tint */
.minecraft-theme .md-typeset code {
  background-color: rgba(126, 86, 194, 0.15);
  color: #CE93D8;
}

.minecraft-theme .md-typeset pre > code {
  background-color: rgba(30, 0, 50, 0.6);
}

/* Links — Ender pearl flash on hover */
.minecraft-theme .md-typeset a:hover {
  color: #EA80FC;
}

/* Admonitions — Purpur block accent */
.minecraft-theme .md-typeset .admonition,
.minecraft-theme .md-typeset details {
  border-color: #9C27B0;
}

.minecraft-theme .md-typeset .admonition-title,
.minecraft-theme .md-typeset summary {
  background-color: rgba(156, 39, 176, 0.15);
}

/* Horizontal rules — subtle ender glow */
.minecraft-theme .md-typeset hr {
  border-color: rgba(199, 125, 255, 0.2);
}

Step 3: Create `docs/overrides/main.html`¶

Template override for per-page theme scoping and Mermaid configuration:

{% extends "base.html" %}

{% block content %}
{% if page.meta.theme == "minecraft" %}
<div class="minecraft-theme">
  {{ super() }}
</div>
<script>
  // Re-initialize Mermaid with Enderman/End colors for Minecraft-themed pages
  document.addEventListener('DOMContentLoaded', function() {
    if (typeof mermaid !== 'undefined') {
      mermaid.initialize({
        theme: 'base',
        themeVariables: {
          primaryColor: '#4A148C',
          primaryTextColor: '#E0B0FF',
          primaryBorderColor: '#6A1B9A',
          lineColor: '#009485',
          secondaryColor: '#6A1B9A',
          tertiaryColor: '#311B92',
          background: '#1a1a2e',
          fontFamily: 'Roboto, sans-serif',
          fontSize: '14px'
        }
      });
    }
  });
</script>
{% else %}
{{ super() }}
{% endif %}
{% endblock %}

Step 4: Add front matter to mod documentation pages¶

Add theme: minecraft YAML front matter to the top of each mod documentation page. Example for docs/architecture.md:

---
theme: minecraft
---

# Architecture Overview
...

Pages receiving front matter: - docs/index.md - docs/architecture.md - docs/ci-cd.md - docs/configuration.md - docs/development.md - docs/releasing.md - docs/debug-logging.md - docs/shader-compatibility.md

Pages not receiving front matter (professional theme): - CONTRIBUTING.md (copied to docs/contributing.md) - GUIDELINES.md (copied to docs/development-guidelines.md) - CHANGELOG.md (copied to docs/changelog.md) - SECURITY.md (copied to docs/security.md) - CODE_OF_CONDUCT.md (copied to docs/code-of-conduct.md)

Step 5: Copy branding assets¶

Copy or symlink logo and favicon from branding/ to docs/assets/: - docs/assets/logo.png - docs/assets/favicon.png

Step 6: Update `.gitlab-ci.yml`¶

Add a pages stage and job. GitLab Pages requires the job to be named exactly pages and output to public/:

stages:
  - lint
  - build
  - release
  - deploy
  - pages          # new

pages:
  stage: pages
  image: python:3.12-slim
  before_script:
    - pip install mkdocs-material
  script:
    # Copy root-level docs into docs/ for MkDocs
    - cp README.md docs/about.md
    - cp CONTRIBUTING.md docs/contributing.md
    - cp GUIDELINES.md docs/development-guidelines.md
    - cp CHANGELOG.md docs/changelog.md
    - cp SECURITY.md docs/security.md
    - cp CODE_OF_CONDUCT.md docs/code-of-conduct.md
    # Fix relative links in copied files
    # Root files reference docs/ paths like docs/ci-cd.md → ci-cd.md
    # Root files reference sibling files like CONTRIBUTING.md → contributing.md
    - sed -i 's|(docs/|(|g' docs/about.md docs/contributing.md docs/development-guidelines.md
    - sed -i 's|(../|(|g' docs/about.md docs/contributing.md docs/development-guidelines.md
    - sed -i 's|development.md|development.md|g' docs/contributing.md
    - sed -i 's|CONTRIBUTING.md|contributing.md|g' docs/about.md docs/development-guidelines.md
    - sed -i 's|GUIDELINES.md|development-guidelines.md|g' docs/about.md docs/contributing.md
    - sed -i 's|README.md|about.md|g' docs/contributing.md docs/development-guidelines.md
    - sed -i 's|CHANGELOG.md|changelog.md|g' docs/about.md docs/contributing.md docs/development-guidelines.md
    - sed -i 's|SECURITY.md|security.md|g' docs/about.md
    - sed -i 's|CODE_OF_CONDUCT.md|code-of-conduct.md|g' docs/about.md docs/contributing.md
    # Build the site
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - docs/**/*
        - mkdocs.yml
        - README.md
        - CONTRIBUTING.md
        - GUIDELINES.md
        - CHANGELOG.md
        - SECURITY.md
        - CODE_OF_CONDUCT.md
  allow_failure: true

Step 7: Update `docs/ci-cd.md`¶

Update the pipeline overview Mermaid diagram to include the Pages stage
Add a new ### 5. Pages subsection under Stages
Add pages row to the Job Trigger Matrix table
Add a ### Pages Build Fails troubleshooting entry

Step 8: Update `docs/index.md`¶

Add a note below the opening paragraph:

📖 Documentation site: This documentation is automatically published to GitLab Pages on every push to main. The site is read-only — all edits should be made in the repository.

flowchart TD
    subgraph Minecraft Theme
        HOME["⛏️ Home"]
        ABOUT["📦 About"]
        ARCH["🏗️ Architecture"]
        DEV["🧱 Development Guide"]
        CICD["⚙️ CI/CD Pipeline"]
        CONFIG["⚡ Configuration"]
        REL["🚀 Release Process"]
        DEBUG["🐛 Debug Logging"]
        SHADER["🌈 Shader Compatibility"]
    end

    subgraph Professional Theme
        CONTRIB["🤝 Contributing"]
        GUIDE["📏 Dev Guidelines"]
        CHANGE["📋 Changelog"]
        SEC["🔒 Security"]
        COC["🤝 Code of Conduct"]
    end

Testing Strategy¶

Local preview — run mkdocs serve locally to preview the site with live reload; verify both themes render correctly
Link validation — check that cross-references between mod pages and professional pages work in both directions
Mermaid verification — confirm all existing Mermaid diagrams render on both themed and unthemed pages
Mobile responsiveness — verify the site looks good on mobile viewports
CI validation — after merging to main, verify the pages job runs and the site deploys to GitLab Pages
Idempotency — push to main without doc changes and verify the job skips via changes: filter

Risks and Mitigations¶

Risk	Mitigation
`pymdownx.superfences` Mermaid rendering differs from GitLab native	Test all existing diagrams locally with `mkdocs serve` before merging
Copied root-level files have broken links	Explicit sed substitutions for each known cross-reference; test locally
`pages` job name conflicts with existing GitLab Pages config	This project has no existing Pages config; the `pages` job name is reserved by GitLab for Pages deployment
Minecraft CSS bleeds into professional pages	CSS is scoped to `.minecraft-theme` wrapper; professional pages never get the wrapper div
Font licensing for Minecraft pixel font	Use a free alternative like Silkscreen or VT323 from Google Fonts, or omit custom font and rely on color/styling alone
`changes:` filter misses a new doc file	Update the `changes:` list when adding new documentation files

Commit Plan¶

All changes in a single commit on the feature/docs-site branch:

feat(docs): add GitLab Pages documentation site with MkDocs Material

- Add mkdocs.yml with dual-theme configuration
- Add Enderman/End-inspired Minecraft CSS for mod documentation pages
- Add template override for per-page theme scoping and Mermaid theming
- Add pages CI job to .gitlab-ci.yml for automated deployment
- Add theme: minecraft front matter to mod documentation pages
- Update docs/ci-cd.md with Pages stage documentation
- Update docs/index.md with documentation site note

Future Enhancements¶

These are out of scope for this branch but could be added later:

Minecraft pixel font — add a web font like Silkscreen for headings on Minecraft-themed pages
Custom admonition icons — replace default Material icons with Minecraft block/item icons
Version selector — use the mike MkDocs plugin to serve docs per Minecraft version
Custom 404 page — Minecraft-themed "You died!" 404 page
Social cards — auto-generated Open Graph preview images with Minecraft styling
Search analytics — track what users search for to improve documentation