133 lines
5.8 KiB
Markdown
133 lines
5.8 KiB
Markdown
# TSYS DevStack Docs & Diagrams Toolchain
|
|
|
|
  [](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. |