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

29
.devcontainer/devcontainer.json Normal file
View File

@@ -0,0 +1,29 @@
{
"name": "TSYSDevStack Toolboxes Docs",
"dockerComposeFile": "docker-compose.yml",
"service": "tsysdevstack-toolboxes-docs",
"workspaceFolder": "/home/tsysdevstack",
"settings": {
"terminal.integrated.defaultProfile.linux": "bash",
"terminal.integrated.profiles.linux": {
"bash": {
"path": "/bin/bash"
},
"zsh": {
"path": "/bin/zsh"
},
"fish": {
"path": "/usr/bin/fish"
}
}
},
"extensions": [
"ms-vscode.vscode-json",
"redhat.vscode-yaml",
"ms-vscode.powershell",
"GitHub.copilot",
"GitHub.copilot-chat"
],
"remoteUser": "tsysdevstack",
"postCreateCommand": "mise install"
}

206
Dockerfile Normal file
View File

@@ -0,0 +1,206 @@
# Use latest Debian stable as base image
FROM debian:stable-slim AS build
# Set environment variables
ENV DEBIAN_FRONTEND=noninteractive
ENV HOME=/home/tsysdevstack
ENV USER=tsysdevstack
ENV MISE_DATA_DIR=/home/tsysdevstack/.local/share/mise
ENV MISE_CONFIG_DIR=/home/tsysdevstack/.config/mise
ENV PATH=/home/tsysdevstack/.local/share/mise/shims:/home/tsysdevstack/.local/bin:/usr/local/bin:$PATH
# Install system dependencies (as root only during build time)
RUN apt-get update && \
apt-get install -y --no-install-recommends \
ca-certificates \
curl \
wget \
gnupg \
lsb-release \
git \
unzip \
zip \
build-essential \
python3 \
python3-pip \
python3-dev \
nodejs \
npm \
sudo \
locales \
fonts-noto \
fonts-noto-cjk \
fonts-noto-color-emoji \
fontconfig \
&& rm -rf /var/lib/apt/lists/* \
&& apt-get clean
# Set up locale
RUN echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen && \
locale-gen
# Create tsysdevstack user with specific UID/GID for consistency
RUN groupadd -g 1000 tsysdevstack && \
useradd -u 1000 -g tsysdevstack -m -s /bin/bash tsysdevstack && \
echo "tsysdevstack ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/tsysdevstack && \
chmod 0440 /etc/sudoers.d/tsysdevstack
# Switch to tsysdevstack user for remaining operations
USER tsysdevstack
WORKDIR /home/tsysdevstack
# Install mise (version managed)
RUN curl -fsSL https://mise.run | sh -s -- -y && \
# Add mise to PATH and source it in .bashrc
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc && \
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
# Install TeXLive for document generation
RUN mkdir -p /tmp/texlive && \
cd /tmp/texlive && \
wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz && \
tar -xzf install-tl-unx.tar.gz && \
cd install-tl-* && \
printf '%s\n' \
'selected_scheme scheme-basic' \
'TEXDIR /home/tsysdevstack/texlive' \
'TEXMFCONFIG /home/tsysdevstack/.texmf-config' \
'TEXMFVAR /home/tsysdevstack/.texmf-var' \
'option_doc 0' \
'option_src 0' \
> texlive.profile && \
./install-tl --profile=texlive.profile && \
cd / && \
rm -rf /tmp/texlive
ENV PATH=/home/tsysdevstack/texlive/bin/$(uname -m)-linuxmusl:$PATH
# Install additional TeXLive packages needed for PDF generation
RUN tlmgr install scheme-basic \
collection-latex \
collection-latexrecommended \
collection-latexextra \
collection-fontsrecommended \
xetex \
fontspec \
lualatex \
scheme-full \
&& mktexlsr
# Install pandoc with version pinning
RUN wget -q https://github.com/jgm/pandoc/releases/download/3.2/pandoc-3.2-1-amd64.deb -O /tmp/pandoc.deb && \
dpkg-deb -x /tmp/pandoc.deb /tmp/pandoc && \
cp -r /tmp/pandoc/usr/* /usr/local/ && \
rm /tmp/pandoc.deb /tmp/pandoc
# Install additional tools via system packages
RUN sudo apt-get update && \
sudo apt-get install -y --no-install-recommends \
jq \
yq \
wkhtmltopdf \
graphviz \
&& sudo rm -rf /var/lib/apt/lists/* \
&& sudo apt-get clean
# Set up mise for installing specific versions of tools
SHELL ["/bin/bash", "-c"]
RUN source ~/.bashrc && \
mise use --global python@3.12.6 && \
mise use --global node@21.7.3 && \
mise install
# Install tools via npm (using mise-managed Node.js)
RUN source ~/.bashrc && \
npm install -g mdbook@0.4.40 && \
npm install -g typst@0.12.0 && \
npm install -g @marp-team/marp-cli@3.4.0 && \
npm install -g markwhen@0.9.1 && \
npm install -g quarto-cli@1.6.17 && \
npm install -g vale@3.4.2
# Install tools via pip (using mise-managed Python)
RUN source ~/.bashrc && \
pip3 install --user kroki-cli==0.6.0 && \
pip3 install --user bibtool==3.2
# Install Rust-based tools
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH=/home/tsysdevstack/.cargo/bin:$PATH
RUN source ~/.bashrc && \
cargo install --version 0.8.0 ripgrep
# Install fish shell, zsh and other utilities
RUN sudo apt-get update && \
sudo apt-get install -y --no-install-recommends \
fish \
zsh \
&& sudo rm -rf /var/lib/apt/lists/* \
&& sudo apt-get clean
# Set up oh-my-zsh
RUN sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
# Final stage - create minimal runtime image
FROM debian:stable-slim
# Set environment variables
ENV DEBIAN_FRONTEND=noninteractive
ENV HOME=/home/tsysdevstack
ENV USER=tsysdevstack
ENV MISE_DATA_DIR=/home/tsysdevstack/.local/share/mise
ENV MISE_CONFIG_DIR=/home/tsysdevstack/.config/mise
ENV PATH=/home/tsysdevstack/.local/share/mise/shims:/home/tsysdevstack/.local/bin:/usr/local/bin:/home/tsysdevstack/texlive/bin/$(uname -m)-linuxmusl:$PATH
# Install minimal runtime dependencies
RUN apt-get update && \
apt-get install -y --no-install-recommends \
ca-certificates \
curl \
wget \
git \
python3 \
python3-pip \
nodejs \
npm \
sudo \
locales \
fonts-noto \
fonts-noto-cjk \
fonts-noto-color-emoji \
fontconfig \
wkhtmltopdf \
graphviz \
jq \
yq \
&& rm -rf /var/lib/apt/lists/* \
&& apt-get clean
# Set up locale
RUN echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen && \
locale-gen
# Create tsysdevstack user and group
RUN groupadd -g 1000 tsysdevstack && \
useradd -u 1000 -g tsysdevstack -m -s /bin/bash tsysdevstack && \
echo "tsysdevstack ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/tsysdevstack && \
chmod 0440 /etc/sudoers.d/tsysdevstack
# Copy installed tools from build stage
COPY --from=build /home/tsysdevstack/ /home/tsysdevstack/
COPY --from=build /usr/local/ /usr/local/
COPY --from=build /home/tsysdevstack/.cargo/bin/ /home/tsysdevstack/.cargo/bin/
# Set up workspace directory
RUN mkdir -p /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output && \
chown -R tsysdevstack:tsysdevstack /home/tsysdevstack/TSYSDevStack
# Switch to tsysdevstack user
USER tsysdevstack
WORKDIR /home/tsysdevstack
# Expose output directory
VOLUME ["/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output"]
# Default command
CMD ["/bin/bash"]

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>

193
build.sh Executable file
View File

@@ -0,0 +1,193 @@
#!/usr/bin/env bash
# build.sh - Script to build the tsysdevstack-toolboxes-docs container
set -e
# Default values
IMAGE_NAME="tsysdevstack/toolboxes-docs"
TAG="latest"
DOCKERFILE_PATH="Dockerfile"
BUILD_CONTEXT="."
PLATFORMS="linux/amd64,linux/arm64"
# Parse command line arguments
NO_CACHE=false
QUIET=false
SKIP_TESTS=false
while [[ $# -gt 0 ]]; do
case $1 in
--no-cache)
NO_CACHE=true
shift
;;
--quiet)
QUIET=true
shift
;;
--skip-tests)
SKIP_TESTS=true
shift
;;
--platforms)
PLATFORMS="$2"
shift 2
;;
-t|--tag)
TAG="$2"
shift 2
;;
-h|--help)
echo "Usage: $0 [OPTIONS]"
echo ""
echo "Options:"
echo " --no-cache Do not use cache when building"
echo " --quiet Suppress build output except final result"
echo " --skip-tests Skip running tests after build"
echo " --platforms Specify platforms to build for (default: $PLATFORMS)"
echo " -t, --tag Set image tag (default: $TAG)"
echo " -h, --help Show this help message"
echo ""
echo "Examples:"
echo " $0 # Build with default settings"
echo " $0 --no-cache # Build without using cache"
echo " $0 --tag v1.0.0 # Build with specific tag"
exit 0
;;
*)
echo "Unknown option: $1"
exit 1
;;
esac
done
# Function to validate prerequisites
check_prerequisites() {
echo "Checking prerequisites..."
# Check if Docker is available
if ! command -v docker &> /dev/null; then
echo "Error: Docker is not installed or not in PATH"
exit 1
fi
# Check if Docker daemon is running
if ! docker version &> /dev/null; then
echo "Error: Docker daemon is not running"
exit 1
fi
# Check if Docker Buildx is available
if ! docker buildx version &> /dev/null; then
echo "Error: Docker Buildx is not available"
exit 1
fi
echo "Prerequisites OK"
}
# Function to run QA checks before building
run_qa_checks() {
echo "Running QA checks..."
# Check if Dockerfile exists
if [ ! -f "$DOCKERFILE_PATH" ]; then
echo "Error: Dockerfile not found at $DOCKERFILE_PATH"
exit 1
fi
# Run hadolint on Dockerfile
echo "Running hadolint on Dockerfile..."
if command -v hadolint &> /dev/null; then
hadolint "$DOCKERFILE_PATH" || {
echo "Error: hadolint found issues in Dockerfile"
exit 1
}
else
echo "Warning: hadolint not found, skipping Dockerfile linting"
fi
# Run shellcheck on shell scripts
echo "Running shellcheck on scripts..."
for script in run.sh build.sh test.sh; do
if [ -f "$script" ]; then
if command -v shellcheck &> /dev/null; then
shellcheck "$script" || {
echo "Error: shellcheck found issues in $script"
exit 1
}
else
echo "Warning: shellcheck not found, skipping $script linting"
fi
fi
done
# Run yamllint on yaml files
echo "Running yamllint on YAML files..."
if command -v yamllint &> /dev/null; then
yamllint docker-compose.yml || {
echo "Error: yamllint found issues in docker-compose.yml"
exit 1
}
else
echo "Warning: yamllint not found, skipping docker-compose.yml linting"
fi
echo "QA checks passed"
}
# Function to build the image
build_image() {
echo "Building Docker image: $IMAGE_NAME:$TAG"
local build_args=()
if [ "$NO_CACHE" = true ]; then
build_args+=(--no-cache)
fi
if [ "$QUIET" = true ]; then
build_args+=(--quiet)
fi
# Use Docker Buildx for multi-platform build
docker buildx build \
--platform "$PLATFORMS" \
--tag "$IMAGE_NAME:$TAG" \
"${build_args[@]}" \
--load \
"$BUILD_CONTEXT"
echo "Image built successfully: $IMAGE_NAME:$TAG"
}
# Function to tag the image with additional tags if needed
tag_image() {
if [[ "$TAG" != "latest" ]]; then
echo "Tagging image as latest..."
docker tag "$IMAGE_NAME:$TAG" "$IMAGE_NAME:latest"
fi
}
# Main execution flow
main() {
check_prerequisites
run_qa_checks
build_image
tag_image
if [ "$SKIP_TESTS" = false ]; then
echo "Running tests after build..."
if [ -f "./test.sh" ]; then
./test.sh
else
echo "Warning: test.sh not found, skipping tests"
fi
else
echo "Skipping tests as requested"
fi
echo "Build completed successfully!"
}
main "$@"

19
docker-compose.yml Normal file
View File

@@ -0,0 +1,19 @@
version: '3.8'
services:
tsysdevstack-toolboxes-docs:
build:
context: .
dockerfile: Dockerfile
container_name: tsysdevstack-toolboxes-docs
volumes:
- ./output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output
- ./.config/mise:/home/tsysdevstack/.config/mise
- ./.local/share/mise:/home/tsysdevstack/.local/share/mise
working_dir: /home/tsysdevstack
environment:
- USER=tsysdevstack
- HOME=/home/tsysdevstack
stdin_open: true
tty: true
command: ["/bin/bash"]

118
documentation/CHEATSHEET.md Normal file
View File

@@ -0,0 +1,118 @@
# CHEATSHEET.md
## TSYSDevStack - Toolboxes - DocsAndDiagrams
Quick Reference for Document Production Tools
---
## 🐳 Docker Commands
| Task | Command |
|------|---------|
| Run interactively | `docker run -it --rm -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs` |
| Run specific command | `docker run --rm -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs <command>` |
| Build image | `docker build -t tsysdevstack/toolboxes-docs .` |
| Run with local files | `docker run --rm -v $(pwd):/data -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs` |
## 📝 Pandoc Commands
| Task | Command |
|------|---------|
| Markdown to PDF | `pandoc input.md -o output.pdf --pdf-engine=xelatex` |
| Markdown to DOCX | `pandoc input.md -o output.docx` |
| HTML to PDF | `pandoc input.html -o output.pdf --pdf-engine=xelatex` |
| With custom template | `pandoc input.md -o output.pdf --template=mytemplate --pdf-engine=xelatex` |
| Resume from Markdown | `pandoc resume.md -o resume.pdf --template=eisvogel --pdf-engine=xelatex` |
| Include CSS | `pandoc input.md -o output.pdf --css=styles.css --pdf-engine=xelatex` |
## 📘 mdBook Commands
| Task | Command |
|------|---------|
| Create new book | `mdbook init mybook` |
| Build book | `mdbook build /path/to/book -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output` |
| Serve book locally | `mdbook serve /path/to/book --hostname 0.0.0.0 --port 3000` |
| Watch and rebuild | `mdbook watch /path/to/book` |
## ✍️ Typst Commands
| Task | Command |
|------|---------|
| Compile document | `typst compile document.typ output.pdf` |
| Watch for changes | `typst watch document.typ output.pdf` |
| Export as PNG | `typst compile document.typ output.png` |
## 🎞️ Marp Commands
| Task | Command |
|------|---------|
| Convert to PDF | `marp input.md --pdf --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pdf` |
| Convert to PPTX | `marp input.md --pptx --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/presentation.pptx` |
| Serve presentation | `marp --server --port 8080` |
## 📊 Quarto Commands
| Task | Command |
|------|---------|
| Render document | `quarto render document.qmd --to pdf` |
| Convert to HTML | `quarto render document.qmd --to html` |
| Convert to DOCX | `quarto render document.qmd --to docx` |
| Render with custom format | `quarto render document.qmd --to revealjs` |
| Create new project | `quarto create-project myproject --type book` |
## 🚦 Kroki Commands
| Task | Command |
|------|---------|
| Convert diagram | `kroki --file diagram.yaml --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/diagram.svg` |
| Convert with format | `kroki --file diagram.txt --type blockdiag --output /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/diagram.png` |
## 📜 Vale Commands
| Task | Command |
|------|---------|
| Check document | `vale /path/to/document.md` |
| Check with specific style | `vale --config=/path/to/.vale.ini /path/to/document.md` |
## 🔧 System Tools
| Tool | Purpose | Example |
|------|---------|---------|
| `jq` | JSON processor | `echo '{"name":"test"}' | jq '.'` |
| `yq` | YAML processor | `yq '.key' file.yaml` |
| `wkhtmltopdf` | HTML to PDF | `wkhtmltopdf input.html output.pdf` |
| `bibtool` | Bibliography tool | `bibtool -s -i refs.bib` |
## 🛠️ Mise Commands
| Task | Command |
|------|---------|
| Install runtimes | `mise install` |
| Use specific Python version | `mise use --global python@3.12.6` |
| Use specific Node.js version | `mise use --global node@21.7.3` |
| Show current tools | `mise current` |
| Install specific tool | `mise install python@3.12.6` |
## 🌐 TeXLive Commands
| Task | Command |
|------|---------|
| Compile with XeTeX | `xelatex document.tex` |
| Compile with PDFLaTeX | `pdflatex document.tex` |
| Manage packages | `tlmgr install package-name` |
| Update packages | `tlmgr update --all` |
## 📁 Directory Locations
- **Input/Working Directory**: `/data` (when mounting local files)
- **Output Directory**: `/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output`
- **User Home**: `/home/tsysdevstack`
- **Mise Configuration**: `/home/tsysdevstack/.config/mise`
- **Mise Data**: `/home/tsysdevstack/.local/share/mise`
## 🔑 User Information
- **Username**: `tsysdevstack`
- **UID**: `1000`
- **Shell Options**: `bash`, `zsh`, `fish`

161
documentation/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,161 @@
# TROUBLESHOOTING.md
## TSYSDevStack - Toolboxes - DocsAndDiagrams
Troubleshooting Guide for the Document Production Workhorse Container
---
## 🐛 Common Issues and Solutions
### Docker Container Won't Start
**Issue**: Container fails to start with permission errors
**Solution**:
```bash
# Check if Docker daemon is running
sudo systemctl status docker
# If not running, start it
sudo systemctl start docker
# Ensure your user is in the docker group
sudo usermod -aG docker $USER
# Then log out and log back in
```
### Permission Denied Errors
**Issue**: Getting permission errors when accessing mounted volumes
**Solution**:
1. The container runs as user `tsysdevstack` with UID 1000
2. Ensure your host directory is writable by UID 1000:
```bash
sudo chown -R 1000:1000 /path/to/local/directory
```
3. Or run the container with appropriate user mapping:
```bash
docker run -u $(id -u):$(id -g) -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs
```
### Pandoc Fails with Font Errors
**Issue**: PDF generation fails with font-related errors
**Solution**:
1. The container includes Noto fonts, but you may need additional fonts:
```bash
# Check available fonts
fc-list
# Install additional fonts by extending the container
```
### Large Document Processing Issues
**Issue**: Container runs out of memory when processing large documents
**Solution**:
1. Increase Docker's memory allocation in Docker Desktop settings
2. Run with memory limits:
```bash
docker run --memory="4g" -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs
```
### TeXLive Compilation Fails
**Issue**: LaTeX compilation fails with missing packages
**Solution**:
1. The container includes a basic TeXLive installation with common packages
2. For additional packages, use `tlmgr`:
```bash
docker run -it tsysdevstack/toolboxes-docs tlmgr install package-name
```
### Missing Language Runtime Tools
**Issue**: Tools installed via npm/pip not working
**Solution**:
1. The container uses `mise` to manage language runtimes
2. Check if the runtime is properly configured:
```bash
mise current
```
3. Install or activate the required version:
```bash
mise use --global python@3.12.6 # or required version
```
### Quarto Rendering Issues
**Issue**: Quarto fails with missing R or Python environments
**Solution**:
1. The container has a basic Python environment but may need extensions:
```bash
# Install required Python packages
pip3 install jupyter numpy pandas matplotlib
```
## 🔧 Diagnostic Commands
### Check Container Information
```bash
# Check running containers
docker ps
# Check container logs
docker logs <container-name>
# Execute commands in running container
docker exec -it <container-name> /bin/bash
```
### Verify Tool Availability
```bash
# Check all installed tools
docker run --rm tsysdevstack/toolboxes-docs which pandoc mdbook typst marp quarto jq yq
# Check Pandoc version and capabilities
docker run --rm tsysdevstack/toolboxes-docs pandoc --version
# Check TeXLive installation
docker run --rm tsysdevstack/toolboxes-docs xelatex --version
```
### Check Storage and Paths
```bash
# Verify output directory exists and is writable
docker run --rm -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs ls -la /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output
# Check if input files are accessible
docker run --rm -v $(pwd)/:/data tsysdevstack/toolboxes-docs ls -la /data
```
## 🔍 Debugging Steps
1. **Check the error message carefully**
2. **Verify your input files exist and are accessible**
3. **Check that you have sufficient disk space**
4. **Try running a simple command first** (e.g., `pandoc --version`)
5. **Check container logs** if running as a service
6. **Verify volume mappings are correct**
7. **Test with a minimal document** to isolate issues
## 📞 Support
If you encounter issues not covered in this guide:
1. Check the [Usage Guide](USAGE.md) for correct command syntax
2. Review [Cheat Sheet](CHEATSHEET.md) for common commands
3. Search the repository issues for similar problems
4. Create a new issue with:
- Docker version
- Host OS
- Command used
- Error message
- Expected behavior

316
documentation/USAGE.md Normal file
View File

@@ -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

53
examples/README.md Normal file
View File

@@ -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

32
examples/basic-markdown.md Normal file
View File

@@ -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.

102
examples/doc-workflow.sh Executable file
View File

@@ -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!"

32
examples/example-document.typ Normal file
View File

@@ -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.

55
examples/presentation.md Normal file
View File

@@ -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)

34
output/joplin-note.md Normal file
View File

@@ -0,0 +1,34 @@
# Project Planning Meeting Notes
**Date:** October 26, 2023
**Attendees:** John, Sarah, Mike, Lisa
## Agenda
- Review project timeline
- Discuss resource allocation
- Address technical challenges
## Key Decisions
- Extend deadline by 2 weeks for backend development
- Allocate additional resources to testing phase
- Implement new authentication system
## Action Items
- [x] John: Complete API design by Nov 5
- [ ] Sarah: Prepare testing framework by Nov 10
- [ ] Mike: Set up staging environment by Nov 8
- [ ] Lisa: Review security requirements by Nov 3
## Discussion Points
- The initial timeline was too aggressive
- More time needed for integration testing
- Consider using external consultants for UI work
## Next Meeting
**Date:** November 2, 2023
**Time:** 10:00 AM
**Location:** Conference Room 3
## Attachments
- [API_Design_Draft.pdf](api_design_draft.pdf)
- [Resource_Allocation_Sheet.xlsx](resource_sheet.xlsx)

46
output/resume.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: John Doe - Software Engineer
author: John Doe
keywords: [software engineer, resume, ATS]
---
# John Doe
**Software Engineer**
Email: john.doe@example.com | Phone: (123) 456-7890
LinkedIn: linkedin.com/in/johndoe | GitHub: github.com/johndoe
---
## PROFESSIONAL SUMMARY
Experienced software engineer with 5+ years of expertise in designing, developing, and maintaining scalable web applications. Proficient in JavaScript, Python, and cloud technologies. Strong problem-solving skills with a passion for clean, efficient code.
## TECHNICAL SKILLS
**Programming Languages:** JavaScript (ES6+), Python, Java, TypeScript, SQL
**Frameworks & Libraries:** React, Node.js, Django, Express.js, Vue.js
**Tools & Technologies:** Git, Docker, Kubernetes, AWS, REST APIs, GraphQL
**Databases:** PostgreSQL, MongoDB, Redis
## PROFESSIONAL EXPERIENCE
**Senior Software Engineer** | TechCorp | 2020 - Present
- Developed and maintained microservices handling 1M+ daily requests
- Improved application performance by 40% through code optimization
- Mentored 3 junior developers and conducted code reviews
**Software Engineer** | StartupXYZ | 2018 - 2020
- Built responsive web applications using React and Node.js
- Implemented CI/CD pipelines reducing deployment time by 60%
- Collaborated with cross-functional teams to deliver features on schedule
## EDUCATION
**Bachelor of Science in Computer Science**
University of Technology | 2014 - 2018
## CERTIFICATIONS
- AWS Certified Developer - Associate (2021)
- MongoDB Certified Developer (2020)

28
output/test-document.md Normal file
View File

@@ -0,0 +1,28 @@
# Test Document
This is a test document to verify that the TSYSDevStack Toolboxes Docs container is working correctly.
## Features Tested
- [ ] Markdown to PDF conversion
- [ ] Markdown to DOCX conversion
- [ ] TeXLive/XeTeX rendering
- [ ] Font rendering
- [ ] Code block formatting
- [ ] Table formatting
## Code Example
```javascript
function hello() {
console.log("Hello, World!");
}
```
## Table Example
| Feature | Status | Notes |
|---------|--------|-------|
| Pandoc | ✅ | Working |
| TeXLive | ✅ | Working |
| Fonts | ✅ | Noto fonts available |

104
run.sh Executable file
View File

@@ -0,0 +1,104 @@
#!/usr/bin/env bash
# run.sh - Script to run the tsysdevstack-toolboxes-docs container
set -e
# Default values
CONTAINER_NAME="tsysdevstack-toolboxes-docs"
IMAGE_NAME="tsysdevstack/toolboxes-docs:latest"
WORKDIR="/home/tsysdevstack"
OUTPUT_DIR="/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output"
# Parse command line arguments
INTERACTIVE=true
DAEMON=false
CMD=""
while [[ $# -gt 0 ]]; do
case $1 in
-d|--daemon)
DAEMON=true
INTERACTIVE=false
shift
;;
-c|--command)
CMD="$2"
INTERACTIVE=false
shift 2
;;
-n|--name)
CONTAINER_NAME="$2"
shift 2
;;
-h|--help)
echo "Usage: $0 [OPTIONS] [COMMAND]"
echo ""
echo "Options:"
echo " -d, --daemon Run container in daemon mode"
echo " -c, --command Run a specific command in the container"
echo " -n, --name Specify container name (default: $CONTAINER_NAME)"
echo " -h, --help Show this help message"
echo ""
echo "Examples:"
echo " $0 # Run interactively"
echo " $0 -d # Run as daemon"
echo " $0 -c 'pandoc --version' # Run specific command"
exit 0
;;
*)
echo "Unknown option: $1"
exit 1
;;
esac
done
# Function to run the container
run_container() {
local extra_args=()
if [ "$INTERACTIVE" = true ]; then
extra_args+=(-it)
fi
if [ "$DAEMON" = true ]; then
extra_args+=(-d)
fi
if [ -n "$CMD" ]; then
docker run "${extra_args[@]}" \
--name "$CONTAINER_NAME" \
-v "$(pwd)/output:$OUTPUT_DIR" \
-w "$WORKDIR" \
"$IMAGE_NAME" \
bash -c "$CMD"
else
docker run "${extra_args[@]}" \
--name "$CONTAINER_NAME" \
-v "$(pwd)/output:$OUTPUT_DIR" \
-w "$WORKDIR" \
"$IMAGE_NAME"
fi
}
# Check if container is already running
if [ "$(docker ps -q -f name="$CONTAINER_NAME")" ]; then
echo "Container $CONTAINER_NAME is already running."
if [ -n "$CMD" ]; then
# Run command in existing container
docker exec -it "$CONTAINER_NAME" bash -c "$CMD"
else
# Attach to existing container
docker exec -it "$CONTAINER_NAME" /bin/bash
fi
elif [ "$(docker ps -aq -f name="$CONTAINER_NAME")" ]; then
# Container exists but is not running, start it
docker start "$CONTAINER_NAME" > /dev/null
if [ -n "$CMD" ]; then
docker exec -it "$CONTAINER_NAME" bash -c "$CMD"
else
docker attach "$CONTAINER_NAME"
fi
else
# Run new container
run_container
fi

101
test.sh Executable file
View File

@@ -0,0 +1,101 @@
#!/usr/bin/env bash
# test.sh - Script to test the tsysdevstack-toolboxes-docs container
set -e
# Default values
IMAGE_NAME="tsysdevstack/toolboxes-docs"
TAG="latest"
CONTAINER_NAME="test-tsysdevstack-toolboxes-docs"
TEST_DIR="/tmp/test-tsysdevstack-toolboxes-docs"
# Function to print test results
print_result() {
if [ $? -eq 0 ]; then
echo "✅ PASS: $1"
else
echo "❌ FAIL: $1"
exit 1
fi
}
# Function to run a command in the container and check the result
run_test_command() {
local test_name="$1"
local command="$2"
echo "Running test: $test_name"
docker run --rm --name "$CONTAINER_NAME-$(date +%s)" "$IMAGE_NAME:$TAG" bash -c "$command"
print_result "$test_name"
}
# Function to test if a command exists in the container
test_command_exists() {
local test_name="$1"
local command="$2"
run_test_command "$test_name" "which $command"
}
# Function to test if a specific version of a tool is available
test_version_command() {
local test_name="$1"
local command="$2"
local expected_version="$3"
echo "Running version test: $test_name"
docker run --rm --name "$CONTAINER_NAME-$(date +%s)" "$IMAGE_NAME:$TAG" bash -c "$command" | grep "$expected_version" > /dev/null
print_result "$test_name"
}
# Main test execution
main() {
echo "Starting tests for $IMAGE_NAME:$TAG..."
# Test that core utilities exist
test_command_exists "Check if pandoc exists" "pandoc"
test_command_exists "Check if mdbook exists" "mdbook"
test_command_exists "Check if typst exists" "typst"
test_command_exists "Check if marp exists" "marp"
test_command_exists "Check if markwhen exists" "markwhen"
test_command_exists "Check if quarto exists" "quarto"
test_command_exists "Check if jq exists" "jq"
test_command_exists "Check if yq exists" "yq"
test_command_exists "Check if wkhtmltopdf exists" "wkhtmltopdf"
test_command_exists "Check if bibtool exists" "bibtool"
test_command_exists "Check if vale exists" "vale"
test_command_exists "Check if kroki exists" "kroki"
test_command_exists "Check if fish shell exists" "fish"
test_command_exists "Check if zsh exists" "zsh"
test_command_exists "Check if bash exists" "bash"
# Test that TeXLive is properly installed
test_command_exists "Check if xelatex exists" "xelatex"
test_command_exists "Check if pdflatex exists" "pdflatex"
# Test that Python and Node.js are managed by mise
run_test_command "Check if Python is available via mise" "python --version"
run_test_command "Check if Node.js is available via mise" "node --version"
# Test that we can run a simple pandoc command
run_test_command "Test basic pandoc functionality" "echo '# Test' | pandoc -f markdown -t html | grep '<h1>Test</h1>'"
# Test that we can run a simple mdbook command
run_test_command "Test basic mdbook functionality" "mdbook --version"
# Test that we can run a simple typst command
run_test_command "Test basic typst functionality" "echo '# Hello' > /tmp/test.typ && typst compile /tmp/test.typ /tmp/test.pdf && [ -f /tmp/test.pdf ]"
# Test that user is not root
run_test_command "Check that default user is not root" "whoami | grep tsysdevstack"
# Test that required directories exist
run_test_command "Check that output directory exists" "[ -d /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output ]"
# Test that we can write to the output directory
run_test_command "Test write access to output directory" "touch /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/test_file.txt && [ -f /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output/test_file.txt ]"
echo "All tests passed! 🎉"
}
main