186 lines
4.1 KiB
Markdown
186 lines
4.1 KiB
Markdown
# 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 |