TSYSDevStack/toolbox-docs/documentation/USAGE.md

Usage Guide - TSYS Dev Stack Docs Toolbox

Table of Contents

• Overview
• Running the Container
• Available Tools
• Document Conversion 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

# 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

# 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

# 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:

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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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