TSYSDevStack/toolbox-docs/documentation/USAGE.md

# 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