Skip to content

README.md

Latest commit

 

History

History
127 lines (89 loc) · 3.19 KB

README.md

File metadata and controls

127 lines (89 loc) · 3.19 KB

🧰 docs-toolbox

License: MIT Docker Docs-as-Code

docs-as-code-toolkit-logo

Part of the Docs-as-Code Toolkit
→ https://github.com/docs-as-code-toolkit

A lightweight Docker image for running Docs-as-Code pipelines in a fully reproducible environment — locally and in CI.

Stop installing random tools locally.
Stop breaking your CI builds.
Just use the same environment everywhere.

Unlike ad-hoc setups, this image is designed to be the single source of truth for your documentation toolchain.

🧠 What this enables

  • Reproducible documentation builds across environments
  • Zero-setup onboarding for contributors
  • Consistent toolchain in local and CI workflows

✨ What’s inside?

This image provides a ready-to-use toolchain for Docs-as-Code pipelines:

  • Asciidoctor
  • Pandoc
  • Graphviz
  • Common CLI utilities

👉 Everything preconfigured to work together.

🎯 Why this exists

Documentation pipelines often suffer from:

  • ❌ "Works on my machine"
  • ❌ Different tool versions locally vs CI
  • ❌ Painful setup for new contributors
  • ❌ Hidden dependencies

This image solves that by providing:

A consistent, versioned, reproducible environment for documentation builds.

🚀 Usage

Run a command

docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  ghcr.io/docs-as-code-toolkit/docs-toolbox:latest \
  ./asciidoctor -v

💡 On Windows, replace $(pwd) with the appropriate path syntax.

Use in scripts (example)

./build.sh <some action>

(assuming your project wraps the container execution)

GitHub Actions (example

jobs:
  docs:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/docs-as-code-toolkit/docs-toolbox:latest

    steps:
      - uses: actions/checkout@v4
      - run: ./gradlew build

🧩 Typical Use Cases

  • 📄 Generate HTML / PDF / Markdown from AsciiDoc
  • 🧱 Docs-as-Code pipelines
  • 📦 CI/CD documentation builds
  • 👥 Onboarding without local setup

📐 Philosophy

This image follows a few simple principles:

  • 🔁 Reproducibility over convenience
  • 📦 Everything included, nothing assumed
  • ⚙️ Same environment locally and in CI
  • 🧼 No hidden magic

🔄 Versioning

  • latest → most recent stable toolbox
  • version tags → reproducible builds
  • df-<hash> → image of latest commit (does not need to be the same as 'latest')

👉 Pin versions in CI for full determinism.

🛠️ Customization

If you need additional tools:

  • Extend this image via your own Dockerfile
  • Or fork and adapt it to your pipeline

🌐 Related Project

This image powers the following real-world project:

👉 https://github.com/dieterbaier/profile

A real-world example of a Docs-as-Code pipeline for personal branding.

📄 License

This project is licensed under the MIT License.