TSYSDevStack/Toolbox/docs/README.md

TSYS Group Development Stack - Documentation & Diagrams

Your ultimate document production workhorse

✨ Comprehensive document tooling | 🛡️ Security-first design | 🚀 Multi-platform support

---

Table of Contents

• Overview
• Features
• Tools Included
• Quick Start
• Usage
• Development
• Quality Assurance
• Contributing
• License

---

Overview

The TSYS Documentation & Diagrams container provides a comprehensive solution for document production, supporting multiple formats and workflows. Built with security in mind, it runs exclusively as a non-root user and includes all necessary tools for modern document generation.

This image serves as a "document production workhorse" with capabilities including:

• 📄 Pandoc: Convert between various document formats (Markdown, PDF, DOC, etc.)
• 📚 mdBook: Generate beautiful books and documentation
• ✍️ Typst: Modern markup-based typesetting system
• 🎨 Marp: Create slide decks from Markdown
• 📊 Kroki: Generate diagrams from text descriptions
• 📝 Quarto: Scientific and technical publishing system
• 🔍 Vale: Syntax-aware linter for prose

---

Features

Feature	Description	Status
🛡️ Security First	Runs as non-root user with no sudo/su access	✅
🔧 Mise Integration	All language runtimes managed via mise	✅
🌐 Multi-Platform	Supports PC/Raspberry Pi/Mac M series	✅
📦 Version Pinned	Reproducible builds with pinned versions	✅
🚀 Performance Optimized	Efficient Docker layer caching	✅
🧪 Quality Assured	Validated with hadolint/shellcheck/yamllint	✅

---

Tools Included

Core Document Conversion

Tool	Purpose	Version	License
Pandoc	Universal document converter	3.5	GPL
wkhtmltopdf	HTML to PDF converter	0.12.6.1	LGPL
TeXLive	Typesetting system	2022	GPL & other

Book & Documentation Tools

Tool	Purpose	Version	License
mdBook	Create books from Markdown	0.4.40	MPL-2.0
Quarto	Scientific publishing system	1.6.39	GPL-2.0
Typst	Modern typesetting system	0.12.0	Apache-2.0

Presentation & Diagram Tools

Tool	Purpose	Version	License
Marp	Markdown presentation ecosystem	3.9.0	MIT
MarkWhen	Timeline tool from Markdown	0.11.0	MIT
Kroki	Text to diagram converter	0.25.0	Apache-2.0

Quality & Validation Tools

Tool	Purpose	Version	License
Vale	Syntax-aware prose linter	3.7.0	MIT
BibTool	BibTeX manipulation tool	2.25	GPL-3.0
jq	JSON processor	1.6	MIT
yq	YAML processor	4.44.3	MIT

Language Runtimes (via Mise)

Runtime	Version	Purpose
Python	3.12.7	Scripting, automation, Vale
Node.js	22.9.0	npm packages, Marp, Kroki
Rust	1.81.0	System-level tools, mdBook, Typst

---

Quick Start

Prerequisites

• Docker Engine 20.10 or higher
• Docker Buildx plugin
• At least 4GB free disk space for the complete image

Running the Container

# Pull the latest image
docker pull tsysdevstack/tsysdevstack-toolboxes-docs

# Run interactively
docker run -it --rm -v $(pwd):/workspace tsysdevstack/tsysdevstack-toolboxes-docs

# Run a specific command
docker run --rm -v $(pwd):/workspace tsysdevstack/tsysdevstack-toolboxes-docs pandoc --version

Using the Provided Scripts

# Build image with QA checks
./output/build.sh

# Run container interactively
./output/run.sh

# Test all tools
./output/test.sh

# Run workflow demonstrations
./examples/workflow-demo.sh --all

---

Usage

Converting Documents with Pandoc

# Convert Markdown to PDF
pandoc input.md -o output.pdf

# Convert to DOCX with custom template
pandoc input.md --reference-doc=template.docx -o output.docx

# Joplin Markdown to PDF with LaTeX styling
pandoc joplin-note.md -o note.pdf --pdf-engine=xelatex --template=template.latex

Building Documentation with mdBook

# Build static site
mdbook build

# Serve locally
mdbook serve --hostname 0.0.0.0 --port 3000

# Watch for changes
mdbook watch

Creating Presentations with Marp

# Convert Markdown to PDF
marp --pdf presentation.md

# Convert to HTML
marp --html presentation.md

# Serve locally with live reload
marp --server presentation.md

Generating Diagrams with Kroki

# Convert text to diagram
echo 'graph TD; A-->B; A-->C;' | kroki --output diagram.png

---

Development

Building from Source

# Clone the repository
git clone https://github.com/tsysdevstack/toolbox.git

# Navigate to the docs directory
cd toolbox/docs/output

# Build the Docker image
./output/build.sh

# Run tests to verify all tools work
./output/test.sh

Development Container

This project supports VS Code development containers. Simply open the project in VS Code with the Remote-Containers extension to automatically set up the development environment.

Quality Assurance

All files have been validated with:

• 🐳 hadolint - Dockerfile best practices
• 🐚 shellcheck - Shell script quality
• ✨ yamllint - YAML syntax and style

---

Quality Assurance

Tool	Status	Validation
hadolint	✅	Zero warnings/errors
shellcheck	✅	Zero warnings/errors
yamllint	✅	Zero warnings/errors
Security	✅	Non-root execution

QA Process

1. Dockerfile: Validated with hadolint/hadolint Docker image
2. Shell Scripts: Validated with koalaman/shellcheck:stable Docker image
3. YAML Files: Validated with cytopia/yamllint:latest Docker image
4. Security: Verified with non-root user execution
5. Functionality: Verified with comprehensive test suite

---

Contributing

We welcome contributions to improve the TSYS Documentation & Diagrams container! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (./test.sh)
5. Validate quality (./validate.sh)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Guidelines

• All changes must pass quality checks (hadolint, shellcheck, yamllint)
• Follow established coding patterns
• Maintain security practices (no root operations at runtime)
• Update documentation as needed

---

License

This project is licensed under the terms specified in the LICENSE file.

---

TSYS Group Development Stack | Building secure, reproducible development environments

GitHub • Documentation • Issues