feat: initial commit

.dockerignore

@@ -0,0 +1,23 @@
+.git
+.gitignore
+.github
+.vscode
+.devcontainer
+README.md
+LICENSE
+*.md
+.DS_Store
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info
+dist
+build
+test
+site
+docs
+

.github/workflows/build-and-release.yml

@@ -0,0 +1,65 @@
+name: Build and Release
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Create Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: ""
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: false
+          tags: mkdocs-material-image:test
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/commitmsg-conform.yml

@@ -0,0 +1,11 @@
+name: Commit Message Conformance
+on:
+  pull_request: {}
+permissions:
+  statuses: write
+  checks: write
+  contents: read
+  pull-requests: read
+jobs:
+  commitmsg-conform:
+    uses: actionsforge/actions/.github/workflows/commitmsg-conform.yml@main

.github/workflows/markdown-lint.yml

@@ -0,0 +1,14 @@
+name: Markdown Lint
+
+on:
+  pull_request: {}
+
+permissions:
+  statuses: write
+  checks: write
+  contents: read
+  pull-requests: read
+
+jobs:
+  markdown-lint:
+    uses: actionsforge/actions/.github/workflows/markdown-lint.yml@main

.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.log
+
+# MkDocs
+site/
+

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.13-slim
+
+# Set working directory
+WORKDIR /docs
+
+# Install mkdocs and mkdocs-material
+RUN pip install --no-cache-dir \
+    mkdocs \
+    mkdocs-material \
+    mkdocs-minify-plugin \
+    mkdocs-redirects
+
+# Expose the default mkdocs port
+EXPOSE 8000
+
+# Set entrypoint to mkdocs serve
+ENTRYPOINT ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]
+

README.md

@@ -1,2 +1,73 @@
 # mkdocs-material-image
-Build and serve MkDocs Material documentation in a single Docker image
+
+![CI](https://github.com/platformfuzz/mkdocs-material-image/actions/workflows/ci.yml/badge.svg)
+![Build and Release](https://github.com/platformfuzz/mkdocs-material-image/actions/workflows/build-and-release.yml/badge.svg)
+
+Build and serve MkDocs Material documentation in a single Docker image.
+
+## Overview
+
+This repository contains a Docker image based on Python 3.13 with MkDocs and MkDocs Material pre-installed. The image is automatically built and published to GitHub Container Registry (GHCR) via GitHub Actions.
+
+## Quick Start
+
+### Prerequisites
+
+Your documentation should be in a `docs` directory with:
+
+- `mkdocs.yml` - MkDocs configuration file
+- `docs/` - Your documentation source files
+
+### Using the Pre-built Image
+
+Pull and run the image from GitHub Container Registry:
+
+```bash
+docker pull ghcr.io/platformfuzz/mkdocs-material-image:latest
+docker run -p 8000:8000 -v $(pwd)/docs:/docs ghcr.io/platformfuzz/mkdocs-material-image:latest
+```
+
+Then open your browser to `http://localhost:8000` to view your documentation.
+
+## Local Testing
+
+```bash
+docker build -t mkdocs-material-image:latest .
+docker run -p 8000:8000 -v $(pwd)/test:/docs mkdocs-material-image:latest
+```
+
+## CI/CD
+
+The GitHub Actions workflow builds and pushes the image to GHCR on push to main or when tags are created.
+
+## Project Structure
+
+```plaintext
+.
+├── Dockerfile                 # Docker image definition
+├── .dockerignore             # Files excluded from Docker build
+├── .github/
+│   └── workflows/
+│       └── build-and-release.yml  # CI/CD workflow
+├── .vscode/
+│   ├── settings.json         # VS Code settings
+│   └── extensions.json       # Recommended extensions
+├── test/                     # Test documentation for local testing
+│   ├── mkdocs.yml
+│   └── docs/
+└── README.md                 # This file
+```
+
+## Included Packages
+
+The Docker image includes:
+
+- Python 3.13
+- MkDocs
+- MkDocs Material
+- MkDocs Minify Plugin
+- MkDocs Redirects Plugin
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

scripts/build.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+set -e
+
+# Script to build Docker image for mkdocs-material
+# Can be used both locally and in CI/CD
+
+IMAGE_NAME="mkdocs-material-image"
+REGISTRY="ghcr.io/platformfuzz"
+FULL_IMAGE_NAME="${REGISTRY}/${IMAGE_NAME}"
+
+# Detect version from git tag or VERSION file
+if [ -n "${GITHUB_REF}" ] && [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+    # In GitHub Actions with a tag
+    VERSION="${GITHUB_REF#refs/tags/}"
+    # Remove 'v' prefix if present
+    VERSION="${VERSION#v}"
+elif git describe --tags --exact-match HEAD 2>/dev/null; then
+    # Local: git tag exists
+    VERSION=$(git describe --tags --exact-match HEAD)
+    VERSION="${VERSION#v}"
+elif [ -f VERSION ]; then
+    # Fallback to VERSION file
+    VERSION=$(cat VERSION | tr -d '[:space:]')
+else
+    # Default version
+    VERSION="latest"
+fi
+
+# Get git commit SHA (short)
+COMMIT_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+
+echo "Building Docker image..."
+echo "Version: ${VERSION}"
+echo "Commit SHA: ${COMMIT_SHA}"
+
+# Build the image
+docker build -t "${FULL_IMAGE_NAME}:${VERSION}" \
+             -t "${FULL_IMAGE_NAME}:latest" \
+             -t "${FULL_IMAGE_NAME}:${COMMIT_SHA}" \
+             .
+
+echo "Build complete!"
+echo "Image tags:"
+echo "  - ${FULL_IMAGE_NAME}:${VERSION}"
+echo "  - ${FULL_IMAGE_NAME}:latest"
+echo "  - ${FULL_IMAGE_NAME}:${COMMIT_SHA}"
+
+# If in CI and we have credentials, push the image
+if [ -n "${GITHUB_ACTIONS}" ] && [ -n "${GITHUB_TOKEN}" ]; then
+    echo "Pushing images to registry..."
+    echo "${GITHUB_TOKEN}" | docker login ghcr.io -u "${GITHUB_ACTOR}" --password-stdin
+
+    docker push "${FULL_IMAGE_NAME}:${VERSION}"
+    docker push "${FULL_IMAGE_NAME}:latest"
+    docker push "${FULL_IMAGE_NAME}:${COMMIT_SHA}"
+
+    echo "Images pushed successfully!"
+fi
+

test/docs/index.md

@@ -0,0 +1,8 @@
+# Test Documentation
+
+This is a minimal test setup for local testing of the mkdocs-material-image.
+
+## Getting Started
+
+If you can see this page, the Docker image is working correctly!
+

test/mkdocs.yml

@@ -0,0 +1,6 @@
+site_name: Test Documentation
+theme:
+  name: material
+nav:
+  - Home: index.md
+