pipx install doc-engine-cli

Overview

doc-engine-cli is a developer-first CLI tool that converts Markdown files into professionally styled PDF documents using Typst as its rendering backend. It is designed for teams and individual developers who need high-quality documentation artifacts without the complexity of LaTeX or manual typesetting.

The tool auto-detects your README.md, extracts metadata from Git, and produces an IEEE-inspired technical document — complete with cover page, table of contents, and premium typography — in a single command.

That's it. Zero configuration required.

Features

🎓 Academic Features (v0.1.2+)

doc-engine-cli ships with a premium scientific layout (using Linux Libertine and Inter font-families) and Zero-Config Bibliography handling.

To add an IEEE-styled bibliography to your PDF:

1. Create a refs.bib, references.bib, or bibliography.bib file in your repository.
2. In your README.md, cite using standard syntax: [@citation-key].

When you run doc-engine build, the CLI will automatically detect your .bib file, securely bind it to the sandbox, and inject a formatted References page at the end of the document.

Quick Start

Installation

pipx install doc-engine-cli

(If you don't have pipx, you can install it via pip install pipx)

Generate Your First PDF

Navigate to any project directory containing a README.md and run:

The tool will:

1. Auto-detect README.md in the current directory
2. Extract the document title from the first # heading
3. Read your Git user.name for the author field
4. Generate a README_doc.pdf with cover page, ToC, and formatted content

Explicit Options

doc-engine build path/to/file.md -o output.pdf -t "Custom Title" -a "Author Name"

Usage

CLI Reference

Usage: doc-engine build [OPTIONS] [INPUT_FILE]

  Convert a Markdown file into a professional PDF document.

Arguments:
  INPUT_FILE    Path to Markdown file (default: auto-detect README.md)

Options:
  -o, --output  TEXT    Output PDF file path (default: <input>_doc.pdf)
  -t, --title   TEXT    Document title override (default: first # heading)
  -a, --author  TEXT    Author name override (default: git user.name)
  --open                Open PDF after generation
  --version             Show version and exit
  --help                Show this message and exit

Examples

Basic — zero-config mode:

cd my-project
doc-engine build
# → Generates README_doc.pdf

Specify input and output:

doc-engine build CONTRIBUTING.md -o contributing_guide.pdf

Override metadata:

doc-engine build -t "API Reference v2.0" -a "Engineering Team"

Generate and open immediately:

Use as Python module:

python -m doc_engine build README.md

Architecture

                    ┌─────────────┐
                    │  README.md  │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │   CLI Layer  │  click + rich
                    │  (cli.py)    │  arg parsing, git detection
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │                         │
       ┌──────▼──────┐          ┌───────▼──────┐
       │  Converter   │          │   Compiler   │
       │(converter.py)│          │(compiler.py) │
       │              │          │              │
       │ Markdown AST │          │  Typst → PDF │
       │  → Typst     │          │  via typst-py│
       └──────┬──────┘          └───────┬──────┘
              │                         │
              │    ┌──────────────┐     │
              └────► report.typ   ◄─────┘
                   │  (template)  │
                   └──────┬──────┘
                          │
                   ┌──────▼──────┐
                   │  output.pdf  │
                   └─────────────┘

Pipeline

How It Works

Markdown → Typst Conversion

The converter module parses Markdown using mistune and generates equivalent Typst markup:

Special characters (#, $, @, *, _, etc.) are automatically escaped to prevent Typst interpretation.

PDF Template

The included report.typ template provides:

• Cover page with title, author, and date
• Table of contents with depth-3 navigation
• Running headers with document title and author
• Page footer with page numbers and engine attribution
• Code blocks with rounded corners and subtle borders
• Heading hierarchy with accent-colored H2 sections

Project Structure

doc-engine-cli/
├── doc_engine/
│   ├── __init__.py          # Package version
│   ├── __main__.py          # python -m doc_engine entrypoint
│   ├── cli.py               # Click-based CLI + Git detection
│   ├── converter.py         # Markdown → Typst transpiler
│   ├── compiler.py          # Typst → PDF compilation engine
│   └── templates/
│       └── report.typ       # Professional Typst report template
├── tests/
│   ├── __init__.py
│   └── test_converter.py    # Unit tests for converter module
├── pyproject.toml            # Package configuration + dependencies
├── LICENSE                   # MIT License
├── .gitignore
└── README.md

Dependencies

All dependencies are pure Python — no external binaries (Pandoc, LaTeX, etc.) are required.

Development

Setup

git clone https://github.com/leonardosalasd/doc-engine-cli.git
cd doc-engine-cli
pip install -e ".[dev]"

Run Tests

python -m pytest tests/ -v

Project Commands

# Generate PDF from this project's README
python -m doc_engine build

# Run with verbose error output
python -m doc_engine build README.md -o docs_output.pdf

Supported Markdown Elements

• Headings (H1–H6)
• Bold, italic, strikethrough
• Inline code and fenced code blocks (with language hints)
• Links
• Ordered and unordered lists
• Nested lists
• Blockquotes
• Tables
• Horizontal rules
• Line breaks (<br>)
• Images (rendered as alt-text; remote images not embedded)
• Footnotes
• Math blocks

Roadmap

• Custom template injection via --template flag
• Multi-file documentation merge
• GitHub Actions integration for CI/CD pipelines
• Dark-mode PDF theme variant
• Image downloading and embedding for remote URLs
• YAML front-matter support for metadata override
• PDF/A compliance for archival

Contributing

Contributions are welcome. Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Write tests for new functionality
4. Ensure all tests pass (python -m pytest tests/ -v)
5. Submit a pull request

License

This project is licensed under the MIT License.