5.8 KiB
5.8 KiB
TSYS DevStack Docs & Diagrams Toolchain
📘 A comprehensive Docker-based documentation production workhorse featuring pandoc, mdbook, typst, marp, markwhen, kroki, quarto, and more.
🚀 Overview
The TSYS DevStack Docs & Diagrams toolchain provides a complete containerized environment for generating professional documentation in multiple formats. Built on Debian stable with a focus on security and reproducibility, this image includes all the tools you need to create resumes, project plans, technical documentation, presentations, and more.
📋 Architecture
┌─────────────────────────────────────────────────────────────────┐
│ tsysdevstack-toolboxes-docs │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Core Tools │ │ Format Tools │ │ Support Tools │ │
│ │ • pandoc │ │ • mdbook │ │ • jq, yq │ │
│ │ • texlive-full │ │ • typst │ │ • git, curl │ │
│ │ • wkhtmltopdf │ │ • marp-cli │ │ • fish shell │ │
│ │ • bibtool │ │ • markwhen │ │ • zsh, bash │ │
│ │ • vale │ │ • kroki-cli │ │ • wget │ │
│ │ │ │ • quarto-cli │ │ • ca-certificates│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Runtime Environment │
│ User: tsysdevstack (UID 1001) │
└─────────────────────────────────────────────────────────────────┘
🛠️ Included Tools
| Tool | Purpose | Version |
|---|---|---|
| pandoc | Universal document converter | Latest |
| mdbook | Book generation from markdown | 0.4.36 |
| typst | Modern typesetting system | 0.11.0 |
| marp-cli | Markdown presentation builder | 3.0.0 |
| markwhen | Timeline generator from markdown | 0.8.0 |
| kroki-cli | Diagram generation from text | 0.6.0 |
| quarto-cli | Scientific publishing system | 1.5.56 |
| bibtool | Bibliography file processor | Latest |
| vale | Syntax-aware linter for prose | 2.31.0 |
| texlive-full | LaTeX distribution | 2022.20220321-3 |
| wkhtmltopdf | HTML to PDF converter | 0.12.6.1 |
🏗️ Quick Start
Prerequisites
- Docker 20.10+
- Docker Buildx plugin
Building the Image
# Clone the repository
git clone https://github.com/tsysdevstack/toolboxes-docs.git
# Change to the directory
cd toolboxes-docs
# Build the image
./output/build.sh
Running the Container
# Run in interactive mode with access to your docs directory
docker run --rm -it -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs
# Or use the run script directly
./output/run.sh pandoc examples/resume-sample.md -o output/resume.pdf
# Or use docker-compose
docker-compose -f output/docker-compose.yml run docs
📚 Usage Examples
Convert Markdown to PDF
# Using pandoc with a LaTeX template
./output/run.sh pandoc examples/resume-sample.md -o output/resume.pdf --template=examples/resume-style.tex
Generate a Book
# Build an mdbook from source
./output/run.sh bash -c "cd examples/mdbook-sample && mdbook build"
Create a Presentation
# Convert markdown to PDF presentation
./output/run.sh bash -c "npx --package @marp-team/marp-cli marp examples/sample-presentation.md -o output/presentation.pdf"
Compile Typst Document
# Compile a typst document to PDF
./output/run.sh typst compile examples/sample-typst.typ output/document.pdf
🐳 Multi-Architecture Support
This image supports multiple architectures through Docker Buildx:
linux/amd64(x86_64)linux/arm64(ARM 64-bit)linux/arm/v7(ARM 32-bit, v7)
🔐 Security & Best Practices
- Rootless Runtime: Container runs as non-root user (UID 1001)
- Version Pinning: All packages and dependencies are version-pinned
- Multi-Stage Build: Minimal final image with only necessary components
- Regular Scanning: Automated security scanning with Trivy
⚙️ Configuration
The container can be configured via:
- Environment Variables: Set user preferences and tool configurations
- Volume Mounts: Share files between host and container
- Build Arguments: Customize image during build process
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for more details.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.