Quillmark CLI

Command-line interface for the Quillmark Markdown rendering system.

Maintained by TTQ.

Overview

quillmark-cli is a standalone executable that renders Markdown files with YAML frontmatter into PDF, SVG, and other formats using Quillmark templates.

Installation

From crates.io (Recommended)

cargo install quillmark-cli

The binary will be installed to ~/.cargo/bin/quillmark (ensure ~/.cargo/bin is in your PATH).

From Git Repository

# Install latest from main branch
cargo install --git https://github.com/nibsbin/quillmark quillmark-cli

# Install from specific branch or tag
cargo install --git https://github.com/nibsbin/quillmark --branch main quillmark-cli

From Local Source

# From workspace root
cargo install --path bindings/quillmark-cli

# Or build without installing
cargo build --release -p quillmark-cli
# Binary will be at: target/release/quillmark

Quick Start

Render a markdown file using a quill template:

quillmark render document.md --quill path/to/quill

The output will be saved as document.pdf by default.

Usage

Basic Rendering

# Render to PDF (default format)
quillmark render memo.md --quill ./quills/usaf_memo

# Specify output file
quillmark render memo.md --quill ./quills/usaf_memo -o output/final.pdf

# Render to different format
quillmark render memo.md --quill ./quills/usaf_memo --format svg

Using QUILL Field in Frontmatter

If your markdown file has a QUILL field in the frontmatter, you can omit the --quill flag:

---
QUILL: usaf_memo
title: My Memo
---

Content here...

quillmark render memo.md

Advanced Options

# Output to stdout (useful for piping)
quillmark render memo.md --quill ./quills/usaf_memo --stdout > output.pdf

# Verbose output
quillmark render memo.md --quill ./quills/usaf_memo --verbose

# Quiet mode (suppress all non-error output)
quillmark render memo.md --quill ./quills/usaf_memo --quiet

Command Reference

quillmark render

Render a markdown file to the specified output format.

Usage:

quillmark render [OPTIONS] <MARKDOWN_FILE>

Arguments:

• <MARKDOWN_FILE> - Path to markdown file with YAML frontmatter

Options:

• -q, --quill <PATH> - Path to quill directory (overrides QUILL frontmatter field)
• -o, --output <FILE> - Output file path (default: derived from input filename)
• -f, --format <FORMAT> - Output format: pdf, svg, txt (default: pdf)
• --stdout - Write output to stdout instead of file
• -v, --verbose - Show detailed processing information
• --quiet - Suppress all non-error output

Examples

Example: Render USAF Memo

quillmark render \
  crates/fixtures/resources/quills/usaf_memo/0.1.0/example.md \
  --quill crates/fixtures/resources/quills/usaf_memo/0.1.0 \
  -o usaf_memo_output.pdf

Example: Generate SVG

quillmark render document.md \
  --quill ./quills/my_template \
  --format svg \
  -o output.svg

Example: Pipeline Usage

# Render and immediately view with a PDF viewer
quillmark render memo.md --quill ./quills/usaf_memo --stdout | evince -

# Render to stdout and pipe to another tool
quillmark render memo.md --quill ./quills/usaf_memo --stdout > final.pdf

Error Handling

The CLI provides clear error messages for common issues:

• Missing markdown file: Markdown file not found: path/to/file.md
• Missing quill: Quill directory not found: path/to/quill
• No QUILL field: No QUILL field in frontmatter and --quill not specified
• Parse errors: Line numbers and context for YAML or markdown issues
• Template errors: Compilation diagnostics from the rendering backend

Exit Codes

• 0 - Success
• 1 - Error occurred (see stderr for details)

Development

Building

cargo build

Running Tests

cargo test

Running Locally

cargo run -- render example.md --quill path/to/quill

Design Documentation

For architectural details and design decisions, see:

• CLI Design Document
• Implementation Plan

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.