TSYSDevStack/Toolbox/docs/documentation/CHEATSHEET.md

Cheatsheet

A quick reference for common commands and workflows in the documentation toolchain.

📋 Tool Commands

Pandoc

Most versatile conversions:

# Convert markdown to PDF with LaTeX
pandoc input.md -o output.pdf --pdf-engine=xelatex

# Convert to HTML with custom CSS
pandoc input.md -o output.html --css styles.css --standalone

# Convert to Word document
pandoc input.md -o output.docx

# Use custom template
pandoc input.md -o output.pdf --template my-template.tex

MdBook

Create documentation books:

# Build a book
mdbook build

# Serve book locally
mdbook serve

# Watch for changes and rebuild
mdbook watch

Typst

Modern typesetting:

# Compile document
typst compile document.typ output.pdf

# Watch for changes
typst watch document.typ output.pdf

# Format document
typst format document.typ

Marp

Create presentations from markdown:

# Create PDF presentation
npx --package @marp-team/marp-cli marp presentation.md -o output.pdf

# Serve presentation live
npx --package @marp-team/marp-cli marp presentation.md --server

# Create HTML presentation
npx --package @marp-team/marp-cli marp presentation.md --html -o output.html

Quarto

Scientific publishing:

# Render document
quarto render document.qmd

# Render with specific format
quarto render document.qmd --to pdf

# Render to specific output
quarto render document.qmd -o output.html

🏗️ Build & Run

Building the container:

# Build with default settings
./output/build.sh

# Build for specific platform
./output/build.sh --platform linux/amd64

# Build with security scan
./output/build.sh --scan-security

Running the container:

# Interactive shell
docker run --rm -it tsysdevstack-toolboxes-docs

# Run specific command
docker run --rm -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs pandoc examples/input.md -o output.pdf

# Using docker-compose
docker-compose -f output/docker-compose.yml up

# Run with volumes mounted
docker run --rm -it \
  -v $(pwd)/docs:/home/tsysdevstack/docs \
  -v $(pwd)/templates:/home/tsysdevstack/templates \
  tsysdevstack-toolboxes-docs

🔧 Environment Setup

Language Runtimes via Mise:

# List available runtimes
mise ls

# Install a specific version
mise install python@3.11.5

# Use a specific version in current shell
mise exec python -- python script.py

# Set default version
mise use python@3.11.5

Useful File Locations:

• /home/tsysdevstack/docs - Working directory for documents
• /home/tsysdevstack/.local/bin - User-installed binaries
• /home/tsysdevstack/.config/mise - Mise configuration
• /home/tsysdevstack/examples - Example documents (when mounted)

🧪 Testing & Validation

Run all tests:

./output/test.sh

Validate specific tools:

# Check QA tools
docker run --rm -i hadolint/hadolint:latest < output/Dockerfile
docker run --rm -v "$(pwd)":/mnt koalaman/shellcheck:stable /mnt/output/build.sh

# Check tool versions
docker run --rm tsysdevstack-toolboxes-docs pandoc --version
docker run --rm tsysdevstack-toolboxes-docs mdbook --version

🛠️ Common Workflows

Resume Creation:

# From markdown to styled PDF
pandoc examples/resume-sample.md -o output/resume.pdf --template=examples/resume-style.tex --pdf-engine=xelatex

Project Documentation:

# Create a complete documentation site
cd examples/mdbook-sample
mdbook build -d ../../output/project-docs

Note Conversion:

# Convert Joplin note to PDF
pandoc examples/joplin-note-sample.md -o output/note.pdf --pdf-engine=xelatex

Presentation Creation:

# Create a presentation from markdown
npx --package @marp-team/marp-cli marp examples/sample-presentation.md -o output/presentation.pdf

🔍 Useful Tips

• Always use --rm flag to automatically remove containers after running
• Mount volumes with :rw for read-write access
• Use the --userns=keep-id flag to maintain file ownership
• Check the Usage Guide for detailed workflows
• Run tests with ./output/test.sh to verify your setup