KNEL/TSYSDevStack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Toolboxes-Docs (vibe-kanban c5c3e68d)

Browse Source 
TSYS Group Development Stack - Toolboxes - DocsAndDiagrams - Product Requirements Document -

## Docker Image Boilerplate

Image name: tsysdevstack-toolboxes-docs
Image username: tsysdevstack
Image base: latest Debian stable

- ALL operations MUST be as the tsysdevstack user
- NO ROOT ACCESS should be possible at runtime (no sudo, no su)
- The ONLY permitted use of root is during build time, and that MUST be to the ABSOLUTE MINIMUM extent possible (just for apt-get operations and creating the tsysdevstack user). Switching to tsysdevstack as early as possible.
- mise (as the tsysdevstack user) MUST be used to install all language runtimes (node/python/rust/ruby).
- If an application is installed via npm/pip/cargo/gem, those application installs MUST be done via mise managed versions of npm/pip/cargo/gem.
- NO system wide (apt-get) installs of language runtimes are allowed
- This is a production container. Use ALL best common practices for the building and securing of docker containers. (Buildx, multi stage, hardened )
- Use yamllint/hadolint/shellcheck (available via docker images on this system) as a QA gate BEFORE attempting to build the image. If ANY changes to Dockerfile/run.sh/build.sh/test.sh are made, run them through hadolint/shellcheck respectively.
- ALL hadolint/yamllint/shellcheck issues MUST be FULLY RESOLVED always. The only acceptable QA outcome is when those tools return no warnings/errors.
- Think about how to efficiently create the Dockerfile, keeping caching of layers in mind , especially how layers can be cached across multiple different image builds.
- Utilize buildkit/buildx
- This container needs to run on PC/Raspberry Pi/Mac M series.
- Reproducibility of the build is PARAMOUNT! Use version pinning for EVERYTHING. Do the research to find the latest stable version and update Dockerfile and other files accordingly. Do not "just use latest", that is never acceptable. You MUST pin the Debian package versions, and any of the tooling you install via mise managed runtimes.
- Use the examples subdirectory and create example artifacts and workflow scripts to fully QA the functionality of the container
- Create a README.md file that is BEAUTIFULLY formatted (using table of contents/headers/icons/graphics/whitespace/tables (with left justified text)). Document the container image thoroughly.
- Use the documentation subdirectory and creaate the following artifacts:
  - TROUBLESHOOTING.md
  - CHEATSHEET.md
  - USAGE.md
- Use the output subdirectory and create the following artifacts (ensure they will pass strict QA testing/auditing):

- Dockerfile
- docker-compose.yml
- devcontainer.json
- run.sh
- build.sh
- test.sh

## Docker Image Requirements

The overall purpose of this container image is to be a document production workhorse.

Core workflows:

- pandoc

 markdown to pdf/doc (for resumes) (so simple formatting, ATS optimized)
 markdown to pdf (for project plans, budgets, proposals etc)
 Joplin markdown notes to PDF preserving all the extensive formatting that Joplin has when it renders the notes to pdf

The generated PDFs need to be beautiful. Rich fonts, graphics, formatting of the code listings etc. We will be heavily leaning into texlive/xetex for this. I would also like to explore using wkhtmltopdf so that CSS can be used to style the output.

- mdbook
- typst
- marp
- markwhen
- kroki cli
- quarto
- bibtool
- vale

Add in any other common support tools you think may be needed (such as jq/yq).

Generally this image will be used "headless" to run a generation workflow (or mdbook serve during active development of an mdbook site).

It should have fish as it's shell (and also bash/zsh) for the occasional interactive use.

Follow test-driven-development for this project without fail.

Ensure that the image is built successfully and fully validated against this PRD

Use the /home/localuser/TSYSDevStack/Toolbox/docs/output directory for all of the work you do for this task.
This commit is contained in:
Charles N Wyble - admin
2025-11-11 20:59:13 -06:00
parent d94f81bc55
commit 544d1c31e5
18 changed files with 1902 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
README.md Normal file
View File

@@ -0,0 +1,273 @@
# TSYSDevStack - Toolboxes - DocsAndDiagrams 📚
<div align="center">
[![Docker Image Version](https://img.shields.io/docker/v/tsysdevstack/toolboxes-docs?sort=semver&logo=docker&logoColor=white)](https://hub.docker.com/r/tsysdevstack/toolboxes-docs)
[![Docker Pulls](https://img.shields.io/docker/pulls/tsysdevstack/toolboxes-docs?logo=docker&logoColor=white)](https://hub.docker.com/r/tsysdevstack/toolboxes-docs)
[![License](https://img.shields.io/github/license/tsysdevstack/toolboxes-docs)](LICENSE)
**A comprehensive document production workhorse container**
Transform your documentation workflows with powerful tools for document generation, conversion, and processing.
</div>
## 🗂️ Table of Contents
- [🎯 Overview](#-overview)
- [🛠️ Tools Included](#️-tools-included)
- [🚀 Quick Start](#-quick-start)
- [🐳 Docker Usage](#-docker-usage)
- [🏗️ Building the Image](#️-building-the-image)
- [🧪 Testing](#-testing)
- [📁 Directory Structure](#-directory-structure)
- [🔧 Configuration](#-configuration)
- [📝 Examples](#-examples)
- [❓ Troubleshooting](#-troubleshooting)
- [📄 License](#-license)
## 🎯 Overview
The **TSYSDevStack Toolboxes Docs** container is a specialized Docker image designed for document production workflows. It provides a rich set of tools for converting, generating, and processing documents in various formats with a focus on beautiful PDF output.
### ✨ Key Features
- **Multi-format document conversion** with Pandoc
- **Beautiful PDF generation** using TeXLive and XeTeX
- **Book generation** with mdBook
- **Scientific document preparation** with Typst
- **Presentation creation** with Marp
- **Timeline visualization** with Markwhen
- **Statistical publishing** with Quarto
- **Diagram generation** with Kroki CLI
- **Code-aware linter** with Vale
- **Cross-platform compatibility** (PC/Raspberry Pi/Mac M series)
### 🎯 Use Cases
- Converting Markdown documents to PDF, DOCX, and other formats (ATS-optimized)
- Generating beautiful project plans, budgets, and proposals
- Converting Joplin notes to PDF while preserving formatting
- Creating books and documentation with mdBook
- Developing presentations with Marp
- Producing scientific documents with Typst
- Publishing reports with Quarto
## 🛠️ Tools Included
| Tool | Purpose | Version |
|------|---------|---------|
| **Pandoc** | Universal document converter | 3.2 |
| **mdBook** | Book generation from Markdown | 0.4.40 |
| **Typst** | Modern typesetting system | 0.12.0 |
| **Marp CLI** | Presentation slide generation | 3.4.0 |
| **Markwhen** | Timeline and calendar visualization | 0.9.1 |
| **Quarto** | Scientific and technical publishing | 1.6.17 |
| **Kroki CLI** | Diagram generation | 0.6.0 |
| **BibTool** | Bibliography manipulation | 3.2 |
| **Vale** | Code-aware linter | 3.4.2 |
| **TeXLive/XeTeX** | Professional document preparation | Latest |
| **wkhtmltopdf** | HTML to PDF conversion | Latest |
| **jq/yq** | JSON/YAML processing | Latest |
| **Fish shell** | Modern interactive shell | Latest |
| **Zsh** | Powerful shell | Latest |
## 🚀 Quick Start
### Prerequisites
- Docker installed and running
- At least 4GB of free disk space
### Running the Container
```bash
# Run interactively
docker run -it --rm -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" tsysdevstack/toolboxes-docs
# Run a specific command
docker run --rm -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" tsysdevstack/toolboxes-docs pandoc --version
# Convert a Markdown file to PDF
docker run --rm -v "$(pwd)/:/data" -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" tsysdevstack/toolboxes-docs bash -c "cd /data && pandoc README.md -o /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/readme.pdf"
```
### Using Docker Compose
```bash
# Build and start the container
docker-compose up --build
# Run a command in the container
docker-compose run --rm tsysdevstack-toolboxes-docs pandoc --version
```
## 🐳 Docker Usage
### Volume Mapping
The container expects your documents to be available in the container. Map your local directories as follows:
```bash
-v "/path/to/your/documents:/data"
-v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output"
```
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `USER` | `tsysdevstack` | Username inside container |
| `HOME` | `/home/tsysdevstack` | Home directory |
### Common Commands
```bash
# Generate a PDF from Markdown using Pandoc
pandoc input.md -o output.pdf --pdf-engine=xelatex
# Build an mdBook
mdbook build /data -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output
# Convert Markdown to presentation
marp input.md --pdf --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pdf
# Process with Typst
typst compile document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.pdf
```
## 🏗️ Building the Image
### Prerequisites for Building
- Docker with Buildx
- Minimum 8GB free disk space
- Stable internet connection
### Build with Script
```bash
# Build the image with default settings
./build.sh
# Build without using cache
./build.sh --no-cache
# Build with a specific tag
./build.sh --tag v1.0.0
```
### Manual Build
```bash
docker buildx build --platform linux/amd64,linux/arm64 -t tsysdevstack/toolboxes-docs:latest .
```
## 🧪 Testing
Run the included test suite to verify the container functionality:
```bash
# Run all tests
./test.sh
# Run tests manually
docker run --rm tsysdevstack/toolboxes-docs pandoc --version
docker run --rm tsysdevstack/toolboxes-docs mdbook --version
docker run --rm tsysdevstack/toolboxes-docs typst --version
```
## 📁 Directory Structure
```
├── documentation/ # Documentation files
│ ├── TROUBLESHOOTING.md # Troubleshooting guide
│ ├── CHEATSHEET.md # Quick reference
│ └── USAGE.md # Detailed usage instructions
├── examples/ # Example documents and workflows
├── output/ # Output directory for generated docs
├── Dockerfile # Container definition
├── docker-compose.yml # Docker Compose configuration
├── devcontainer.json # Dev container configuration
├── run.sh # Container run script
├── build.sh # Build script with QA checks
├── test.sh # Testing script
└── README.md # This file
```
## 🔧 Configuration
### TeXLive Configuration
The container includes a full TeXLive installation with XeTeX support, optimized for beautiful document generation. The fonts include Noto fonts for international character support.
### Language Runtimes
Language runtimes (Python, Node.js) are managed through `mise` to ensure version consistency and reproducibility. Applications installed via npm/pip are done using mise-managed versions.
### Shell Configuration
The container includes Fish shell, Zsh, and Bash with Oh-My-Zsh preconfigured for the tsysdevstack user.
## 📝 Examples
### Pandoc Conversion Examples
```bash
# Convert Markdown to PDF with custom styling
pandoc input.md -o output.pdf --pdf-engine=xelatex --css styles.css
# Convert Joplin notes to PDF
pandoc joplin_note.md -o note.pdf --pdf-engine=xelatex --variable classoption=landscape
# Create a resume from Markdown
pandoc resume.md -o resume.pdf --pdf-engine=xelatex --template elegant-latex-resume
```
### mdBook Examples
```bash
# Create a new book
mdbook init mybook
# Build the book
mdbook build mybook
# Serve the book locally
mdbook serve mybook --hostname 0.0.0.0 --port 3000
```
### Typst Examples
```bash
# Compile a Typst document
typst compile document.typ output.pdf
# Watch for changes and recompile
typst watch document.typ output.pdf
```
## ❓ Troubleshooting
For troubleshooting information, please see [TROUBLESHOOTING.md](documentation/TROUBLESHOOTING.md).
Common issues and solutions:
- **Permission errors**: Ensure volume mounts are accessible by the `tsysdevstack` user (UID 1000)
- **Font issues**: The container includes Noto fonts; custom fonts can be mounted into the container
- **Large document processing**: For large documents, increase Docker's memory allocation
- **Missing dependencies**: All dependencies are included in the image; if tools fail, check the troubleshooting guide
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
<div align="center">
Made with ❤️ by [TSYS Group](https://tsysgroup.com)
⭐ Star this repo if you find it helpful!
</div>