texforge 0.5.0

Self-contained LaTeX to PDF compiler CLI
texforge-0.5.0 is not a library. 
 ███████████          █████ █████ ███████████                                     
░█░░░███░░░█         ░░███ ░░███ ░░███░░░░░░█                                     
░   ░███  ░   ██████  ░░███ ███   ░███   █ ░   ██████  ████████   ███████  ██████ 
    ░███     ███░░███  ░░█████    ░███████    ███░░███░░███░░███ ███░░███ ███░░███
    ░███    ░███████    ███░███   ░███░░░█   ░███ ░███ ░███ ░░░ ░███ ░███░███████ 
    ░███    ░███░░░    ███ ░░███  ░███  ░    ░███ ░███ ░███     ░███ ░███░███░░░  
    █████   ░░██████  █████ █████ █████      ░░██████  █████    ░░███████░░██████ 
   ░░░░░     ░░░░░░  ░░░░░ ░░░░░ ░░░░░        ░░░░░░  ░░░░░      ░░░░░███ ░░░░░░  
                                                                 ███ ░███         
                                                                ░░██████          
                                                                 ░░░░░░

CI Release Crates.io License: MIT

Self-contained LaTeX to PDF compiler — one curl, zero friction. No TeX Live, no MiKTeX, no Perl, no Node. A single install sets up everything you need.

Installation

Quick install (recommended)

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/JheisonMB/texforge/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/JheisonMB/texforge/main/install.ps1 | iex

This downloads and installs texforge. No Rust toolchain required. Tectonic (the LaTeX engine) is installed automatically on first build.

You can customize the install:

# Pin a specific version
VERSION=0.1.0 curl -fsSL https://raw.githubusercontent.com/JheisonMB/texforge/main/install.sh | sh

# Install to a custom directory
INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/JheisonMB/texforge/main/install.sh | sh

# Pin a specific version (PowerShell)
$env:VERSION="0.1.0"; irm https://raw.githubusercontent.com/JheisonMB/texforge/main/install.ps1 | iex

Via cargo

cargo install texforge

Tectonic (the LaTeX engine) is installed automatically on first build. No extra steps needed.

Available on crates.io.

From source

git clone https://github.com/JheisonMB/texforge.git
cd texforge
cargo build --release
# Binary at target/release/texforge

GitHub Releases

Check the Releases page for precompiled binaries (Linux x86_64, macOS x86_64/ARM64, Windows x86_64).

Uninstall

rm -f ~/.local/bin/texforge  # texforge binary
rm -rf ~/.texforge/           # tectonic engine + cached templates

Skill

An texforge Skill is available for AI-assisted LaTeX workflows with texforge:

npx skills add https://github.com/jheisonmb/skills --skill texforge

Quick Start

# Interactive wizard — new project or migrate existing
texforge init

# Or directly:
texforge new mi-tesis
texforge build

Workflow

sequenceDiagram
    actor User
    participant CLI as texforge
    participant Tectonic

    User->>CLI: texforge new my-doc
    CLI-->>User: project scaffolded

    alt Existing LaTeX project
        User->>CLI: texforge init
        CLI-->>User: project.toml generated
    end

    User->>CLI: texforge check
    CLI-->>User: errors with file:line + suggestion

    User->>CLI: texforge fmt
    CLI-->>User: .tex files formatted in place

    User->>CLI: texforge build
    Note over CLI: render embedded diagrams to PNG
    CLI->>Tectonic: compile build/main.tex
    Note over CLI,Tectonic: auto-installs tectonic on first run
    Tectonic-->>User: build/main.pdf

texforge init

Interactive wizard. Auto-detects the context:

  • If a .tex file with \documentclass is found in the current directory — migrates the existing project (asks for title and author, generates project.toml)
  • Otherwise — guides creation of a new project (asks for name and template)
# Existing LaTeX project
cd mi-tesis-existente/
texforge init

# Empty directory
mkdir mi-nuevo-doc && cd mi-nuevo-doc
texforge init
Command Description
texforge new <name> Create new project from template
texforge new <name> -t <template> Create with specific template
texforge init Interactive wizard — new project or migrate existing
texforge build Compile to PDF
texforge build --watch Watch for changes and rebuild automatically
texforge clean Remove build artifacts
texforge fmt Format .tex files
texforge fmt --check Check formatting without modifying
texforge check Lint without compiling
texforge template list List installed templates
texforge template list --all List installed + available in registry
texforge template add <name> Download template from registry
texforge template remove <name> Remove installed template
texforge template validate <name> Verify template compatibility

Templates

Templates are managed through the texforge-templates registry. The general template is embedded in the binary and works offline. Run texforge template list --all to see all available templates.

Diagrams

texforge build intercepts embedded diagram environments before compilation. Originals are never modified — diagrams are rendered in build/ copies.

Mermaid

% Default: width=\linewidth, pos=H, no caption
\begin{mermaid}
flowchart LR
  A[Input] --> B[Process] --> C[Output]
\end{mermaid}

% With options
\begin{mermaid}[width=0.6\linewidth, caption=System flow, pos=t]
flowchart TD
  X --> Y --> Z
\end{mermaid}

Graphviz / DOT

\begin{graphviz}[caption=Pipeline]
digraph G {
  rankdir=LR
  A -> B -> C
  B -> D
}
\end{graphviz}

Both rendered to PNG via pure Rust — no browser, no Node.js, no dot binary required.

Option Default Description
width \linewidth Image width
pos H Figure placement (H, t, b, h, p)
caption (none) Figure caption

Watch Mode

texforge build --watch watches for .tex file changes and rebuilds automatically:

texforge build --watch            # rebuild after 2s of inactivity (default)
texforge build --watch --delay 5  # custom delay in seconds

The terminal shows a live session timer, build count, and the result of the last build. Press Ctrl+C to stop.

Linter

texforge check runs static analysis without compiling:

  • \input{file} — verifies file exists
  • \includegraphics{img} — verifies image exists
  • \cite{key} — verifies key exists in .bib
  • \ref{label} / \label{label} — verifies cross-reference consistency
  • \begin{env} / \end{env} — detects unclosed environments
ERROR [main.tex:47]
  \includegraphics{missing.png} — file not found

ERROR [main.tex:12]
  \cite{smith2020} — key not found in .bib

ERROR [main.tex:23]
  \begin{figure} never closed
  suggestion: Add \end{figure}

Formatter

texforge fmt applies opinionated formatting inspired by rustfmt:

  • Consistent indentation (2 spaces) inside environments
  • Collapsed multiple blank lines
  • Aligned \begin{}/\end{} blocks

One canonical output regardless of input style. Git diffs stay clean.

texforge fmt           # format in place
texforge fmt --check   # check without modifying (CI-friendly)

Runtime Directory

~/.texforge/
  bin/
    tectonic            # LaTeX engine (auto-installed on first build)
  templates/
    general/            # Cached templates
    apa-general/
    ...

Platform Support

Platform Architecture Status
Linux x86_64 yes
macOS x86_64 yes
macOS ARM64 (Apple Silicon) yes
Windows x86_64 yes

Tech Stack

Concern Crate
CLI parsing clap (derive)
Error handling anyhow
Serialization serde + toml
HTTP client reqwest (blocking)
Archive extraction flate2 + tar
File traversal walkdir
LaTeX engine tectonic (external binary)
Mermaid renderer mermaid-rs-renderer
Graphviz renderer layout-rs
SVG → PNG resvg

License

MIT