# TSYSDevStack - Toolboxes - DocsAndDiagrams ๐
[](https://hub.docker.com/r/tsysdevstack/toolboxes-docs)
[](https://hub.docker.com/r/tsysdevstack/toolboxes-docs)
[](LICENSE)
**A comprehensive document production workhorse container**
Transform your documentation workflows with powerful tools for document generation, conversion, and processing.
## ๐๏ธ Table of Contents
- [๐ฏ Overview](#-overview)
- [๐ ๏ธ Tools Included](#๏ธ-tools-included)
- [๐ Quick Start](#-quick-start)
- [๐ณ Docker Usage](#-docker-usage)
- [๐๏ธ Building the Image](#๏ธ-building-the-image)
- [๐งช Testing](#-testing)
- [๐ Directory Structure](#-directory-structure)
- [๐ง Configuration](#-configuration)
- [๐ Examples](#-examples)
- [โ Troubleshooting](#-troubleshooting)
- [๐ License](#-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
```bash
# 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
```bash
# 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:
```bash
-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
```bash
# 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
```bash
# 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
```bash
docker buildx build --platform linux/amd64,linux/arm64 -t tsysdevstack/toolboxes-docs:latest .
```
## ๐งช Testing
Run the included test suite to verify the container functionality:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](documentation/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](LICENSE) file for details.
---
Made with โค๏ธ by [TSYS Group](https://tsysgroup.com)
โญ Star this repo if you find it helpful!