GitHub - StructuredLabs/waldtex: Your Markdown files → publication-quality PDFs. Local-first, open-source.

Quick Start · Features · Installation · Usage Guide · Contributing · License · Get in Touch

What is WaldTeX?

WaldTeX is a free, open-source, local-first IDE for writing scientific documents. Think of it as Obsidian meets Overleaf — you get the linked-notes experience of Obsidian and the publication-quality output of Overleaf, but everything runs on your machine. No account. No cloud. No subscription.

You write in Markdown, not LaTeX. Your files are .md and .qmd (Quarto Markdown). You write prose in plain Markdown, math in $E = mc^2$ , citations with @einstein1905. When you save, Quarto compiles your Markdown into a beautifully typeset PDF — using LaTeX under the hood — or Word, HTML, slides, and more. One source, many outputs.

LaTeX is there when you need it. Drop into raw LaTeX blocks for complex equations, TikZ diagrams, or custom formatting. But you never have to write \begin{document} unless you want to.

Why WaldTeX?

	Overleaf	Obsidian	WaldTeX
Markdown editing	Limited	Full	Full
LaTeX / PDF output	Native	Via plugins	Via Quarto
Wiki links & backlinks	No	Yes	Yes
Graph view	No	Yes	Yes
Local-first / offline	No	Yes	Yes
Free & open source	Partially	No	Yes
Multi-format export	PDF only	Limited	PDF, Word, HTML, slides, EPUB
Bibliography manager	Basic	Via plugins	Built-in
Embedded terminal	No	No	Yes
Version history	Yes	Via plugin	Built-in (Git)

Quick Start

Three commands to get running:

# 1. Clone the repository
git clone https://github.com/StructuredLabs/waldtex.git
cd waldtex

# 2. Install dependencies
npm install

# 3. Start WaldTeX
npm start

WaldTeX opens in your browser at http://localhost:1618.

Prerequisites: You need Node.js (v18+), Quarto, and a TeX distribution installed. See Installation for detailed instructions per platform.

Features

Markdown-First Editor

Write in Markdown with full syntax highlighting, bracket matching, and code folding. The editor uses CodeMirror 6 — the same engine behind many modern code editors.

LaTeX math — inline $...$ and display $$...$$ with syntax highlighting and hover preview
YAML frontmatter — syntax-aware editing for Quarto document configuration
Citations — type @ and get autocomplete suggestions from your .bib file
Smart formatting — bold, italic, headings, lists, links, images via keyboard shortcuts
Multiple files — tabbed editing with unsaved-change indicators

Obsidian-Style Knowledge Management

Your research notes and your paper live in the same project. Link between them freely.

Wiki links — type [[ to link to any file in your project. Click to navigate. If the target doesn't exist, WaldTeX creates it.
Backlinks — a sidebar panel showing every note that links to the one you're reading. Discover connections you forgot about.
Graph view — a force-directed network visualization of all your notes and their connections. Click any node to open that file. Zoom, pan, and filter by tags.
Tags — add #methodology, #results, or #todo anywhere in your notes. Browse all tags from the tag index.
Quick switcher — press Cmd+O (or Ctrl+O) to fuzzy-search any file by name and jump to it instantly.

Live Preview

See your formatted output as you write.

HTML preview — fast, near-instant preview powered by quarto preview. Rendered math, formatted citations, figure layouts — all updating live as you save.
PDF preview — full typeset output via quarto render. The exact document you'd submit to a journal. Toggle between preview modes with one click.
Split pane — editor on the left, preview on the right. Resize the split however you like.

Multi-Format Output via Quarto

One source file, many output formats. Controlled entirely from your YAML frontmatter:

format:
  pdf:
    documentclass: article
    number-sections: true
  docx: default
  html: default

Supported formats:

Format	Engine	Use case
PDF	LaTeX (pdflatex / xelatex / lualatex)	Journal submissions, printed documents
Word (.docx)	Pandoc	Journals that require Word, collaborators who use Word
HTML	Pandoc	Personal website, blog post, online appendix
Reveal.js slides	Quarto	Conference presentations (HTML)
Beamer slides	LaTeX	Conference presentations (PDF)
EPUB	Pandoc	E-readers
arXiv bundle	Custom	`.tar.gz` with source + figures ready for arXiv upload

Project Templates

Start a new project from a built-in template:

Article — single-file journal paper with bibliography
Thesis / Book — multi-chapter document with frontmatter, chapters, and references
Slides — presentation with speaker notes (Reveal.js + Beamer)
CV / Resume — academic curriculum vitae
Letter — formal letter

Each template includes a _quarto.yml project configuration, a starter .qmd file, and a references.bib bibliography file.

Bibliography Manager

Manage your references without leaving the editor.

Visual browser — see all entries in your .bib file with title, author, year, and type
Search — filter by title, author, keyword, or BibTeX key
Add / edit — create new entries or edit existing ones via a form
Insert citations — click an entry or type @ to insert a @cite-key reference at your cursor position
CSL support — choose from thousands of citation styles (APA, IEEE, Nature, Chicago, etc.) via Quarto's CSL integration

Version History (Git)

Every project is a Git repository. Track changes without leaving WaldTeX.

Commit — stage changes and commit with a message from the sidebar
History — visual timeline of all commits
Diff viewer — side-by-side comparison of any two versions
It's just Git — push to GitHub, create branches, collaborate via PRs. WaldTeX wraps standard Git, so anything you do from the terminal works too.

Embedded Terminal

A real terminal inside WaldTeX — toggle it with Ctrl+`.

Full shell access — runs your system shell (bash, zsh, fish, etc.)
Claude Code ready — type claude in the terminal to get AI-assisted writing. Claude sees your .qmd and .bib files and can edit them directly. WaldTeX detects the changes, reloads the editor, and recompiles automatically.
Multiple tabs — run Claude Code in one tab, git in another, quarto commands in a third.
Project-aware — the terminal opens in your current project directory.

Dark Theme

A dark, minimal interface inspired by Obsidian. Light theme available via the settings toggle.

Installation

Prerequisites

WaldTeX requires three things installed on your system:

Prerequisite	What it does	Required?
Node.js >= 18	Runs the WaldTeX application	Yes
Quarto CLI	Compiles Markdown to PDF, Word, HTML, etc. (includes Pandoc)	Yes
TeX distribution	Used by Quarto to produce PDF output	For PDF output

macOS

# Install Node.js (if you don't have it)
brew install node

# Install Quarto (includes Pandoc)
brew install --cask quarto

# Install MacTeX for PDF output
brew install --cask mactex
# Or for a smaller (~100MB) install:
# brew install --cask basictex

Note on BasicTeX: If you use basictex instead of the full mactex, you may need to install additional LaTeX packages as Quarto requests them. Run sudo tlmgr install <package-name> when prompted.

After installing MacTeX, restart your terminal or run eval "$(/usr/libexec/path_helper)" to update your PATH.

Ubuntu / Debian

# Install Node.js (via NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Install Quarto
wget https://github.com/quarto-dev/quarto-cli/releases/latest/download/quarto-linux-amd64.deb
sudo dpkg -i quarto-linux-amd64.deb

# Install TeX Live for PDF output
sudo apt install -y texlive-full
# Or for a smaller install:
# sudo apt install -y texlive texlive-latex-extra texlive-fonts-recommended

Fedora / RHEL

# Install Node.js
sudo dnf install -y nodejs

# Install Quarto
wget https://github.com/quarto-dev/quarto-cli/releases/latest/download/quarto-linux-amd64.rpm
sudo rpm -i quarto-linux-amd64.rpm

# Install TeX Live for PDF output
sudo dnf install -y texlive-scheme-full

Windows

Install Node.js (LTS version, v18+)
Install Quarto (download the Windows installer)
Install MiKTeX for PDF output (enable "Install missing packages on the fly")

Verify Your Installation

After installing prerequisites, verify everything is available:

node --version    # Should print v18.x or higher
quarto --version  # Should print 1.x
pdflatex --version  # Should print pdfTeX info (optional, for PDF output)

Install WaldTeX

git clone https://github.com/StructuredLabs/waldtex.git
cd waldtex
npm install

Start WaldTeX

npm start

WaldTeX starts a local server and opens http://localhost:1618 in your default browser.

To start on a different port:

PORT=3000 npm start

Usage Guide

Your First Document

Start WaldTeX with npm start.
On the welcome screen, click New Project and choose the Article template.
WaldTeX creates a project folder at ~/waldtex-projects/my-article/ with a starter main.qmd file.
The editor opens with the template loaded. Start writing.
Press Cmd+S (or Ctrl+S) to save. The preview pane updates with your formatted document.

Understanding `.qmd` Files

A .qmd file is Markdown with a YAML header. Here's a minimal example:

---
title: "My Paper Title"
author: "Your Name"
date: today
format: pdf
bibliography: references.bib
---

## Introduction

Write your content here in plain Markdown.

Cite a reference with [@key]. Use inline math like $x^2$ or display math:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

## Methods

Add a figure:

![Description of the figure](figures/plot.png){#fig-plot}

Reference it with @fig-plot.

The YAML header controls everything: output format, bibliography file, numbering, fonts, margins, document class. See the Quarto documentation for all options.

File Types

WaldTeX handles different file types differently:

Extension	Behavior
`.qmd`	Quarto Markdown — compiles to PDF/Word/HTML via Quarto
`.md`	Pure Markdown — Obsidian-style notes with wiki links, no compilation
`.tex`	Raw LaTeX — opens in LaTeX editing mode for advanced use
`.bib`	BibTeX — opens in the bibliography manager

Writing Workflow

The typical workflow in WaldTeX:

Write in .md notes  ──→  Organize ideas with [[wiki-links]]
        │                          │
        ▼                          ▼
Draft in .qmd files  ──→  See live preview as you write
        │                          │
        ▼                          ▼
Compile with Quarto  ──→  PDF / Word / HTML output

Research phase — create .md notes for papers you're reading, ideas, experiment logs. Link between them with [[wiki-links]]. Use the graph view to see how your ideas connect.
Writing phase — create a .qmd file (or start from a template). Write your paper in Markdown. Reference your notes. Cite with @cite-key.
Review phase — toggle the PDF preview to see the final typeset output. Fix formatting issues. Use the embedded terminal to run Claude Code for feedback or to generate sections.
Export phase — render to PDF for journal submission, Word for collaborators, HTML for your website.

Using Wiki Links

In any .md or .qmd file, type [[ to create a wiki link:

See my notes on [[transformer-architecture]] for background.

This relates to the findings in [[experiment-log#results]].

[[filename]] links to filename.md or filename.qmd in your project
[[filename#heading]] links to a specific heading within that file
If the target file doesn't exist, WaldTeX creates it when you click the link
The backlinks panel shows you every file that links to the one you're currently editing

Managing Citations

Add entries to your references.bib file (manually or via the bibliography manager).
In your .qmd file, set bibliography: references.bib in the YAML header.
Cite with [@key] for parenthetical or @key for in-text citations:

Recent work [@vaswani2017; @devlin2019] has shown that...

As demonstrated by @vaswani2017, the attention mechanism...

Quarto automatically generates the bibliography at the end of your document.
To change citation style, add csl: ieee.csl to your YAML header (download CSL files from zotero.org/styles).

Multi-File Projects (Thesis, Book)

For large documents like a thesis, use a Quarto book project:

my-thesis/
  _quarto.yml          # Project configuration
  index.qmd            # Title page and abstract
  chapters/
    01-introduction.qmd
    02-literature.qmd
    03-methods.qmd
    04-results.qmd
    05-conclusion.qmd
  notes/               # Your research notes (not compiled)
    reading-log.md
    ideas.md
  references.bib
  figures/

The _quarto.yml file defines the chapter order and output settings:

project:
  type: book

book:
  title: "My Thesis"
  author: "Your Name"
  chapters:
    - index.qmd
    - chapters/01-introduction.qmd
    - chapters/02-literature.qmd
    - chapters/03-methods.qmd
    - chapters/04-results.qmd
    - chapters/05-conclusion.qmd

format:
  pdf:
    documentclass: report
    number-sections: true
    toc: true
    lof: true
    lot: true

Using the Embedded Terminal

Toggle the terminal with Ctrl+` (or Cmd+` on macOS).

The terminal opens in your current project directory. Some things you can do:

# Run Claude Code for AI-assisted writing
claude

# Compile manually with Quarto
quarto render main.qmd --to pdf

# Install a Quarto extension (e.g., journal template)
quarto add quarto-journals/elsevier

# Git operations
git add -A && git commit -m "Draft introduction"
git push origin main

Using with Claude Code

WaldTeX and Claude Code work together through the filesystem:

Open the terminal panel in WaldTeX.
Run claude.
Ask Claude to write, edit, or review your documents:
- "Write an introduction section about transformer architectures, citing papers from references.bib"
- "Fix the LaTeX error on line 42"
- "Rewrite the methods section to be more concise"
- "Add a figure environment for results.png with a caption"
Claude edits your .qmd files directly on disk.
WaldTeX detects the changes, reloads the editor, and recompiles automatically.

You never have to copy-paste between tools. The filesystem is the shared interface.

Keyboard Shortcuts

Shortcut	Action
`Cmd+S`	Save and compile
`Cmd+O`	Quick switcher (fuzzy file search)
`Cmd+K`	Command palette
`Cmd+B`	Toggle sidebar
Ctrl+`	Toggle terminal
`Cmd+Shift+P`	Toggle PDF / HTML preview mode
`Cmd+N`	New file
`Cmd+W`	Close current tab
`Cmd+\`	Split editor

Project Layout

When you create a WaldTeX project, it's just a folder on your filesystem:

~/waldtex-projects/
  my-paper/
    main.qmd             # Your document
    references.bib       # Bibliography
    figures/              # Images and plots
    notes/                # Research notes (.md)
    _quarto.yml           # Quarto project config (optional)
    .git/                 # Version history

There is nothing proprietary about this format. Your files are standard Markdown, BibTeX, and images. You can:

Open them in any text editor
Compile them with quarto render from any terminal
Push them to GitHub
Share them with collaborators who don't use WaldTeX
Move them to Overleaf if you ever want to

WaldTeX never locks you in.

Configuration

Application Settings

WaldTeX stores its configuration in ~/.waldtex/config.json:

{
  "projectsDir": "~/waldtex-projects",
  "port": 1618,
  "theme": "dark",
  "defaultFormat": "pdf",
  "compileOnSave": true,
  "compileDebounceMs": 500,
  "editor": {
    "fontSize": 14,
    "fontFamily": "JetBrains Mono, monospace",
    "lineNumbers": true,
    "wordWrap": true,
    "tabSize": 2
  },
  "quarto": {
    "engine": "pdflatex"
  }
}

All settings can also be changed from the in-app settings panel.

Per-Project Configuration

Each project can have a _quarto.yml file that configures Quarto's behavior for that project. See the Quarto project documentation for details.

Development

Want to work on WaldTeX itself? Here's how to set up a development environment.

Dev Setup

git clone https://github.com/StructuredLabs/waldtex.git
cd waldtex
npm install

Dev Server

npm run dev

This starts both the backend server and the Vite dev server with hot module replacement. Changes to the frontend code are reflected instantly in the browser.

Project Structure

src/
  server/            # Node.js backend (Express + WebSocket)
    index.ts         # Server entry point
    routes/          # REST API endpoints
    services/        # Business logic (Quarto, filesystem, git, link indexing)
  client/            # React frontend
    components/      # UI components (editor, preview, file tree, etc.)
    hooks/           # React hooks
    stores/          # Zustand state stores
    styles/          # Global styles and Tailwind config
templates/           # Built-in Quarto project templates

Tech Stack

Layer	Technology
Frontend framework	React 19 + TypeScript
Build tool	Vite
Editor	CodeMirror 6
Styling	Tailwind CSS
State management	Zustand
Layout	Allotment (split panes)
Backend	Express.js
Real-time	WebSocket (ws)
Compilation	Quarto CLI
Terminal	xterm.js + node-pty
Git	simple-git
Graph visualization	d3-force
Fuzzy search	fuse.js
File watching	chokidar

Scripts

Command	Description
`npm start`	Start WaldTeX (production mode)
`npm run dev`	Start with hot reload (development mode)
`npm run build`	Build for production
`npm run lint`	Run ESLint
`npm run typecheck`	Run TypeScript type checking
`npm test`	Run tests

Troubleshooting

"quarto: command not found"

Quarto is not installed or not in your PATH. Install it:

# macOS
brew install --cask quarto

# Linux — download from https://quarto.org/docs/get-started/
# Windows — download from https://quarto.org/docs/get-started/

"pdflatex: command not found" (PDF compilation fails)

You need a TeX distribution for PDF output. Install one:

# macOS
brew install --cask mactex
# Then restart your terminal, or run:
eval "$(/usr/libexec/path_helper)"

# Ubuntu/Debian
sudo apt install texlive-full

# Windows — install MiKTeX from https://miktex.org

Alternatively, if you only need HTML or Word output, you can skip the TeX installation entirely — Quarto generates those formats without LaTeX.

"LaTeX Error: File `.sty' not found"

If you installed basictex instead of the full mactex, you may be missing LaTeX packages. Install the missing package:

sudo tlmgr update --self
sudo tlmgr install <package-name>

Port 1618 is already in use

Start on a different port:

PORT=3000 npm start

Preview not updating

Make sure the file is saved (Cmd+S)
Check the status bar at the bottom for compilation errors
Open the error panel to see detailed Quarto/LaTeX output
Try a manual recompile from the compile button

Files edited externally aren't detected

WaldTeX watches your project directory for changes. If external edits aren't detected:

Make sure the file is within your project folder (not a symlinked directory outside it)
Restart WaldTeX — the file watcher reinitializes on startup

FAQ

Q: Do I need to know LaTeX? No. You write in Markdown. Quarto handles the LaTeX conversion. You only need LaTeX syntax if you want advanced formatting like custom equation layouts or TikZ diagrams.

Q: Can I use my existing LaTeX files? Yes. WaldTeX opens .tex files in LaTeX editing mode. You can compile them with Quarto (which passes them through to LaTeX) or keep them as-is alongside your Markdown files.

Q: Is my data sent anywhere? No. WaldTeX runs entirely on your machine. No telemetry, no cloud, no analytics. Your files never leave your computer.

Q: Can I use this with Zotero? Yes. Export your Zotero library as a .bib file (or use the Better BibTeX plugin for auto-sync) and point your .qmd YAML header at it: bibliography: my-library.bib.

Q: How is this different from VS Code with Quarto extension? WaldTeX is purpose-built for scientific writing. You get Obsidian-style wiki links, backlinks, graph view, and bibliography management out of the box — features that VS Code doesn't have. The interface is designed for writing, not general-purpose coding.

Q: Can I collaborate with others? WaldTeX is a single-user local tool. For collaboration, push your project to GitHub and use Git-based workflows (PRs, branches). Your collaborators can use WaldTeX, VS Code, Overleaf, or any editor — the files are standard Markdown and BibTeX.

Q: Can I use journal-specific templates? Yes. Quarto has an extension system for journal templates:

quarto add quarto-journals/elsevier
quarto add quarto-journals/plos
quarto add quarto-journals/acm

See the Quarto journal articles guide for the full list.

Roadmap

Contributing

We welcome contributions of all kinds — bug fixes, features, documentation, templates, and ideas.

See CONTRIBUTING.md for guidelines on:

Setting up a development environment
Code style and conventions
How to submit a pull request
Reporting bugs and requesting features

If you're not sure where to start, look for issues labeled good first issue.

Acknowledgments

WaldTeX is built on the shoulders of exceptional open source projects:

Quarto — the compilation engine that makes Markdown-to-PDF possible
CodeMirror — the editor component
Obsidian — inspiration for the linked-notes experience
Overleaf — inspiration for the live-preview workflow
PDF.js — PDF rendering in the browser
D3.js — graph visualization
xterm.js — terminal emulation

License

MIT License. See LICENSE for details.

You are free to use, modify, and distribute WaldTeX for any purpose.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
public		public
src		src
templates		templates
test-workspace		test-workspace
.editorconfig		.editorconfig
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
tsconfig.server.json		tsconfig.server.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

What is WaldTeX?

Why WaldTeX?

Quick Start

Features

Markdown-First Editor

Obsidian-Style Knowledge Management

Live Preview

Multi-Format Output via Quarto

Project Templates

Bibliography Manager

Version History (Git)

Embedded Terminal

Dark Theme

Installation

Prerequisites

macOS

Ubuntu / Debian

Fedora / RHEL

Windows

Verify Your Installation

Install WaldTeX

Start WaldTeX

Usage Guide

Your First Document

Understanding .qmd Files

File Types

Writing Workflow

Using Wiki Links

Managing Citations

Multi-File Projects (Thesis, Book)

Using the Embedded Terminal

Using with Claude Code

Keyboard Shortcuts

Project Layout

Configuration

Application Settings

Per-Project Configuration

Development

Dev Setup

Dev Server

Project Structure

Tech Stack

Scripts

Troubleshooting

"quarto: command not found"

"pdflatex: command not found" (PDF compilation fails)

"LaTeX Error: File `.sty' not found"

Port 1618 is already in use

Preview not updating

Files edited externally aren't detected

FAQ

Roadmap

Contributing

Acknowledgments

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Understanding `.qmd` Files

Packages