# Cheatsheet

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

## 📋 Tool Commands

### Pandoc

Most versatile conversions:
```bash
# 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:
```bash
# Build a book
mdbook build

# Serve book locally
mdbook serve

# Watch for changes and rebuild
mdbook watch
```

### Typst

Modern typesetting:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
./output/test.sh
```

### Validate specific tools:
```bash
# 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:
```bash
# From markdown to styled PDF
pandoc examples/resume-sample.md -o output/resume.pdf --template=examples/resume-style.tex --pdf-engine=xelatex
```

### Project Documentation:
```bash
# Create a complete documentation site
cd examples/mdbook-sample
mdbook build -d ../../output/project-docs
```

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

### Presentation Creation:
```bash
# 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](USAGE.md) for detailed workflows
- Run tests with `./output/test.sh` to verify your setup