From ce52d58d830394e44d4c1d8828f540e537de36ac Mon Sep 17 00:00:00 2001 From: John Ajera Date: Fri, 14 Nov 2025 09:15:39 +1300 Subject: [PATCH] feat: initial commit first release --- .dockerignore | 23 ++++++++ .github/workflows/build-and-release.yml | 65 ++++++++++++++++++++++ .github/workflows/ci.yml | 27 +++++++++ .github/workflows/commitmsg-conform.yml | 11 ++++ .github/workflows/markdown-lint.yml | 14 +++++ .gitignore | 44 +++++++++++++++ Dockerfile | 18 ++++++ README.md | 73 ++++++++++++++++++++++++- scripts/build.sh | 59 ++++++++++++++++++++ test/docs/index.md | 8 +++ test/mkdocs.yml | 6 ++ 11 files changed, 347 insertions(+), 1 deletion(-) create mode 100644 .dockerignore create mode 100644 .github/workflows/build-and-release.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/commitmsg-conform.yml create mode 100644 .github/workflows/markdown-lint.yml create mode 100644 .gitignore create mode 100644 Dockerfile create mode 100755 scripts/build.sh create mode 100644 test/docs/index.md create mode 100644 test/mkdocs.yml diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..41b88b9 --- /dev/null +++ b/.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 + diff --git a/.github/workflows/build-and-release.yml b/.github/workflows/build-and-release.yml new file mode 100644 index 0000000..04da5a4 --- /dev/null +++ b/.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 }} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..360063f --- /dev/null +++ b/.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 diff --git a/.github/workflows/commitmsg-conform.yml b/.github/workflows/commitmsg-conform.yml new file mode 100644 index 0000000..8af1d71 --- /dev/null +++ b/.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 diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 0000000..034b809 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6ae02aa --- /dev/null +++ b/.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/ + diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..e6c82ac --- /dev/null +++ b/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"] + diff --git a/README.md b/README.md index cf61c04..35004a3 100644 --- a/README.md +++ b/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. diff --git a/scripts/build.sh b/scripts/build.sh new file mode 100755 index 0000000..81296df --- /dev/null +++ b/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 + diff --git a/test/docs/index.md b/test/docs/index.md new file mode 100644 index 0000000..68b5615 --- /dev/null +++ b/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! + diff --git a/test/mkdocs.yml b/test/mkdocs.yml new file mode 100644 index 0000000..62f53af --- /dev/null +++ b/test/mkdocs.yml @@ -0,0 +1,6 @@ +site_name: Test Documentation +theme: + name: material +nav: + - Home: index.md +