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

Compare commits

base: KNEL:vk/cb89-create-toolbox-d
Branches Tags
KNEL:main KNEL:vk/50a0-toolboxes-docs KNEL:vk/cb89-create-toolbox-d
..
compare: KNEL:vk/50a0-toolboxes-docs
Branches Tags
KNEL:main KNEL:vk/50a0-toolboxes-docs KNEL:vk/cb89-create-toolbox-d

1 Commits
vk/cb89-cr ... vk/50a0-to

Author SHA1 Message Date
ReachableCEO
544d1c31e5 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
32 changed files with 1902 additions and 1512 deletions
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

137
toolbox-docs/Dockerfile
View File

@@ -1,137 +0,0 @@
# Use latest Debian stable as base image
FROM debian:stable-slim
# Build arguments for version pinning
ARG DEBIAN_FRONTEND=noninteractive
ARG TSDS_USER=tsysdevstack
ARG TSDS_UID=1000
ARG TSDS_GID=1000
# Install dependencies for system packages (apt-get) - pin all versions
RUN apt-get update && \
apt-get install -y --no-install-recommends \
ca-certificates=20240224 \
curl=8.6.0-1 \
wget=1.21.4-1 \
gnupg=2.2.41-1 \
gosu=1.12-5 \
git=1:2.43.0-1 \
unzip=6.0-28 \
zip=3.0-13 \
python3=3.11.2-1+b1 \
python3-pip=23.3.1+dfsg-1 \
python3-venv=3.11.2-1+b1 \
openssh-client=1:9.6p1-3 \
dumb-init=1.2.5-2 \
build-essential=12.9 \
texlive-full=2023.20230707-5 \
fonts-noto=20231023-1 \
fonts-noto-cjk=1:20221122+urwcyr1.0.7~dfsg-6 \
fonts-noto-color-emoji=20231023-1 \
fonts-liberation2=2.1.5-1 \
fonts-roboto=2:20230915-1 \
fonts-dejavu=2.37-6 \
fonts-opensymbol=2:102.12+LibO7.4.7-1 \
fonts-liberation=1:1.07.4-12 \
jq=1.6-2.1 \
yq=4.25.2+ds1-1 \
nodejs=1:21.7.3-1nodesource1 \
npm=10.2.4+ds-4 \
&& \
apt-get clean && \
rm -rf /var/lib/apt/lists/*
# Create group and user with specific UID/GID
RUN groupadd -g ${TSDS_GID} ${TSDS_USER} && \
useradd -u ${TSDS_UID} -g ${TSDS_GID} -m -s /bin/bash -l ${TSDS_USER}
# Install mise as the tsysdevstack user
USER ${TSDS_USER}
WORKDIR /home/${TSDS_USER}
# Install mise (version-pinned)
RUN curl -fsSL https://mise.run | bash -s -- -y && \
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
# Add mise to PATH and activate
ENV PATH="/home/${TSDS_USER}/.local/bin:${PATH}"
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
RUN echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc && \
bash -c 'source ~/.bashrc'
# Create a directory structure for the tools
RUN mkdir -p ~/tools
# Install fish, bash, and zsh shells and set fish as default for the user
USER root
RUN apt-get update && \
apt-get install -y --no-install-recommends \
fish=3.7.0-1+b4 \
zsh=5.9-4+b2 \
&& \
apt-get clean && \
rm -rf /var/lib/apt/lists/* && \
chsh -s /usr/bin/fish ${TSDS_USER}
# Install additional fonts and tools for document generation
USER ${TSDS_USER}
RUN mkdir -p ~/.config/fish && \
echo "set -g fish_greeting" > ~/.config/fish/config.fish
# Install Rust via mise to support various tools
RUN ~/.local/bin/mise use --global rust@1.78.0 && \
~/.local/bin/mise exec -- rustup component add rust-src
# Install Node.js via mise
RUN ~/.local/bin/mise use --global node@21.7.3
# Install Python via mise
RUN ~/.local/bin/mise use --global python@3.11.9
# Install Ruby via mise
RUN ~/.local/bin/mise install ruby@3.3.0
# Install tools via npm (using mise-managed Node) and Pandoc
USER root
RUN ~/.local/bin/mise exec -- npm install -g \
mdbook@0.4.36 \
@marp-team/marp-cli@3.3.0 \
quarto-cli@1.5.57 \
kroki-cli@0.7.0 \
markwhen@0.7.10 \
vale@3.0.6 && \
curl -L -o pandoc.deb https://github.com/jgm/pandoc/releases/download/3.1.11.1/pandoc-3.1.11.1-1-amd64.deb && \
dpkg -i pandoc.deb && \
rm pandoc.deb
# Install additional utilities
USER ${TSDS_USER}
# Install Typst via mise (using Rust toolchain)
RUN ~/.local/bin/mise exec -- cargo install typst --version 0.12.0
# Install wkhtmltopdf
USER root
RUN apt-get update && \
apt-get install -y --no-install-recommends \
wkhtmltopdf=0.12.6.1-2 \
&& \
apt-get clean && \
rm -rf /var/lib/apt/lists/*
# Install bibtool
USER root
RUN apt-get update && \
apt-get install -y --no-install-recommends \
bibtool=2.72-2 \
&& \
apt-get clean && \
rm -rf /var/lib/apt/lists/*
# Set up working directory for documents
USER ${TSDS_USER}
WORKDIR /home/${TSDS_USER}/docs
# Set up entrypoint with dumb-init for proper signal handling
ENTRYPOINT ["/usr/bin/dumb-init", "--"]
CMD ["/bin/fish"]

162
toolbox-docs/README.md
View File

@@ -1,162 +0,0 @@
# TSYS Dev Stack - Docs Toolbox
<div align="center">
[![Docker Image Size](https://img.shields.io/docker/image-size/tsysdevstack/toolbox-docs)](https://hub.docker.com/r/tsysdevstack/toolbox-docs)
[![Docker Pulls](https://img.shields.io/docker/pulls/tsysdevstack/toolbox-docs)](https://hub.docker.com/r/tsysdevstack/toolbox-docs)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/tsysdevstack/toolbox-docs)
</div>
> 🔧 **A comprehensive document production environment**
> A Docker container optimized for generating beautiful documents from various source formats
## ✨ Features
- **Complete Document Toolchain**: Pandoc, mdBook, Typst, Marp, Quarto, and more
- **Beautiful PDF Generation**: With TeXLive, XeTeX support, and rich fonts
- **Multiple Output Formats**: Convert from Markdown to PDF, DOCX, HTML, and more
- **Security First**: Runs as non-root user with minimal runtime privileges
- **Cross-Platform**: Works on PC, Raspberry Pi, and Mac M series devices
- **Reproducible Builds**: All dependencies version-pinned for consistency
## 🚀 Quick Start
### Prerequisites
- Docker 20.10+
- Docker Buildx plugin
### Build and Run
```bash
# Clone the repository (if needed)
git clone https://github.com/tsysdevstack/toolbox-docs.git
cd toolbox-docs
# Build the image
./build.sh
# Run the container
./run.sh
```
### Using Docker Compose
```bash
# Build and run with docker-compose
docker-compose up --build
```
## 🛠️ Included Tools
| Tool | Purpose | Documentation |
|------|---------|---------------|
| [Pandoc](https://pandoc.org/) | Universal document converter | [Usage Guide](./documentation/USAGE.md#pandoc) |
| [mdBook](https://rust-lang.github.io/mdBook/) | Create books from markdown | [Usage Guide](./documentation/USAGE.md#mdbook) |
| [Typst](https://typst.app/) | Modern typesetting system | [Usage Guide](./documentation/USAGE.md#typst) |
| [Marp](https://marp.app/) | Create slide decks from markdown | [Usage Guide](./documentation/USAGE.md#marp) |
| [Quarto](https://quarto.org/) | Scientific publishing system | [Usage Guide](./documentation/USAGE.md#quarto) |
| [TeXLive](https://www.tug.org/texlive/) | Professional typesetting suite | [PDF Generation](./documentation/USAGE.md#document-conversion-workflows) |
| [Wkhtmltopdf](https://wkhtmltopdf.org/) | HTML to PDF converter | [PDF Generation](./documentation/USAGE.md#document-conversion-workflows) |
| [Vale](https://valelint.github.io/) | Syntax-aware linter | [Documentation](./documentation/USAGE.md) |
| [JQ/YQ](https://stedolan.github.io/jq/) | JSON/YAML processor | [Cheatsheet](./documentation/CHEATSHEET.md) |
## 📚 Common Workflows
### Markdown to Professional PDF
```bash
# For resumes (ATS optimized)
pandoc resume.md -o resume.pdf --template=altacv
# For project plans and proposals
pandoc document.md -o document.pdf --template=eisvogel
```
### Joplin Notes to PDF
```bash
# Preserve Joplin's formatting when converting to PDF
pandoc joplin_note.md -o note.pdf --css=styles.css
```
### Book Generation
```bash
# Initialize and build a book
mdbook init my-book
cd my-book
mdbook build
```
### Presentation Creation
```bash
# Create slide deck from markdown
marp --pdf slides.md
```
See [USAGE.md](./documentation/USAGE.md) for complete workflows and examples.
## 🏗️ Project Structure
```
toolbox-docs/
├── Dockerfile # Multi-stage build with security best practices
├── docker-compose.yml # Docker Compose configuration
├── devcontainer.json # VS Code Dev Container configuration
├── run.sh # Script to run the container
├── build.sh # Script to build the container
├── test.sh # Test script for CI/CD
├── docs/ # Working directory for documents
├── examples/ # Example documents and workflows
├── documentation/ # Usage, troubleshooting guides
│ ├── USAGE.md
│ ├── TROUBLESHOOTING.md
│ └── CHEATSHEET.md
└── output/ # Generated documents output
```
## 🛡️ Security
- **Zero Root Runtime**: Container runs as `tsysdevstack` user with no root access
- **Minimal Build Privileges**: Root only used during build for package installation
- **Principle of Least Privilege**: Only necessary tools and permissions included
- **Hardened Image**: Security best practices applied throughout the build process
## 🚢 CI/CD Integration
Use the provided scripts in your CI/CD pipeline:
```bash
# Build for multiple platforms
./build.sh -p linux/amd64,linux/arm64
# Run tests
./test.sh
# Push to registry (requires auth)
./build.sh --push
```
## 📖 Documentation
- [Usage Guide](./documentation/USAGE.md) - Complete usage instructions
- [Troubleshooting](./documentation/TROUBLESHOOTING.md) - Common issues and solutions
- [Cheatsheet](./documentation/CHEATSHEET.md) - Quick reference for common commands
- [Examples](./examples/) - Sample documents and workflows
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
<div align="center">
**TSYS Dev Stack - Docs Toolbox** © 2025 | A [TSYS Group](https://www.tsys.com/) Project
[![TSYS Group](https://img.shields.io/badge/TSYS_Group-Dev_Stack-blue?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDJDNi40ODYgMiAyIDYuNDg2IDIgMTJzNC40ODYgMTAgMTAgMTAgMTAtNC40ODYgMTAtMTBTMTcuNTE0IDIgMTIgMnptMCAxOGMtNC40MTEgMC04LTMuNTg5LTgtOHMzLjU4OS04IDgtOCA4IDMuNTg5IDggOC0zLjU4OSA4LTggOHoiLz48L3N2Zz4=)](https://www.tsys.com/)
</div>

105
toolbox-docs/build.sh
View File

@@ -1,105 +0,0 @@
#!/usr/bin/env bash
# Script to build the tsysdevstack-toolboxes-docs container
set -e
# Default values
IMAGE_NAME="tsysdevstack/toolbox-docs"
BUILD_ARGS=""
PLATFORMS="linux/amd64,linux/arm64,linux/arm/v7" # Support PC, Raspberry Pi, Mac M series
# Function to display usage
usage() {
echo "Usage: $0 [OPTIONS]"
echo "Options:"
echo " -p, --platform PLATFORM Target platform (default: all supported)"
echo " -t, --tag TAG Tag for the image (default: latest)"
echo " -c, --cache Use build cache (default: true)"
echo " --no-cache Skip build cache"
echo " --push Push image to registry after building"
echo " -h, --help Show this help message"
echo ""
echo "Examples:"
echo " $0 # Build for all platforms"
echo " $0 -p linux/amd64 # Build for x86_64"
echo " $0 -t v1.0.0 # Build with specific tag"
echo " $0 --no-cache # Build without cache"
echo " $0 --push # Build and push to registry"
}
# Parse command line arguments
PLATFORM=""
TAG="latest"
USE_CACHE=true
PUSH=false
while [[ $# -gt 0 ]]; do
case $1 in
-p|--platform)
PLATFORM="$2"
shift 2
;;
-t|--tag)
TAG="$2"
shift 2
;;
-c|--cache)
USE_CACHE=true
shift
;;
--no-cache)
USE_CACHE=false
shift
;;
--push)
PUSH=true
shift
;;
-h|--help)
usage
exit 0
;;
*)
echo "Unknown option: $1"
usage
exit 1
;;
esac
done
# Build the image using Docker Buildx for multi-platform support
echo "Building tsysdevstack/toolbox-docs Docker image..."
# Create buildx builder if it doesn't exist
if ! docker buildx ls | grep -q "tsysdevstack-builder"; then
echo "Creating buildx builder instance..."
docker buildx create --name tsysdevstack-builder --use --bootstrap
fi
# Prepare build arguments
BUILD_ARGS="--progress=plain --platform=${PLATFORM:-$PLATFORMS} --tag ${IMAGE_NAME}:${TAG}"
if [ "$USE_CACHE" = false ]; then
BUILD_ARGS="$BUILD_ARGS --no-cache"
fi
if [ "$PUSH" = true ]; then
BUILD_ARGS="$BUILD_ARGS --push"
else
BUILD_ARGS="$BUILD_ARGS --load" # Load to local Docker image store
fi
# Execute the build command
BUILD_CMD="docker buildx build $BUILD_ARGS ."
echo "Running: $BUILD_CMD"
if eval "$BUILD_CMD"; then
echo "Build completed successfully!"
if [ "$PUSH" = true ]; then
echo "Image pushed to registry."
else
echo "Image loaded to local Docker image store."
fi
else
echo "Build failed!"
exit 1
fi

42
toolbox-docs/devcontainer.json
View File

@@ -1,42 +0,0 @@
{
"name": "TSYS Dev Stack - Docs",
"dockerFile": "Dockerfile",
"runArgs": [
"--userns=keep-id"
],
"remoteUser": "tsysdevstack",
"workspaceFolder": "/home/tsysdevstack/docs",
"workspaceMount": "source=${localWorkspaceFolder}/docs,target=/home/tsysdevstack/docs,type=bind",
"mounts": [
"source=${localWorkspaceFolder}/output,target=/home/tsysdevstack/output,type=bind"
],
"features": {},
"customizations": {
"vscode": {
"extensions": [
"ms-vscode.vscode-json",
"redhat.vscode-yaml",
"ms-vscode.powershell",
"ms-vsliveshare.vsliveshare",
"yzhang.markdown-all-in-one",
"shd101.windicss-intellisense",
"bradlc.vscode-tailwindcss",
"esbenp.prettier-vscode",
"ms-python.python",
"ms-python.black-formatter",
"ms-toolsai.jupyter",
"ms-toolsai.jupyter-keymap",
"ms-toolsai.jupyter-renderers"
],
"settings": {
"terminal.integrated.defaultProfile.linux": "fish",
"terminal.integrated.profiles.linux": {
"fish": {
"path": "/usr/bin/fish"
}
}
}
}
},
"postCreateCommand": "chown -R tsysdevstack:tsysdevstack /home/tsysdevstack/docs /home/tsysdevstack/output"
}

22
toolbox-docs/docker-compose.yml
View File

@@ -1,22 +0,0 @@
version: '3.8'
services:
docs:
build:
context: .
dockerfile: Dockerfile
container_name: tsysdevstack-toolboxes-docs
user: "${TSDS_UID:-1000}:${TSDS_GID:-1000}"
environment:
- HOME=/home/tsysdevstack
- USER=tsysdevstack
volumes:
- ./docs:/home/tsysdevstack/docs
- ./output:/home/tsysdevstack/output
- ~/.ssh:/home/tsysdevstack/.ssh:ro
- /etc/passwd:/etc/passwd:ro
- /etc/group:/etc/group:ro
working_dir: /home/tsysdevstack/docs
stdin_open: true
tty: true
command: /bin/fish

227
toolbox-docs/documentation/CHEATSHEET.md
View File

@@ -1,227 +0,0 @@
# Cheatsheet - TSYS Dev Stack Docs Toolbox
## Table of Contents
- [Quick Commands](#quick-commands)
- [Pandoc Conversions](#pandoc-conversions)
- [MdBook Commands](#mdbook-commands)
- [Typst Commands](#typst-commands)
- [Marp Commands](#marp-commands)
- [Quarto Commands](#quarto-commands)
- [Document Templates](#document-templates)
- [File Locations](#file-locations)
## Quick Commands
| Task | Command |
|------|---------|
| Run container interactively | `./run.sh` |
| Build image | `./build.sh` |
| Run tests | `./test.sh` |
| Run detached container | `./run.sh -d` |
| Build and run | `./run.sh -b` |
## Pandoc Conversions
### Markdown to PDF
```bash
# Basic conversion
pandoc input.md -o output.pdf
# With a specific template (e.g., for resumes)
pandoc input.md -o output.pdf --template=altacv --pdf-engine=xelatex
# With custom CSS (for HTML)
pandoc input.md -o output.html --css=styles.css
```
### Advanced Pandoc Options
```bash
# Include metadata for title page
pandoc --metadata title="Document Title" --metadata author="Author Name" input.md -o output.pdf
# Use specific LaTeX engine for different fonts
pandoc input.md -o output.pdf --pdf-engine=xelatex
# Include TOC and specify depth
pandoc input.md -o output.pdf --toc --toc-depth=2
```
## MdBook Commands
### Basic Operations
```bash
# Create a new book
mdbook init mybook
# Build the book
mdbook build
# Serve with live reload
mdbook serve
# Open in browser after serving
mdbook serve --open
```
### Directory Structure
```
mybook/
├── book.toml # Configuration file
├── src/
│ ├── SUMMARY.md # Table of contents
│ ├── chapter_1.md
│ └── chapter_2.md
└── book/ # Generated files (ignored by git)
```
## Typst Commands
### Compilation
```bash
# Compile to PDF
typst compile document.typ document.pdf
# Watch for changes and recompile
typst watch document.typ
# Format the document
typst format document.typ
```
## Marp Commands
### Slide Generation
```bash
# Convert to PDF slides
marp --pdf slides.md
# Convert to HTML slides
marp --html slides.md
# Serve with live preview
marp --server slides.md
# Use custom theme
marp --theme custom-theme.css slides.md
```
### Marp Slide Format
```markdown
---
marp: true
theme: gaia
_class: lead
paginate: true
backgroundColor: ffffff
backgroundImage: url('https://cdn.url-to-image')
---
# Page 1
---
# Page 2
```
## Quarto Commands
### Document Rendering
```bash
# Basic render
quarto render document.qmd
# Render to specific format
quarto render document.qmd --to pdf
quarto render document.qmd --to html
quarto render document.qmd --to docx
# Render with custom format
quarto render document.qmd --to revealjs # For presentations
```
### Project Creation
```bash
# Create a new project
quarto create-project myproject --type default
quarto create-project mybook --type book
quarto create-project myslides --type presentation
```
## Document Templates
### Standard Markdown Template
```markdown
---
title: "Document Title"
author: ["Author Name"]
date: "2025-01-01"
lang: "en"
header-includes:
- \usepackage{fancyhdr}
- \pagestyle{fancy}
---
# Section Title
Content goes here...
## Subsection
More content here...
```
### Resume Markdown Template (for Pandoc)
```markdown
---
title: "John Doe"
author: []
date: []
output:
pdf_document:
template: altacv
pandoc_args: ["--top-level-division=section"]
---
# Personal Info
**Address:** 123 Main St, City, State
**Phone:** (555) 123-4567
**Email:** john.doe@example.com
**LinkedIn:** [johndoe](https://linkedin.com/in/johndoe)
# Experience
## Job Title
**Company Name** | Month Year - Present
- Point 1
- Point 2
```
## File Locations
### Container Paths
- Working directory: `/home/tsysdevstack/docs`
- Output directory: `/home/tsysdevstack/output`
- User home: `/home/tsysdevstack`
- Mise tools: `~/.local/share/mise`
### Host Paths (when using run.sh)
- Source documents: `./docs`
- Output documents: `./output`
- Examples: `./examples`
- Documentation: `./documentation`
### Mise Management
```bash
# Check currently managed tools
mise ls
# Install a new version of a tool
mise install python@3.12.0
# Switch to a specific version
mise use python@3.12.0
# Execute command with specific tool version
mise exec -- python script.py
```

152
toolbox-docs/documentation/TROUBLESHOOTING.md
View File

@@ -1,152 +0,0 @@
# Troubleshooting Guide - TSYS Dev Stack Docs Toolbox
## Table of Contents
- [Common Issues](#common-issues)
- [Docker-related Issues](#docker-related-issues)
- [Tool-specific Issues](#tool-specific-issues)
- [Performance Issues](#performance-issues)
- [Security Considerations](#security-considerations)
## Common Issues
### Container Won't Start
**Problem**: The container fails to start with an error.
**Solution**:
1. Check if Docker is running:
```bash
docker info
```
2. Check if the image exists:
```bash
docker images | grep tsysdevstack/toolbox-docs
```
3. If the image doesn't exist, build it:
```bash
./build.sh
```
### Permission Issues
**Problem**: Getting permission errors when accessing files.
**Solution**: The container runs as the `tsysdevstack` user. Ensure your host files have appropriate permissions:
```bash
# Change ownership to match the container user (UID 1000)
sudo chown -R 1000:1000 ./docs ./output
```
### Tools Not Found
**Problem**: Commands like `pandoc`, `mdbook`, etc. are not found.
**Solution**: Ensure you're running inside the container:
```bash
# Run the container interactively to use the tools
./run.sh
# Then run your command inside the container
pandoc --version
```
## Docker-related Issues
### Image Build Fails
**Problem**: Building the image fails with errors.
**Solution**:
1. Make sure you're using the latest version of Docker
2. Increase Docker's memory allocation if building fails
3. Clear Docker build cache:
```bash
docker builder prune
```
### Large Image Size
**Problem**: The image is very large due to TeXLive and other tools.
**Solution**: The image is intentionally comprehensive for document generation. You can create a custom minimal image if needed, but this full image provides the most functionality.
### Multi-platform Build Issues
**Problem**: Build fails when targeting specific platforms.
**Solution**:
```bash
# Try building for your current platform only
./build.sh -p $(docker buildx imagetools inspect --format '{{json .Manifest}}' hello-world | jq -r '.platform.architecture')
```
## Tool-specific Issues
### Pandoc Issues
**Problem**: Pandoc fails when converting documents.
**Solution**:
- Check if your input file is properly formatted
- For PDF output, ensure TeXLive is properly installed (it should be in this container)
- For custom templates, ensure the template file is available in the container:
```bash
# Check if template exists
ls -la /home/tsysdevstack/.pandoc/templates/
```
### MdBook Issues
**Problem**: MdBook fails to build or serve books.
**Solution**:
- Verify that your `SUMMARY.md` and `book.toml` files are properly formatted
- Check that all referenced files exist in your book directory
- Make sure you're running mdbook from the book's root directory (where `book.toml` is)
### Typst Issues
**Problem**: Typst fails to compile documents.
**Solution**:
- Check if your Typst syntax is correct
- Ensure you have fonts available in the container
- Look at the error message for specific file or syntax issues
### Marp Issues
**Problem**: Marp doesn't generate PDFs correctly.
**Solution**:
- Make sure your markdown uses correct Marp slide delimiters
- Check for any custom CSS that might be causing rendering issues
- Ensure the container has internet access for downloading themes (if needed)
### Quarto Issues
**Problem**: Quarto fails to render documents.
**Solution**:
- Verify that required dependencies (like Python, R, etc.) are properly available
- Check if extensions are properly installed
- Look for environment-specific issues that might affect rendering
## Performance Issues
### Slow Document Generation
**Problem**: Converting documents takes a very long time.
**Solution**:
- For PDF generation, TeXLive compilation is naturally slower than other formats
- Consider using HTML output for faster preview during editing
- For large documents, consider breaking them into smaller sections
### High Memory Usage
**Problem**: Container uses excessive memory.
**Solution**: For resource-intensive operations like full TeXLive compilation, ensure Docker has sufficient memory allocated (at least 4GB recommended).
## Security Considerations
### Root Access
**Problem**: Concerned about running with root access.
**Solution**: This container is designed to run as the `tsysdevstack` user with no root access at runtime. The only root usage is during the build process for installing system packages.
### Network Security
**Problem**: Need to run without network access.
**Solution**: The container can run offline once built. It can perform all document generation tasks without network access, though some features like fetching remote templates or themes would be unavailable.
### File Access
**Problem**: Container can access files it shouldn't.
**Solution**: The container only has access to files in the `/docs` and `/output` directories that you explicitly mount. Files outside these directories are not accessible.

176
toolbox-docs/documentation/USAGE.md
View File

@@ -1,176 +0,0 @@
# Usage Guide - TSYS Dev Stack Docs Toolbox
## Table of Contents
- [Overview](#overview)
- [Running the Container](#running-the-container)
- [Available Tools](#available-tools)
- [Document Conversion Workflows](#document-conversion-workflows)
- [Development Workflows](#development-workflows)
## Overview
The TSYS Dev Stack Docs Toolbox is a comprehensive document production environment with all the tools you need to create beautiful documents from various source formats. This container runs as the `tsysdevstack` user with no root access, ensuring security while providing a powerful document creation toolkit.
## Running the Container
### Using the Run Script
```bash
# Run interactively (default)
./run.sh
# Run in detached mode
./run.sh -d
# Build the image first, then run
./run.sh -b
# Build and run in detached mode
./run.sh -b -d
```
### Using Docker Compose
```bash
# Run the container with docker-compose
docker-compose up
# Run and build if needed
docker-compose up --build
# Run in detached mode
docker-compose up -d
```
### Direct Docker Run
```bash
# Run with direct docker command
docker run -it --rm \
-v $(pwd)/docs:/home/tsysdevstack/docs \
-v $(pwd)/output:/home/tsysdevstack/output \
tsysdevstack/toolbox-docs:latest
```
## Available Tools
### Pandoc
Convert documents between various formats with powerful templating capabilities:
```bash
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o output.html
```
### MdBook
Create books and documentation sites from markdown files:
```bash
# Build a book
mdbook build
# Serve a book locally with live reload
mdbook serve
# Create a new book
mdbook init mybook
```
### Typst
Modern typesetting tool for scientific and technical documents:
```bash
# Compile a typst document
typst compile document.typ document.pdf
# Watch for changes and recompile
typst watch document.typ
```
### Marp
Create slide decks from markdown:
```bash
# Convert markdown to PDF slides
marp --pdf slides.md
# Convert to HTML
marp --html slides.md
# Serve slides with live preview
marp --server slides.md
```
### Quarto
Next generation scientific and technical publishing system:
```bash
# Render a document
quarto render document.qmd
# Convert to PDF
quarto render document.qmd --to pdf
# Create a new project
quarto create-project myproject --type book
```
### JQ/YQ
Process JSON and YAML files:
```bash
# Format JSON
jq '.' data.json
# Extract values from JSON
jq '.field' data.json
# Process YAML files
yq '.field' data.yml
```
## Document Conversion Workflows
### Markdown to Professional PDF
Convert markdown documents to professionally formatted PDFs:
```bash
# For resumes (ATS optimized)
pandoc resume.md -o resume.pdf --template=altacv
# For project plans and proposals
pandoc document.md -o document.pdf --template=eisvogel
```
### Joplin Notes to PDF
Export your Joplin notes with full formatting preserved:
```bash
# Export individual notes
pandoc joplin_note.md -o note.pdf --css=styles.css
# For complex formatting use a custom template
pandoc joplin_note.md -o note.pdf --template=custom.latex
```
### Creating Books with mdBook
Organize content into structured books:
```bash
# Initialize a new book
mdbook init my-book
# Build the book in output directory
mdbook build
# Preview with live reload
mdbook serve --open
```
## Development Workflows
### Local Development
1. Mount your source files to `/home/tsysdevstack/docs` in the container
2. Place output files in `/home/tsysdevstack/output` which is also mounted
3. Use the container interactively for development
4. Run `mdbook serve` for live preview during content development
### CI/CD Pipeline
1. Build the container with your content inside
2. Run conversion tools to generate all document formats
3. Extract output files from the container
4. Deploy or package as needed
### Version Control
- Keep source files (markdown, typst, etc.) in version control
- Exclude generated files (PDFs, HTML, etc.) from version control
- Use docker-compose for consistent development environments across teams

60
toolbox-docs/examples/README.md
View File

@@ -1,60 +0,0 @@
# Examples Directory
This directory contains example documents and workflow scripts to help you get started with the TSYS Dev Stack Docs Toolbox.
## Table of Contents
- [Markdown Examples](#markdown-examples)
- [Book Examples](#book-examples)
- [Presentation Examples](#presentation-examples)
- [Workflow Scripts](#workflow-scripts)
## Markdown Examples
### Resume Example
- `resume-example.md` - A sample resume in markdown format optimized for ATS systems
- `resume-example.pdf` - The generated PDF version using pandoc
### Technical Documentation
- `technical-doc.md` - A sample technical document with code blocks and diagrams
- `technical-doc.pdf` - The generated PDF with proper formatting
- `technical-doc.html` - The generated HTML version
### Joplin Notes Conversion
- `joplin-note-example.md` - Sample Joplin note with formatting
- `joplin-note-example.pdf` - Converted PDF preserving Joplin formatting
## Book Examples
### Simple Book
- `simple-book/` - A complete mdBook project with:
- `book.toml` - Configuration file
- `src/SUMMARY.md` - Table of contents
- `src/chapter_1.md` - First chapter
- `src/chapter_2.md` - Second chapter
### Technical Book
- `technical-book/` - A more complex mdBook project with:
- Custom CSS styling
- Code examples with syntax highlighting
- Diagrams and images
## Presentation Examples
### Marp Slides
- `marp-slides-example.md` - Slides created with Marp syntax
- `marp-slides-example.pdf` - Exported PDF slides
### Quarto Presentation
- `quarto-slides-example.qmd` - Presentation in Quarto format
- `quarto-slides-example.html` - Generated reveal.js presentation
## Workflow Scripts
### Document Generation Workflow
- `generate-resume.sh` - Complete workflow to convert markdown resume to PDF
- `generate-docs.sh` - Workflow to convert multiple markdown documents to various formats
- `generate-book.sh` - Workflow to build and package an entire mdBook project
### Batch Processing
- `batch-convert.py` - Python script to batch convert multiple documents
- `convert-to-all-formats.sh` - Script to generate all format variants of a document

33
toolbox-docs/examples/generate-resume.sh
View File

@@ -1,33 +0,0 @@
#!/usr/bin/env bash
# Workflow script to convert markdown resume to PDF using pandoc
set -e
INPUT_FILE="resume-example.md"
OUTPUT_FILE="resume-example.pdf"
TEMPLATE="altacv"
echo "Converting resume to PDF..."
# Check if input file exists
if [ ! -f "$INPUT_FILE" ]; then
echo "Error: Input file '$INPUT_FILE' does not exist."
exit 1
fi
# Convert using pandoc with altacv template for ATS-optimized resume
pandoc "$INPUT_FILE" \
-o "$OUTPUT_FILE" \
--template="$TEMPLATE" \
--pdf-engine=xelatex \
--variable "geometry:margin=0.5in" \
--variable "colorlinks:true" \
--variable "linkcolor:blue" \
--variable "urlcolor:blue"
if [ $? -eq 0 ]; then
echo "Resume successfully converted to '$OUTPUT_FILE'"
else
echo "Error: Failed to convert resume"
exit 1
fi

47
toolbox-docs/examples/resume-example.md
View File

@@ -1,47 +0,0 @@
# Example Resume in Markdown
---
title: "John Doe"
author: []
date: []
output:
pdf_document:
template: altacv
pandoc_args: ["--top-level-division=section"]
---
# Personal Info
**Address:** 123 Main St, City, State
**Phone:** (555) 123-4567
**Email:** john.doe@example.com
**LinkedIn:** [johndoe](https://linkedin.com/in/johndoe)
# Experience
## Senior Software Engineer
**Tech Company** | Jan 2022 - Present
- Led development of microservices architecture that improved system scalability by 40%
- Mentored junior developers and conducted technical interviews
- Implemented CI/CD pipelines reducing deployment time by 60%
## Software Engineer
**Previous Company** | Jun 2019 - Dec 2021
- Developed and maintained RESTful APIs serving 10K+ daily active users
- Collaborated with cross-functional teams to deliver product features
- Optimized database queries resulting in 25% improvement in response times
# Education
## Master of Science in Computer Science
**University Name** | 2017 - 2019
## Bachelor of Science in Software Engineering
**University Name** | 2013 - 2017
# Skills
- **Languages:** JavaScript, Python, Go, Rust, Java
- **Frameworks:** React, Node.js, Django, Spring Boot
- **Technologies:** Docker, Kubernetes, AWS, PostgreSQL, Redis
- **Tools:** Git, Jenkins, Jira, Confluence

124
toolbox-docs/examples/technical-doc.md
View File

@@ -1,124 +0,0 @@
# Technical Documentation Example
## Introduction
This is a sample technical document to demonstrate the capabilities of the TSYS Dev Stack Docs Toolbox. This document includes various elements that are commonly found in technical documentation.
## Code Examples
Here's a Python example with syntax highlighting:
```python
def fibonacci(n):
"""
Generate the first n numbers in the Fibonacci sequence.
Args:
n (int): Number of Fibonacci numbers to generate
Returns:
list: List containing the first n Fibonacci numbers
"""
if n <= 0:
return []
elif n == 1:
return [0]
elif n == 2:
return [0, 1]
fib_sequence = [0, 1]
for i in range(2, n):
next_num = fib_sequence[i-1] + fib_sequence[i-2]
fib_sequence.append(next_num)
return fib_sequence
# Example usage
print(fibonacci(10)) # Output: [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
```
And here's a JavaScript example:
```javascript
class TodoList {
constructor() {
this.tasks = [];
}
addTask(task) {
this.tasks.push({
id: Date.now(),
text: task,
completed: false
});
}
completeTask(id) {
const task = this.tasks.find(t => t.id === id);
if (task) {
task.completed = true;
}
}
}
```
## Configuration Examples
Here's a sample configuration in YAML:
```yaml
server:
port: 8080
host: "0.0.0.0"
timeout: 30s
database:
host: "localhost"
port: 5432
name: "myapp"
ssl: true
logging:
level: "info"
format: "json"
output: "stdout"
```
## Diagrams
The following diagram would be generated using Kroki or similar tools:
```
graph TD
A[Client] --> B[Load Balancer]
B --> C[Web Server 1]
B --> D[Web Server 2]
B --> E[Web Server 3]
C --> F[Database]
D --> F
E --> F
```
## Tables
| Feature | Status | Priority |
|--------|--------|----------|
| User Authentication | Complete | High |
| Data Export | In Progress | High |
| Reporting | Planned | Medium |
| Dashboard | Complete | High |
## Mathematical Notation
The quadratic formula: $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$
Maxwell's equations:
$$\nabla \cdot \vec{E} = \frac{\rho}{\varepsilon_0}$$
$$\nabla \cdot \vec{B} = 0$$
$$\nabla \times \vec{E} = -\frac{\partial B}{\partial t}$$
$$\nabla \times \vec{B} = \mu_0\left(\vec{J} + \varepsilon_0\frac{\partial E}{\partial t}\right)$$
## Conclusion
This document demonstrates various features available in the documentation toolbox. You can convert this to PDF, Word, or HTML formats using Pandoc and other tools.

103
toolbox-docs/run.sh
View File

@@ -1,103 +0,0 @@
#!/usr/bin/env bash
# Script to run the tsysdevstack-toolboxes-docs container
set -e
# Default values
CONTAINER_NAME="tsysdevstack-toolboxes-docs"
IMAGE_NAME="tsysdevstack/toolbox-docs:latest"
WORKDIR="/home/tsysdevstack/docs"
# Function to display usage
usage() {
echo "Usage: $0 [OPTIONS]"
echo "Options:"
echo " -i, --interactive Run container interactively (default)"
echo " -b, --build Build the image before running"
echo " -d, --detached Run container in detached mode"
echo " -h, --help Show this help message"
echo ""
echo "Examples:"
echo " $0 # Run interactively (default)"
echo " $0 -d # Run in detached mode"
echo " $0 -b # Build image and run"
echo " $0 -b -d # Build image and run in detached mode"
}
# Parse command line arguments
INTERACTIVE=true
DETACHED=false
BUILD=false
while [[ $# -gt 0 ]]; do
case $1 in
-i|--interactive)
INTERACTIVE=true
shift
;;
-d|--detached)
DETACHED=true
INTERACTIVE=false
shift
;;
-b|--build)
BUILD=true
shift
;;
-h|--help)
usage
exit 0
;;
*)
echo "Unknown option: $1"
usage
exit 1
;;
esac
done
# If both interactive and detached are false, default to interactive
if [ "$INTERACTIVE" = true ] && [ "$DETACHED" = false ]; then
# Default behavior remains interactive
:
fi
# Build the image if requested
if [ "$BUILD" = true ]; then
echo "Building the Docker image..."
docker build -t "$IMAGE_NAME" .
fi
# Prepare docker run command
DOCKER_RUN_CMD="docker run --rm"
# Add user mapping to match host user
if [ -n "${UID:-}" ] && [ -n "${GID:-}" ]; then
DOCKER_RUN_CMD="$DOCKER_RUN_CMD --user $UID:$GID"
else
# Fallback to default user ID
DOCKER_RUN_CMD="$DOCKER_RUN_CMD --user 1000:1000"
fi
# Add volume mounts
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
DOCKER_RUN_CMD="$DOCKER_RUN_CMD -v $SCRIPT_DIR/docs:$WORKDIR"
DOCKER_RUN_CMD="$DOCKER_RUN_CMD -v $SCRIPT_DIR/output:/home/tsysdevstack/output"
# Add container name
DOCKER_RUN_CMD="$DOCKER_RUN_CMD --name $CONTAINER_NAME"
# Add detached mode flag if requested
if [ "$DETACHED" = true ]; then
DOCKER_RUN_CMD="$DOCKER_RUN_CMD -d"
else
# Add interactive and TTY flags for interactive mode
DOCKER_RUN_CMD="$DOCKER_RUN_CMD -it"
fi
# Add image name
DOCKER_RUN_CMD="$DOCKER_RUN_CMD $IMAGE_NAME"
# Run the container
echo "Running: $DOCKER_RUN_CMD"
eval "$DOCKER_RUN_CMD"

122
toolbox-docs/test.sh
View File

@@ -1,122 +0,0 @@
#!/usr/bin/env bash
# Script to test the tsysdevstack-toolboxes-docs container
set -e
# Default values
IMAGE_NAME="tsysdevstack/toolbox-docs:latest"
CONTAINER_NAME="tsysdevstack-toolboxes-docs-test"
WORKDIR="/home/tsysdevstack/docs"
echo "Starting tests for tsysdevstack-toolboxes-docs container..."
# Function to run a command in the container and check the exit code
run_test() {
local test_name="$1"
local command="$2"
local expected_result="${3:-0}" # Default expected result is 0 (success)
echo "Running test: $test_name"
echo "Command: $command"
# Run the command in the container
if docker run --rm --name "${CONTAINER_NAME}-$(date +%s%N)" "$IMAGE_NAME" bash -c "$command"; then
if [ "$expected_result" -eq 0 ]; then
echo "✓ PASS: $test_name"
else
echo "✗ FAIL: $test_name - Expected failure but command succeeded"
return 1
fi
else
if [ "$expected_result" -ne 0 ]; then
echo "✓ PASS: $test_name - Command failed as expected"
else
echo "✗ FAIL: $test_name - Command failed unexpectedly"
return 1
fi
fi
echo ""
}
# Test 1: Check if user is tsysdevstack
run_test "User verification" "whoami | grep tsysdevstack"
# Test 2: Check if required tools are installed
run_test "Pandoc installation" "pandoc --version"
run_test "MdBook installation" "mdbook --version"
run_test "Typst installation" "typst --version"
run_test "Marp CLI installation" "marp --version"
run_test "Quarto installation" "quarto --version"
run_test "YQ installation" "yq --version"
run_test "JQ installation" "jq --version"
run_test "Vale installation" "vale --version"
run_test "BibTool installation" "bibtool -h"
run_test "Wkhtmltopdf installation" "wkhtmltopdf --version"
run_test "Joplin installation" "npm list -g joplin || echo 'joplin not found via npm'"
# Test 3: Check if Python is available via mise
run_test "Python via mise" "mise exec -- python --version"
# Test 4: Check if Node.js is available via mise
run_test "Node.js via mise" "mise exec -- node --version"
# Test 5: Check if Rust is available via mise
run_test "Rust via mise" "mise exec -- rustc --version"
# Test 6: Check if Ruby is available via mise
run_test "Ruby via mise" "mise exec -- ruby --version"
# Test 7: Check if TeXLive is properly installed
run_test "TeXLive installation" "pdflatex --version"
# Test 8: Check if Git is available
run_test "Git installation" "git --version"
# Test 9: Check if shells are available
run_test "Fish shell installation" "fish --version"
run_test "Zsh installation" "zsh --version"
run_test "Bash installation" "bash --version"
# Test 10: Check if Mise is working properly
run_test "Mise activation" "source ~/.bashrc && mise --version"
# Test 11: Test basic functionality - convert markdown to PDF with Pandoc
echo "Running advanced test: Pandoc markdown to PDF conversion"
cat << 'EOF' > /tmp/test.md
% Test Document
% Test Author
# Introduction
This is a test document to verify that Pandoc is working correctly.
## Features
- Pandoc conversion
- Markdown formatting
- PDF generation
### Code Block Example
```python
def hello():
print("Hello, World!")
```
EOF
# Run a simple conversion test inside the container
if docker run --rm -v /tmp:/tmp -w /tmp "$IMAGE_NAME" bash -c "pandoc test.md -o test.pdf"; then
echo "✓ PASS: Pandoc conversion test"
# Clean up the generated file
rm -f /tmp/test.pdf
else
echo "✗ FAIL: Pandoc conversion test"
exit 1
fi
echo ""
# Test 12: Check if the working directory exists
run_test "Working directory exists" "test -d $WORKDIR"
echo "All tests completed successfully!"