Toolboxes-Docs (vibe-kanban c5c3e68d)

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.
2025-11-11 20:59:13 -06:00
parent d94f81bc55
commit 544d1c31e5
18 changed files with 1902 additions and 0 deletions
--- a/documentation/USAGE.md
+++ b/documentation/USAGE.md
@@ -0,0 +1,316 @@
+# USAGE.md
+
+## TSYSDevStack - Toolboxes - DocsAndDiagrams
+
+Detailed Usage Instructions for the Document Production Workhorse Container
+
+---
+
+## 📖 Overview
+
+The TSYSDevStack Toolboxes Docs container is designed for document production workflows, offering a comprehensive suite of tools for converting, generating, and processing documents in various formats with a focus on beautiful PDF output.
+
+This guide details how to effectively use the tools available in the container for various document production tasks.
+
+## 🏗️ Container Setup
+
+### Running the Container
+
+The container can be used in both interactive and non-interactive modes:
+
+**Interactive Mode:**
+```bash
+docker run -it --rm \
+  -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" \
+  -v "$(pwd):/data" \
+  tsysdevstack/toolboxes-docs
+```
+
+**Non-Interactive Mode:**
+```bash
+docker run --rm \
+  -v "$(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output" \
+  -v "$(pwd):/data" \
+  tsysdevstack/toolboxes-docs \
+  bash -c "pandoc /data/input.md -o /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/output.pdf --pdf-engine=xelatex"
+```
+
+### Volume Mounting Explained
+
+- **Output Directory**: Mount your local directory to `/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output` to access generated documents
+- **Input Directory**: Mount your documents directory to `/data` for processing
+- **Configuration**: Store custom configurations in mounted volumes for reuse
+
+## 📝 Pandoc Usage
+
+### Basic Conversion
+
+Pandoc is the universal document converter, supporting over 50 input and output formats:
+
+```bash
+# Markdown to PDF (with beautiful styling)
+pandoc input.md -o output.pdf --pdf-engine=xelatex
+
+# Markdown to DOCX
+pandoc input.md -o output.docx
+
+# HTML to Markdown
+pandoc input.html -o output.md -f html -t markdown
+```
+
+### Advanced Pandoc Options
+
+```bash
+# Convert with custom template and styling
+pandoc input.md \
+  --output=output.pdf \
+  --pdf-engine=xelatex \
+  --template=eisvogel \
+  --highlight-style=tango \
+  --css=styles.css \
+  --variable=geometry:a4paper \
+  --variable=margin=1in
+
+# Resume generation optimized for ATS systems
+pandoc resume.md \
+  --output=resume.pdf \
+  --pdf-engine=xelatex \
+  --template=plain \
+  --variable=margin=1in \
+  --variable=fontsize=11pt \
+  --variable=fontfamily=noto
+```
+
+### Joplin Notes to PDF
+
+```bash
+# Convert Joplin note to PDF preserving formatting
+pandoc joplin_note.md \
+  --output=output.pdf \
+  --pdf-engine=xelatex \
+  --metadata=title:"Note Title" \
+  --variable=classoption=landscape \
+  --highlight-style=espresso
+```
+
+## 📘 mdBook Usage
+
+### Creating a Book
+
+```bash
+# Initialize a new book
+mdbook init mybook
+
+# Build the book
+mdbook build mybook -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output
+```
+
+### Serving Books
+
+```bash
+# Serve the book locally (useful during development)
+mdbook serve /data/mybook --hostname 0.0.0.0 --port 3000
+
+# Then access via http://localhost:3000
+```
+
+### Custom Configuration
+
+Create a `book.toml` file in your book directory:
+
+```toml
+[book]
+authors = ["Your Name"]
+language = "en"
+multilingual = false
+src = "."
+title = "My Book Title"
+
+[output.html]
+mathjax-support = true
+default-theme = "coal"
+preferred-dark-theme = "navy"
+```
+
+## ✍️ Typst Usage
+
+### Basic Document Creation
+
+Create a `.typ` file with Typst syntax:
+
+```typst
+#set page(width: 15cm, height: 20cm, margin: 2cm)
+
+= Introduction
+This is a basic Typst document.
+
+#figure(
+  image("diagram.png"),
+  caption: [Figure 1: A diagram]
+)
+```
+
+### Compiling Typst Documents
+
+```bash
+# Compile to PDF
+typst compile document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.pdf
+
+# Compile to PNG
+typst compile document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.png
+
+# Watch for changes
+typst watch document.typ /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/document.pdf
+```
+
+## 🎞️ Marp Usage
+
+### Creating Presentations
+
+Create a Markdown file with Marp-specific syntax:
+
+```markdown
+---
+marp: true
+theme: gaia
+_class: lead
+paginate: true
+backgroundColor: #fff
+backgroundImage: url('https://cdn.jsdelivr.net/gh/marp-team/marp@master/assets/hero-background.svg')
+---
+
+# Slide 1
+
+---
+
+# Slide 2
+- Point 1
+- Point 2
+```
+
+### Generating Presentations
+
+```bash
+# Convert to PDF
+marp presentation.md --pdf --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pdf
+
+# Convert to PPTX
+marp presentation.md --pptx --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pptx
+
+# Serve locally
+marp --server --port 8080
+```
+
+## 📊 Quarto Usage
+
+### Basic Document Rendering
+
+```bash
+# Render Quarto document to PDF
+quarto render document.qmd --to pdf
+
+# Render to HTML with interactive features
+quarto render document.qmd --to html --embed-resources
+
+# Render to DOCX
+quarto render document.qmd --to docx
+```
+
+### Advanced Quarto Features
+
+```bash
+# Create a parameterized report
+quarto render document.qmd --execute-params "dataset=dataset1;output_format=full" --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/report.pdf
+
+# Create a presentation
+quarto render presentation.qmd --to revealjs --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/slides.html
+```
+
+### Creating Projects
+
+```bash
+# Create a new book project
+quarto create-project mybook --type book
+
+# Create an article project
+quarto create-project article --type default
+```
+
+## 🚦 Kroki Usage
+
+### Generating Diagrams
+
+```bash
+# Create a PlantUML diagram
+kroki --file diagram.puml --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/diagram.svg
+
+# Generate block diagram in PNG format
+echo '@startuml\nAlice -> Bob: Hello\n@enduml' > simple.puml
+kroki --file simple.puml --type plantuml --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/simple.png
+```
+
+## 📜 Vale Usage
+
+### Linting Documents
+
+```bash
+# Check a single document
+vale /data/document.md
+
+# Check with specific configuration
+vale --config=/data/.vale.ini /data/document.md
+
+# Generate report in JSON format
+vale --output-style=JSON /data/document.md
+```
+
+## 🔧 Working with TeXLive
+
+### Custom LaTeX Documents
+
+```bash
+# Compile LaTeX with XeTeX (for better font support)
+xelatex -output-directory=/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output document.tex
+
+# Compile with pdflatex
+pdflatex -output-directory=/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output document.tex
+```
+
+## 📁 Best Practices
+
+### Organizing Work
+
+1. **Use the `/data` directory** for input files
+2. **Use the output directory** for generated documents
+3. **Create a local `config` directory** for custom configurations
+4. **Use volume mounts** for persistent work
+
+### Performance Tips
+
+1. **Use Docker volumes** instead of bind mounts for better performance when possible
+2. **Process multiple files** in a single container run to avoid startup overhead
+3. **Use appropriate memory allocation** for large document processing
+4. **Use specific tool versions** with mise for reproducibility
+
+### Security Considerations
+
+1. **The container runs as non-root user** (`tsysdevstack`)
+2. **No root access is available at runtime** to prevent security issues
+3. **Language runtimes are managed by mise** for consistent and secure tooling
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+- **Font Issues**: The container includes Noto fonts; for additional fonts, extend the container or mount font directories
+- **Memory Issues**: Increase Docker's memory allocation for processing large documents
+- **Permission Issues**: Ensure mounted volumes have appropriate permissions for UID 1000
+
+### Getting Help
+
+If you encounter issues:
+
+1. Check the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide
+2. Use the diagnostic commands from the troubleshooting guide
+3. Examine container logs: `docker logs <container-name>`
+4. Verify volume mappings and file accessibility