.

2025-11-11 21:00:37 -06:00
parent 544d1c31e5
commit 53b986d3f7
37 changed files with 3433 additions and 2 deletions
--- a/Toolbox/docs/documentation/README.md
+++ b/Toolbox/docs/documentation/README.md
@@ -0,0 +1,133 @@
+# 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.