# TSYS DevStack Docs & Diagrams Toolchain

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

> 📘 A comprehensive Docker-based documentation production workhorse featuring pandoc, mdbook, typst, marp, markwhen, kroki, quarto, and more.

## 🚀 Overview

The TSYS DevStack Docs & Diagrams toolchain provides a complete containerized environment for generating professional documentation in multiple formats. Built on Debian stable with a focus on security and reproducibility, this image includes all the tools you need to create resumes, project plans, technical documentation, presentations, and more.

### 📋 Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    tsysdevstack-toolboxes-docs                  │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │   Core Tools    │  │   Format Tools  │  │  Support Tools  │  │
│  │ • pandoc        │  │ • mdbook       │  │ • jq, yq        │  │
│  │ • texlive-full  │  │ • typst        │  │ • git, curl     │  │
│  │ • wkhtmltopdf   │  │ • marp-cli     │  │ • fish shell    │  │
│  │ • bibtool       │  │ • markwhen     │  │ • zsh, bash     │  │
│  │ • vale          │  │ • kroki-cli    │  │ • wget          │  │
│  │                 │  │ • quarto-cli   │  │ • ca-certificates│ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                    Runtime Environment                          │
│                User: tsysdevstack (UID 1001)                    │
└─────────────────────────────────────────────────────────────────┘
```

### 🛠️ Included Tools

| Tool | Purpose | Version |
|------|---------|---------|
| **pandoc** | Universal document converter | Latest |
| **mdbook** | Book generation from markdown | 0.4.36 |
| **typst** | Modern typesetting system | 0.11.0 |
| **marp-cli** | Markdown presentation builder | 3.0.0 |
| **markwhen** | Timeline generator from markdown | 0.8.0 |
| **kroki-cli** | Diagram generation from text | 0.6.0 |
| **quarto-cli** | Scientific publishing system | 1.5.56 |
| **bibtool** | Bibliography file processor | Latest |
| **vale** | Syntax-aware linter for prose | 2.31.0 |
| **texlive-full** | LaTeX distribution | 2022.20220321-3 |
| **wkhtmltopdf** | HTML to PDF converter | 0.12.6.1 |

## 🏗️ Quick Start

### Prerequisites
- Docker 20.10+
- Docker Buildx plugin

### Building the Image
```bash
# Clone the repository
git clone https://github.com/tsysdevstack/toolboxes-docs.git

# Change to the directory
cd toolboxes-docs

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

### Running the Container
```bash
# Run in interactive mode with access to your docs directory
docker run --rm -it -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs

# Or use the run script directly
./output/run.sh pandoc examples/resume-sample.md -o output/resume.pdf

# Or use docker-compose
docker-compose -f output/docker-compose.yml run docs
```

## 📚 Usage Examples

### Convert Markdown to PDF
```bash
# Using pandoc with a LaTeX template
./output/run.sh pandoc examples/resume-sample.md -o output/resume.pdf --template=examples/resume-style.tex
```

### Generate a Book
```bash
# Build an mdbook from source
./output/run.sh bash -c "cd examples/mdbook-sample && mdbook build"
```

### Create a Presentation
```bash
# Convert markdown to PDF presentation
./output/run.sh bash -c "npx --package @marp-team/marp-cli marp examples/sample-presentation.md -o output/presentation.pdf"
```

### Compile Typst Document
```bash
# Compile a typst document to PDF
./output/run.sh typst compile examples/sample-typst.typ output/document.pdf
```

## 🐳 Multi-Architecture Support

This image supports multiple architectures through Docker Buildx:

- `linux/amd64` (x86_64)
- `linux/arm64` (ARM 64-bit)
- `linux/arm/v7` (ARM 32-bit, v7)

## 🔐 Security & Best Practices

- **Rootless Runtime**: Container runs as non-root user (UID 1001)
- **Version Pinning**: All packages and dependencies are version-pinned
- **Multi-Stage Build**: Minimal final image with only necessary components
- **Regular Scanning**: Automated security scanning with Trivy

## ⚙️ Configuration

The container can be configured via:

- **Environment Variables**: Set user preferences and tool configurations
- **Volume Mounts**: Share files between host and container
- **Build Arguments**: Customize image during build process

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.