TSYSDevStack/Toolbox/docs/README.md

# TSYS Group Development Stack - Documentation & Diagrams

<div align="center">

[![Docker Image Size](https://img.shields.io/docker/image-size/tsysdevstack/tsysdevstack-toolboxes-docs?style=for-the-badge)](https://hub.docker.com/r/tsysdevstack/tsysdevstack-toolboxes-docs)
[![Docker Pulls](https://img.shields.io/docker/pulls/tsysdevstack/tsysdevstack-toolboxes-docs?style=for-the-badge)](https://hub.docker.com/r/tsysdevstack/tsysdevstack-toolboxes-docs)
[![License](https://img.shields.io/github/license/tsysdevstack/toolbox?style=for-the-badge)](LICENSE)

**Your ultimate document production workhorse**

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

</div>

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Tools Included](#tools-included)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Development](#development)
- [Quality Assurance](#quality-assurance)
- [Contributing](#contributing)
- [License](#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](https://pandoc.org/) | Universal document converter | 3.5 | GPL |
| [wkhtmltopdf](https://wkhtmltopdf.org/) | HTML to PDF converter | 0.12.6.1 | LGPL |
| [TeXLive](https://www.tug.org/texlive/) | Typesetting system | 2022 | GPL & other |

### Book & Documentation Tools
| Tool | Purpose | Version | License |
| :--- | :--- | :--- | :--- |
| [mdBook](https://rust-lang.github.io/mdBook/) | Create books from Markdown | 0.4.40 | MPL-2.0 |
| [Quarto](https://quarto.org/) | Scientific publishing system | 1.6.39 | GPL-2.0 |
| [Typst](https://typst.app/) | Modern typesetting system | 0.12.0 | Apache-2.0 |

### Presentation & Diagram Tools
| Tool | Purpose | Version | License |
| :--- | :--- | :--- | :--- |
| [Marp](https://marp.app/) | Markdown presentation ecosystem | 3.9.0 | MIT |
| [MarkWhen](https://markwhen.com/) | Timeline tool from Markdown | 0.11.0 | MIT |
| [Kroki](https://kroki.io/) | Text to diagram converter | 0.25.0 | Apache-2.0 |

### Quality & Validation Tools
| Tool | Purpose | Version | License |
| :--- | :--- | :--- | :--- |
| [Vale](https://vale.sh/) | Syntax-aware prose linter | 3.7.0 | MIT |
| [BibTool](https://github.com/ge-ne/bibtool) | BibTeX manipulation tool | 2.25 | GPL-3.0 |
| [jq](https://stedolan.github.io/jq/) | JSON processor | 1.6 | MIT |
| [yq](https://mikefarah.github.io/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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

---

## Development

### Building from Source

```bash
# 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

<div align="center">

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

</div>

### 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](LICENSE) file.

<div align="center">

---
**TSYS Group Development Stack** | *Building secure, reproducible development environments*

[GitHub](https://github.com/tsysdevstack) • [Documentation](docs/) • [Issues](issues)

</div>