TSYSDevStack - Toolboxes - DocsAndDiagrams 📚

A comprehensive document production workhorse container

Transform your documentation workflows with powerful tools for document generation, conversion, and processing.

🗂️ Table of Contents

• 🎯 Overview
• 🛠️ Tools Included
• 🚀 Quick Start
• 🐳 Docker Usage
• 🏗️ Building the Image
• 🧪 Testing
• 📁 Directory Structure
• 🔧 Configuration
• 📝 Examples
• ❓ Troubleshooting
• 📄 License

🎯 Overview

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!