Skip to content

Commit 2ea393e

Browse files
RainPPRRainPPR
committed
Update
1 parent bd264a8 commit 2ea393e

File tree

2 files changed

+114
-49
lines changed

2 files changed

+114
-49
lines changed

‎Dockerfile‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,9 @@ RUN pip install --no-cache-dir -r requirements.txt
1515
WORKDIR /app
1616

1717
COPY scripts/ /app/scripts/
18-
COPY mkdocs-build.sh /usr/local/bin/mkdocs-build
19-
RUN chmod +x /usr/local/bin/mkdocs-build
18+
19+
COPY --chmod=755 mkdocs-build.sh /usr/local/bin/mkdocs-build
20+
COPY --chmod=755 mkdocs-serve.sh /usr/local/bin/mkdocs-serve
21+
COPY --chmod=755 zensical-serve.sh /usr/local/bin/zensical-serve
2022

2123
CMD ["/usr/local/bin/mkdocs-build"]

‎README.md‎

Lines changed: 110 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,143 @@
11
# MkDocs Exporter Docker
22

33
[![Docker Image](https://github.com/raineblog/mkdocs-docker/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/raineblog/mkdocs-docker/actions/workflows/docker-publish.yml)
4-
[![Registry](https://img.shields.io/badge/Container-GHCR-blue)](https://github.com/raineblog/mkdocs-docker/pkgs/container/mkdocs-docker)
5-
6-
A streamlined, Dockerized MkDocs build environment based on **Python 3.12 Alpine**. This project is designed to provide a consistent, containerized toolchain for building documentation with a pre-configured set of plugins and a dynamic configuration generator.
7-
8-
## 🚀 Overview
9-
10-
This image simplifies the MkDocs build process by:
11-
12-
1. **Dynamic Configuration**: Automatically merging metadata (`info.json`) and specific YAML fragments into a final `mkdocs.yml`.
13-
2. **Batteries Included**: Pre-installed with essential plugins like `glightbox`, `minify`, and `pymdown-extensions`.
14-
3. **CI/CD Ready**: Optimized specifically for use as a **GitHub Actions Job Container**.
15-
16-
## 🛠 Features
17-
18-
- **Base Image**: `python:3.12-alpine` (Small footprint, fast pull).
19-
- **GHA Compatible**: Includes `bash`, `git`, `tar`, `gzip` for seamless integration with GitHub Actions steps (e.g., `actions/checkout`, `actions/upload-artifact`).
20-
- **Dynamic Generator**: Uses an internal Python script to assemble the site configuration from multiple sources.
21-
- **Post-processing**: Automatically handles site-dir merging and cleanup.
22-
23-
## 📦 Required Files
24-
25-
To use this builder, your workspace should typically contain:
26-
27-
| File | Description |
28-
| :--- | :--- |
29-
| `info.json` | Project metadata, navigation structure, and project-specific info. |
30-
| `docs/` | Your Markdown content. |
31-
| `docs/assets/extra.yml` | (Optional) Peer-level overrides/extra configuration for MkDocs. |
4+
[![Registry](https://img.shields.io/badge/Container-GHCR-blue?logo=github)](https://github.com/raineblog/mkdocs-docker/pkgs/container/mkdocs-docker)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
[![Python](https://img.shields.io/badge/Python-3.12-blue?logo=python)](https://www.python.org/)
7+
8+
**MkDocs Exporter Docker** is a streamlined, containerized build environment designed for modern documentation workflows. Based on **Python 3.12 Alpine**, it provides a "batteries-included" toolchain specifically optimized for **GitHub Actions** and CI/CD pipelines.
9+
10+
---
11+
12+
## ✨ Key Features
13+
14+
- **🚀 Fast & Lightweight**: Built on Alpine Linux to ensure rapid image pulls and minimal resource footprint in CI environments.
15+
- **🧩 Dynamic Configuration**: Automatically assembles your `mkdocs.yml` from separate sources (`info.json`, templates, and local overrides), allowing for easier metadata management.
16+
- **🔋 Batteries Included**: Pre-configured with essential plugins:
17+
- `mkdocs-material` features (pre-configured)
18+
- `mkdocs-glightbox` for image zooming
19+
- `mkdocs-minify-plugin` for production optimization
20+
- `pymdown-extensions` for advanced Markdown syntax
21+
- **🛠 GitHub Actions Optimized**: Includes `bash`, `git`, `tar`, and `gzip` to support common GHA steps seamlessly.
22+
- **⚡ Specialized Serving**: Support for standard `mkdocs serve` and the specialized `zensical serve`.
23+
24+
---
25+
26+
## 🏗 How It Works
27+
28+
This builder uses a "Configuration-as-Data" approach. Instead of manually maintaining a complex `mkdocs.yml`, the environment generates it at runtime by merging three sources:
29+
30+
1. **Internal Template**: Base settings for theme, plugins, and extensions.
31+
2. **`info.json`**: Your project's core metadata (name, description, navigation).
32+
3. **`docs/assets/extra.yml`**: Any project-specific overrides or additional MkDocs configuration.
33+
34+
### Directory Structure Requirement
35+
To use this image, your project should follow this structure:
36+
```text
37+
.
38+
├── info.json # Required: Project metadata & Nav
39+
├── docs/ # Required: Markdown content
40+
│ ├── index.md # Required (used in intro)
41+
│ ├── intro/ # Required (used in intro)
42+
│ │ ├── format.md
43+
│ │ ├── usage.md
44+
│ │ └── discussion.md
45+
│ ├── madoka.md # Required (used in intro)
46+
│ └── assets/ # Optional
47+
│ └── extra.yml # Optional: MkDocs overrides
48+
└── ...
49+
```
3250

33-
The builder merges these with an internal `template.yml` to produce the final `mkdocs.yml` at runtime.
51+
> [!NOTE]
52+
> This builder is opinionated and automatically prepends several "Introduction" pages to your navigation. Ensure these files exist in your `docs/` folder to avoid build errors.
3453
35-
## 💻 Usage
54+
---
3655

37-
### GitHub Actions (Recommended)
56+
## 🚀 Usage
3857

39-
You can use this image directly as a job container in your workflow:
58+
### 1. GitHub Actions (Recommended)
59+
Add this image as a job container in your `.github/workflows/deploy.yml`:
4060

4161
```yaml
4262
jobs:
43-
build-docs:
63+
build-and-deploy:
4464
runs-on: ubuntu-latest
4565
container:
4666
image: ghcr.io/raineblog/mkdocs-docker:latest
4767
steps:
4868
- name: Checkout
49-
uses: actions/checkout@v6
69+
uses: actions/checkout@v4
5070

5171
- name: Build Documentation
5272
run: mkdocs-build
5373

54-
- name: Upload Artifact
55-
uses: actions/upload-pages-artifact@v4
74+
- name: Deploy to GitHub Pages
75+
uses: actions/upload-pages-artifact@v3
5676
with:
5777
path: ./site
5878
```
5979
60-
### Local Development
80+
### 2. Local Development
81+
You can mirror the production build process locally:
6182
62-
Run the builder inside your project directory:
83+
```bash
84+
docker run --rm \
85+
-v $(pwd):/app/workspace \
86+
-w /app/workspace \
87+
ghcr.io/raineblog/mkdocs-docker:latest \
88+
mkdocs-build
89+
```
6390

91+
To serve documentation with live-reload:
6492
```bash
65-
docker run --rm -v $(pwd):/app/workspace -w /app/workspace ghcr.io/raineblog/mkdocs-docker:latest mkdocs-build
93+
docker run --rm -it \
94+
-v $(pwd):/app/workspace \
95+
-w /app/workspace \
96+
-p 8000:8000 \
97+
ghcr.io/raineblog/mkdocs-docker:latest \
98+
mkdocs-serve
6699
```
67100

68-
## 🛠 Maintenance & Contributions
101+
---
102+
103+
## ⚙️ Configuration Reference
104+
105+
### `info.json` Format
106+
The `info.json` file is the heart of your documentation metadata:
107+
108+
```json
109+
{
110+
"project": {
111+
"site_name": "My Documentation",
112+
"site_description": "A wonderful project description",
113+
"repo_url": "https://github.com/user/repo"
114+
},
115+
"nav": [
116+
{
117+
"title": "Getting Started",
118+
"children": [
119+
"guide/install.md",
120+
"guide/config.md"
121+
]
122+
}
123+
],
124+
"extra": {
125+
"version": "1.0.0"
126+
}
127+
}
128+
```
69129

70-
**Please Note:** This project is a personal toolchain maintained for my own organization's needs.
130+
---
71131

72-
- **Status**: Active but "Low-Maintenance". I use this regularly, but I have limited capacity to review large changes.
73-
- **Bug Reports & Corrections**: Highly welcomed! If you find a typo, a logic error in the build script, or a vulnerability, please open an issue or PR.
74-
- **Feature Requests**: I am generally **not accepting new features** or functional requests. I prefer to keep this toolchain specialized for its current purpose to minimize maintenance overhead.
132+
## 🛠 Maintenance & Community
75133

76-
If you need a more flexible or feature-rich MkDocs environment, I recommend checking out the official [Squidfunk/mkdocs-material](https://github.com/squidfunk/mkdocs-material) image.
134+
This project is a personal toolchain maintained by **raineblog**.
77135

78-
## 📄 License
136+
- **Status**: Active / Low-Maintenance.
137+
- **Contributions**: I am happy to accept **bug reports** and **corrections** (typos, logic fixes, security patches).
138+
- **Feature Requests**: I am currently **not accepting new features**. The tool is designed to be highly specialized for my specific workflow; if you need more flexibility, I recommend using the official [Squidfunk/mkdocs-material](https://github.com/squidfunk/mkdocs-material) image.
79139

80-
This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
140+
---
141+
142+
## 📄 License
143+
Distributed under the **MIT License**. See `LICENSE` for more information.

0 commit comments

Comments
 (0)