# Usage Guide

This guide explains how to use the documentation toolchain container for various document creation workflows.

## 🚀 Quick Start

### Run the Container
```bash
# Interactive mode (recommended for development)
docker run --rm -it -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs

# Or use with docker-compose
docker-compose -f output/docker-compose.yml up
```

### Available Tools
Once inside the container, you have access to all the tools in the toolchain:

- `pandoc` - Universal document converter
- `mdbook` - Book generator from markdown
- `typst` - Modern typesetting system
- `marp` - Markdown presentation tool
- `quarto` - Scientific publishing system
- `vale` - Prose linter
- And many more...

## 📄 Document Workflows

### 1. Resume Generation

Creating a professional PDF resume from Markdown:

```bash
# Convert markdown to PDF using pandoc
pandoc examples/resume-sample.md -o output/resume.pdf --template=examples/resume-style.tex --pdf-engine=xelatex

# Or with custom styling
pandoc examples/resume-sample.md -o output/resume.pdf -H examples/resume-style.tex --pdf-engine=xelatex
```

### 2. Project Documentation

Generating comprehensive project documentation:

```bash
# Create HTML documentation from markdown
pandoc examples/project-plan.md -o output/project-plan.html --standalone

# Create PDF documentation
pandoc examples/project-plan.md -o output/project-plan.pdf --pdf-engine=xelatex

# Generate a full documentation site with mdbook
cd examples/mdbook-sample
mdbook build -d ../../output/mdbook-output
```

### 3. Academic Writing

Using Typst for academic documents:

```bash
# Compile a typst document
typst compile examples/sample-typst.typ output/thesis.pdf

# Watch for changes and recompile
typst watch examples/sample-typst.typ output/thesis.pdf
```

### 4. Presentations

Creating presentations from markdown:

```bash
# Using marp to create a presentation
npx --package @marp-team/marp-cli marp examples/sample-presentation.md -o output/presentation.pdf

# Serve presentation for live editing
npx --package @marp-team/marp-cli marp examples/sample-presentation.md --server
```

### 5. Joplin Notes Conversion

Converting Joplin notes to various formats:

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

# Convert to HTML with custom styling
pandoc examples/joplin-note-sample.md -o output/joplin-note.html --standalone --css styles/notes-style.css
```

### 6. Data-Driven Reports

Using Quarto for data-driven reports:

```bash
# Render a quarto document
quarto render examples/sample-report.qmd -o output/report.html

# Convert to PDF
quarto render examples/sample-report.qmd -o output/report.pdf
```

## 🔧 Advanced Usage

### Environment Variables

Set these environment variables to customize behavior:

- `PANDOC_DATA_DIR` - Directory for custom pandoc templates and filters
- `MARP_USER` - User settings for marp
- `QUARTO_PROJECT_DIR` - Project directory for quarto

### File Mounting

Mount volumes to share files between your host and the container:

```bash
# Share your documents directory
docker run --rm -it \
  -v $(pwd)/docs:/home/tsysdevstack/docs \
  -v $(pwd)/templates:/home/tsysdevstack/templates \
  tsysdevstack-toolboxes-docs
```

### Custom Templates

Place custom pandoc templates in `/home/tsysdevstack/.pandoc/templates/`:

```bash
# Use a custom template
pandoc input.md -o output.pdf --template custom-template

# Or specify template path directly
pandoc input.md -o output.pdf --template=/path/to/my-template.tex
```

## 🛠️ Tool-Specific Examples

### Pandoc

Convert between various formats:

```bash
# Markdown to LaTeX
pandoc input.md -o output.tex

# Markdown to Docx
pandoc input.md -o output.docx

# HTML to markdown
pandoc input.html -o output.md

# Custom styling with CSS
pandoc input.md -o output.html --css styles/custom.css --standalone
```

### Vale

Lint your documentation for style issues:

```bash
# Check a document
vale examples/project-plan.md

# Check with specific configuration
vale --config /path/to/.vale.ini examples/
```

### BibTeX Management

Use bibtool to manage bibliography files:

```bash
# Format and clean a bibliography
bibtool -s -d examples/sample-bibliography.bib > output/cleaned-bibliography.bib

# Extract entries from a larger bibliography
bibtool -x "author='Smith'" examples/large-bibliography.bib > output/smith-entries.bib
```

## 🧪 Testing Your Setup

Verify that all tools are working correctly:

```bash
# Test pandoc
pandoc --version

# Test mdbook
mdbook --version

# Test typst
typst --version

# Test quarto
quarto --version

# Test that all required tools are accessible
ls -la /home/tsysdevstack/.local/bin/
```

## 🚨 Troubleshooting

If you encounter issues, see our [Troubleshooting Guide](TROUBLESHOOTING.md) for solutions to common problems.