206 lines
4.8 KiB
Markdown
206 lines
4.8 KiB
Markdown
# 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. |