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.

examples/README.md

@@ -0,0 +1,53 @@
+# Example Documents for TSYSDevStack Toolboxes Docs
+
+This directory contains example documents and workflow scripts that demonstrate the capabilities of the document production workhorse container.
+
+## 📄 Document Examples
+
+### 1. Basic Markdown to PDF
+- `basic-markdown.md` - Simple markdown document for conversion to PDF
+- `basic-markdown.pdf` - Output PDF generated from the markdown
+
+### 2. Resume/CV Generation
+- `resume-template.tex` - LaTeX template for ATS-optimized resumes
+- `resume.md` - Markdown source for a resume
+- `resume.pdf` - Generated PDF resume
+
+### 3. Project Documentation
+- `project-plan.md` - Example project plan in markdown
+- `project-plan.pdf` - Generated PDF project plan
+
+### 4. Joplin Notes Conversion
+- `joplin-note.md` - Example Joplin note markdown
+- `joplin-note.pdf` - Converted PDF preserving formatting
+
+### 5. mdBook Example
+- `mybook/` - Complete mdBook project example
+- `mybook/src/SUMMARY.md` - Book structure
+- `mybook/src/chapter_1.md` - Sample chapter
+
+### 6. Typst Document
+- `scientific-document.typ` - Example Typst document
+- `scientific-document.pdf` - Generated PDF
+
+### 7. Marp Presentation
+- `presentation.md` - Example Marp presentation
+- `presentation.pdf` - Generated PDF slides
+
+### 8. Quarto Document
+- `analysis.qmd` - Example Quarto document with code execution
+- `analysis.pdf` - Generated analysis document
+
+## 🛠️ Workflow Scripts
+
+### 1. Batch Conversion Script
+- `batch-convert.sh` - Script to convert multiple markdown files to PDF
+
+### 2. Document Pipeline
+- `document-pipeline.sh` - Complete pipeline from source to final document
+
+### 3. Quality Assurance
+- `qa-check.sh` - Script to verify document quality and consistency
+
+### 4. Custom Styling
+- `custom-templates/` - Directory containing custom templates for various document types

examples/basic-markdown.md

@@ -0,0 +1,32 @@
+# Sample Markdown Document
+
+This is a sample markdown document to demonstrate the document conversion capabilities of the TSYSDevStack Toolboxes Docs container.
+
+## Features Demonstrated
+
+- Headers and subheaders
+- **Bold text**
+- *Italic text*
+- Lists
+  - Sublist item 1
+  - Sublist item 2
+- Code blocks:
+  ```python
+  def hello():
+      print("Hello, World!")
+  ```
+
+## Tables
+
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Item 1   | Item 2   | Item 3   |
+| Item 4   | Item 5   | Item 6   |
+
+## Images
+
+![Placeholder Image](https://placehold.co/600x400.png "Sample Image")
+
+## Conclusion
+
+This sample document demonstrates various markdown features that can be converted to beautiful PDFs using the Pandoc and TeXLive tools in this container.

examples/doc-workflow.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+
+# Example workflow script: Convert multiple markdown files to PDF
+# This script demonstrates a typical document generation workflow
+
+set -e  # Exit on any error
+
+echo "Starting document conversion workflow..."
+
+# Define input and output directories
+INPUT_DIR="/data"
+OUTPUT_DIR="/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output"
+WORKFLOW_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "Input directory: $INPUT_DIR"
+echo "Output directory: $OUTPUT_DIR"
+
+# Function to convert a markdown file to PDF
+convert_to_pdf() {
+    local input_file="$1"
+    local output_file="$2"
+    
+    echo "Converting $input_file to $output_file"
+    pandoc "$input_file" \
+        -o "$output_file" \
+        --pdf-engine=xelatex \
+        --variable=geometry:a4paper \
+        --variable=margin=1in \
+        --highlight-style=tango
+}
+
+# Function to convert a markdown file to DOCX
+convert_to_docx() {
+    local input_file="$1"
+    local output_file="$2"
+    
+    echo "Converting $input_file to $output_file"
+    pandoc "$input_file" -o "$output_file"
+}
+
+# Function to process mdBook
+build_mdbook() {
+    local book_dir="$1"
+    local output_dir="$2"
+    
+    echo "Building mdBook from $book_dir"
+    mdbook build "$book_dir" -d "$output_dir"
+}
+
+# Function to process Typst document
+compile_typst() {
+    local input_file="$1"
+    local output_file="$2"
+    
+    echo "Compiling Typst document $input_file to $output_file"
+    typst compile "$input_file" "$output_file"
+}
+
+# Convert all markdown files in the input directory
+for md_file in "$INPUT_DIR"/*.md; do
+    if [ -f "$md_file" ]; then
+        filename=$(basename "$md_file" .md)
+        echo "Processing markdown file: $filename"
+        
+        # Convert to PDF
+        convert_to_pdf "$md_file" "$OUTPUT_DIR/${filename}.pdf"
+        
+        # Convert to DOCX
+        convert_to_docx "$md_file" "$OUTPUT_DIR/${filename}.docx"
+        
+        echo "Completed conversion of $filename"
+    fi
+done
+
+# Process any mdBook directories
+for book_dir in "$INPUT_DIR"/book_*; do
+    if [ -d "$book_dir" ] && [ -f "$book_dir/book.toml" ]; then
+        echo "Found mdBook project: $book_dir"
+        build_mdbook "$book_dir" "$OUTPUT_DIR"
+    fi
+done
+
+# Process any Typst documents
+for typ_file in "$INPUT_DIR"/*.typ; do
+    if [ -f "$typ_file" ]; then
+        filename=$(basename "$typ_file" .typ)
+        echo "Processing Typst file: $filename"
+        compile_typst "$typ_file" "$OUTPUT_DIR/${filename}.pdf"
+    fi
+done
+
+# Generate a summary report
+echo "Conversion workflow completed!"
+echo "Generated documents are available in: $OUTPUT_DIR"
+
+# Count generated files
+pdf_count=$(find "$OUTPUT_DIR" -name "*.pdf" | wc -l)
+docx_count=$(find "$OUTPUT_DIR" -name "*.docx" | wc -l)
+echo "Total PDFs generated: $pdf_count"
+echo "Total DOCX files generated: $docx_count"
+
+echo "Workflow completed successfully!"

examples/example-document.typ

@@ -0,0 +1,32 @@
+// Example Typst document
+#set page(width: 15cm, height: 20cm, margin: 2cm)
+#set text(font: "Noto Sans", size: 12pt)
+
+= Introduction to Typst
+
+This is a simple example document created with Typst, a modern markup-based typesetting system.
+
+== Features
+
+Typst offers several advantages:
+
+- #lorem(10)
+- Mathematical typesetting: $f(x) = x^2$
+- #list(
+  , "Fast processing"
+  , "Template system"
+  , "Symbol collections"
+)
+
+== Code Example
+
+Here's how to include code:
+
+```typst
+= Title
+Lorem ipsum #lorem(50)
+```
+
+= Conclusion
+
+Typst provides a modern alternative to LaTeX for document creation with a simpler syntax and fast compilation.

examples/presentation.md

@@ -0,0 +1,55 @@
+---
+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')
+---
+
+# TSYSDevStack Documentation Tools
+
+*Modern Document Production Workhorse*
+
+---
+
+## Agenda
+
+- Overview of Tools
+- Pandoc for Conversion
+- mdBook for Documentation
+- Typst for Typesetting
+- Marp for Presentations
+- Quarto for Scientific Publishing
+
+---
+
+## Pandoc
+
+- Universal document converter
+- Supports 50+ formats
+- High-quality PDF output with TeXLive
+
+```markdown
+pandoc input.md -o output.pdf --pdf-engine=xelatex
+```
+
+---
+
+## mdBook
+
+- Create books from Markdown
+- Multiple output formats
+- Customizable themes
+
+```bash
+mdbook build mybook -d output/
+```
+
+---
+
+## Thank You
+
+*Questions?*
+
+[github.com/tsysdevstack/toolboxes-docs](https://github.com/tsysdevstack/toolboxes-docs)