The TSYSDevStack Toolboxes Docs container is a specialized Docker image designed for document production workflows. It provides a rich set of tools for converting, generating, and processing documents in various formats with a focus on beautiful PDF output.

✨ Key Features

Multi-format document conversion with Pandoc
Beautiful PDF generation using TeXLive and XeTeX
Book generation with mdBook
Scientific document preparation with Typst
Presentation creation with Marp
Timeline visualization with Markwhen
Statistical publishing with Quarto
Diagram generation with Kroki CLI
Code-aware linter with Vale
Cross-platform compatibility (PC/Raspberry Pi/Mac M series)

🎯 Use Cases

Converting Markdown documents to PDF, DOCX, and other formats (ATS-optimized)
Generating beautiful project plans, budgets, and proposals
Converting Joplin notes to PDF while preserving formatting
Creating books and documentation with mdBook
Developing presentations with Marp
Producing scientific documents with Typst
Publishing reports with Quarto

🛠️ Tools Included

Tool	Purpose	Version
Pandoc	Universal document converter	3.2
mdBook	Book generation from Markdown	0.4.40
Typst	Modern typesetting system	0.12.0
Marp CLI	Presentation slide generation	3.4.0
Markwhen	Timeline and calendar visualization	0.9.1
Quarto	Scientific and technical publishing	1.6.17
Kroki CLI	Diagram generation	0.6.0
BibTool	Bibliography manipulation	3.2
Vale	Code-aware linter	3.4.2
TeXLive/XeTeX	Professional document preparation	Latest
wkhtmltopdf	HTML to PDF conversion	Latest
jq/yq	JSON/YAML processing	Latest
Fish shell	Modern interactive shell	Latest
Zsh	Powerful shell	Latest

🚀 Quick Start

Prerequisites

Docker installed and running
At least 4GB of free disk space

Running the Container

# Run interactively
docker run -it --rm -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" tsysdevstack/toolboxes-docs

# Run a specific command
docker run --rm -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" tsysdevstack/toolboxes-docs pandoc --version

# Convert a Markdown file to PDF
docker run --rm -v "$(pwd)/:/data" -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" tsysdevstack/toolboxes-docs bash -c "cd /data && pandoc README.md -o /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/readme.pdf"

Using Docker Compose

# Build and start the container
docker-compose up --build

# Run a command in the container
docker-compose run --rm tsysdevstack-toolboxes-docs pandoc --version

🐳 Docker Usage

Volume Mapping

The container expects your documents to be available in the container. Map your local directories as follows:

-v "/path/to/your/documents:/data"
-v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output"

Environment Variables

Variable	Default	Description
`USER`	`tsysdevstack`	Username inside container
`HOME`	`/home/tsysdevstack`	Home directory

Common Commands

# Generate a PDF from Markdown using Pandoc
pandoc input.md -o output.pdf --pdf-engine=xelatex

# Build an mdBook
mdbook build /data -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output

# Convert Markdown to presentation
marp input.md --pdf --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pdf

# Process with Typst
typst compile document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.pdf

🏗️ Building the Image

Prerequisites for Building

Docker with Buildx
Minimum 8GB free disk space
Stable internet connection

Build with Script

# Build the image with default settings
./build.sh

# Build without using cache
./build.sh --no-cache

# Build with a specific tag
./build.sh --tag v1.0.0

Manual Build

docker buildx build --platform linux/amd64,linux/arm64 -t tsysdevstack/toolboxes-docs:latest .

🧪 Testing

Run the included test suite to verify the container functionality:

# Run all tests
./test.sh

# Run tests manually
docker run --rm tsysdevstack/toolboxes-docs pandoc --version
docker run --rm tsysdevstack/toolboxes-docs mdbook --version
docker run --rm tsysdevstack/toolboxes-docs typst --version

📁 Directory Structure

├── documentation/          # Documentation files
│   ├── TROUBLESHOOTING.md  # Troubleshooting guide
│   ├── CHEATSHEET.md       # Quick reference
│   └── USAGE.md            # Detailed usage instructions
├── examples/               # Example documents and workflows
├── output/                 # Output directory for generated docs
├── Dockerfile              # Container definition
├── docker-compose.yml      # Docker Compose configuration
├── devcontainer.json       # Dev container configuration
├── run.sh                  # Container run script
├── build.sh                # Build script with QA checks
├── test.sh                 # Testing script
└── README.md               # This file

🔧 Configuration

TeXLive Configuration

The container includes a full TeXLive installation with XeTeX support, optimized for beautiful document generation. The fonts include Noto fonts for international character support.

Language Runtimes

Language runtimes (Python, Node.js) are managed through mise to ensure version consistency and reproducibility. Applications installed via npm/pip are done using mise-managed versions.

Shell Configuration

The container includes Fish shell, Zsh, and Bash with Oh-My-Zsh preconfigured for the tsysdevstack user.

📝 Examples

Pandoc Conversion Examples

# Convert Markdown to PDF with custom styling
pandoc input.md -o output.pdf --pdf-engine=xelatex --css styles.css

# Convert Joplin notes to PDF
pandoc joplin_note.md -o note.pdf --pdf-engine=xelatex --variable classoption=landscape

# Create a resume from Markdown
pandoc resume.md -o resume.pdf --pdf-engine=xelatex --template elegant-latex-resume

mdBook Examples

# Create a new book
mdbook init mybook

# Build the book
mdbook build mybook

# Serve the book locally
mdbook serve mybook --hostname 0.0.0.0 --port 3000

Typst Examples

# Compile a Typst document
typst compile document.typ output.pdf

# Watch for changes and recompile
typst watch document.typ output.pdf

❓ Troubleshooting

For troubleshooting information, please see TROUBLESHOOTING.md.

Common issues and solutions:

Permission errors: Ensure volume mounts are accessible by the tsysdevstack user (UID 1000)
Font issues: The container includes Noto fonts; custom fonts can be mounted into the container
Large document processing: For large documents, increase Docker's memory allocation
Missing dependencies: All dependencies are included in the image; if tools fail, check the troubleshooting guide

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by TSYS Group

⭐ Star this repo if you find it helpful!

Languages

Shell 47.7%

Go 44.4%

Dockerfile 5.6%

TeX 1.3%

HTML 0.5%

Other 0.4%