```
███████████ █████ █████ ███████████
░█░░░███░░░█ ░░███ ░░███ ░░███░░░░░░█
░ ░███ ░ ██████ ░░███ ███ ░███ █ ░ ██████ ████████ ███████ ██████
░███ ███░░███ ░░█████ ░███████ ███░░███░░███░░███ ███░░███ ███░░███
░███ ░███████ ███░███ ░███░░░█ ░███ ░███ ░███ ░░░ ░███ ░███░███████
░███ ░███░░░ ███ ░░███ ░███ ░ ░███ ░███ ░███ ░███ ░███░███░░░
█████ ░░██████ █████ █████ █████ ░░██████ █████ ░░███████░░██████
░░░░░ ░░░░░░ ░░░░░ ░░░░░ ░░░░░ ░░░░░░ ░░░░░ ░░░░░███ ░░░░░░
███ ░███
░░██████
░░░░░░
```
[](https://github.com/JheisonMB/texforge/actions/workflows/ci.yml)
[](https://github.com/JheisonMB/texforge/actions/workflows/release.yml)
[](https://crates.io/crates/texforge)
[](LICENSE)
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:**
```bash
**Windows (PowerShell):**
```powershell
This downloads and installs `texforge`. No Rust toolchain required. Tectonic (the LaTeX engine) is installed automatically on first build.
You can customize the install:
```bash
# Pin a specific version
# Install to a custom directory
INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/JheisonMB/texforge/main/install.sh | sh
```
```powershell
# Pin a specific version (PowerShell)
### Via cargo
```bash
cargo install texforge
```
Tectonic (the LaTeX engine) is installed automatically on first build. No extra steps needed.
Available on [crates.io](https://crates.io/crates/texforge).
### From source
```bash
git clone https://github.com/JheisonMB/texforge.git
cd texforge
cargo build --release
# Binary at target/release/texforge
```
### GitHub Releases
Check the [Releases](https://github.com/JheisonMB/texforge/releases) page for precompiled binaries (Linux x86_64, macOS x86_64/ARM64, Windows x86_64).
### Uninstall
```bash
rm -f ~/.local/bin/texforge # texforge binary
rm -rf ~/.texforge/ # tectonic engine + cached templates
```
## Skill
An [texforge Skill](https://skills.sh/jheisonmb/skills/texforge) is available for AI-assisted LaTeX workflows with texforge:
```bash
npx skills add https://github.com/jheisonmb/skills --skill texforge
```
## Quick Start
```bash
# Interactive wizard — new project or migrate existing
texforge init
# Or directly:
texforge new mi-tesis
texforge build
```
## Workflow
```mermaid
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)
```bash
# Existing LaTeX project
cd mi-tesis-existente/
texforge init
# Empty directory
mkdir mi-nuevo-doc && cd mi-nuevo-doc
texforge init
```
---
| `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](https://github.com/JheisonMB/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
```latex
% 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
```latex
\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.
| `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:
```bash
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.
```bash
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
| Linux | x86_64 | yes |
| macOS | x86_64 | yes |
| macOS | ARM64 (Apple Silicon) | yes |
| Windows | x86_64 | yes |
---
## Tech Stack
| 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