TSYSDevStack/Toolbox/docs/documentation/USAGE.md

Usage Guide

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

🚀 Quick Start

Run the Container

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

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

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

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

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

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

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

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

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

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

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

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

# 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 for solutions to common problems.