Rxiv-Maker

Rxiv-Maker is an automated LaTeX article generation system that transforms scientific writing from chaos to clarity. It converts Markdown manuscripts into publication-ready PDFs with reproducible figures, professional typesetting, and zero LaTeX hassle.

The platform bridges the gap between easy writing (Markdown) and beautiful output (LaTeX), featuring automated figure generation from Python/R scripts and Mermaid diagrams, seamless citation management, Docker containerization for minimal-dependency execution (only Docker and Make required), and integration with GitHub Actions for accelerated cloud-based PDF generation.

Rxiv-Maker enhances the capabilities of traditional scientific writing by ensuring version control compatibility, facilitating reproducible science workflows, and providing professional formatting that meets publication standards.

Key Features

20+ Enhanced Markdown Features - Scientific cross-references, citations, subscript/superscript (rxiv-markdown)
Automated Figure Generation - Python/R scripts and Mermaid diagrams with smart caching
Intelligent Validation - Pre-build error detection with actionable feedback
Professional Output - LaTeX-quality PDFs with various citation styles
Multi-Environment - Local, Docker, Google Colab, and GitHub Actions support
Change Tracking - Visual diff PDFs against git tags
VS Code Integration - Dedicated extension with syntax highlighting
Modern CLI - Beautiful command-line interface with rich output and auto-completion

Key rxiv-markdown features: Scientific cross-references (@fig:label, @eq:label), citations (@citation), text formatting (~subscript~, ^superscript^), document control (<newpage>), and automated figure generation.

Key Benefits

Accessibility - Write in Markdown without LaTeX expertise
Reproducibility - Automated figures and version control ensure consistent results
Flexibility - Generate PDFs locally, in Docker, or via GitHub Actions
Professional Output - LaTeX-quality formatting with automated bibliography management
Collaboration - Git-based workflows with automated PDF generation

System Requirements

📋 Dependencies & Requirements

Core Requirements

Python: 3.11+ (automatically handled in Docker/Colab modes)
Git: For repository management
Make: Build automation (see platform-specific installation)

Python Dependencies

Automatically installed with pip install rxiv-maker or make setup:

matplotlib>=3.7.0    # Figure generation
seaborn>=0.12.0      # Statistical plotting  
numpy>=1.24.0        # Numerical computing
pandas>=2.0.0        # Data manipulation
PyYAML>=6.0.0        # Configuration parsing
pypdf>=3.0.0         # PDF processing
crossref-commons     # Citation validation
click>=8.0.0         # Modern CLI framework
rich>=13.0.0         # Beautiful terminal output

Optional Dependencies (Local Development Only Without Docker)

LaTeX: For PDF generation (TeX Live, MacTeX, or MikTeX)
Node.js: For Mermaid diagram generation
R: For R-based figure scripts

Platform-Specific Setup

Docker Mode: Only Docker Desktop + Make required
Google Colab: Zero local installation needed
GitHub Actions: Zero local installation needed
Local Development: Full dependency stack required

Quick Troubleshooting

Permission errors: Ensure user has write access to project directory
LaTeX not found: Use Docker mode or install platform-specific LaTeX
Python version issues: Use Docker mode or upgrade to Python 3.11+
Make command not found: Install build tools for your platform

📖 Full Installation Guide: Complete platform-specific instructions

Quickstart

🚀 Modern CLI (Recommended)

📦 Universal Install (Recommended)

# One command installs everything
pip install rxiv-maker

# Verify installation
rxiv check-installation

# Initialize new manuscript
rxiv init MY_PAPER/

# Build PDF
rxiv pdf MY_PAPER/

# Enable auto-completion (optional)
rxiv --install-completion bash  # or zsh, fish

🎛️ Installation Options

# Full installation (default)
pip install rxiv-maker

# Minimal installation (Python + LaTeX only)
RXIV_INSTALL_MODE=minimal pip install rxiv-maker

# Skip system dependencies
RXIV_SKIP_SYSTEM_DEPS=1 pip install rxiv-maker

📋 Alternative Setup Options

🌐 Google Colab (Easiest - no installation)

Prerequisites: Google account only
Setup Time: 2 minutes

🐳 Docker (Minimal dependencies)

Prerequisites: Docker Desktop + Make
Setup Time: 3-5 minutes

git clone https://github.com/henriqueslab/rxiv-maker.git
cd rxiv-maker
make pdf RXIV_ENGINE=DOCKER

🏠 Local Development (Full control)

Prerequisites: Python 3.11+, LaTeX, Make (platform guide)
Setup Time: 10-30 minutes

git clone https://github.com/henriqueslab/rxiv-maker.git
cd rxiv-maker
pip install -e .                    # Install with modern CLI
rxiv build                          # Generate PDF using CLI

🛠️ Legacy Make Interface (Still supported)

git clone https://github.com/henriqueslab/rxiv-maker.git
cd rxiv-maker
make setup && make pdf

Modern CLI Usage

Rxiv-Maker includes a modern command-line interface with rich output and intuitive commands:

Quick Start

# Install from PyPI
pip install rxiv-maker

# Initialize new manuscript
rxiv init MY_PAPER/

# Build PDF
rxiv pdf MY_PAPER/

# Validate manuscript
rxiv validate MY_PAPER/

Key CLI Commands

# Essential commands
rxiv build                          # Generate PDF from MANUSCRIPT/
rxiv build --force-figures          # Force regeneration of figures
rxiv validate                       # Validate manuscript
rxiv clean                          # Clean generated files

# Manuscript management
rxiv init MY_PROJECT/               # Initialize new manuscript
rxiv figures                        # Generate figures only
rxiv arxiv                          # Prepare arXiv submission

# Bibliography management
rxiv bibliography add 10.1000/doi   # Add DOI to bibliography
rxiv bibliography fix               # Fix bibliography issues
rxiv bibliography validate          # Validate bibliography

# Utility commands
rxiv version                        # Show version
rxiv version --detailed             # Show detailed system info
rxiv --help                         # Show help

🔧 CLI Features

Rich Output: Beautiful colors, progress bars, and formatted tables
Smart Validation: Pre-build error detection with helpful suggestions
Auto-completion: Support for bash/zsh/fish shells
Flexible Arguments: Intuitive command structure
Error Handling: Clear error messages with resolution tips
Configuration: Persistent settings with ~/.rxiv/config.toml
Backward Compatibility: All Make commands still work

📚 Complete CLI Reference

📖 Manuscript Management

rxiv init MY_PAPER/                 # Initialize new manuscript
rxiv build MY_PAPER/                # Generate PDF
rxiv validate MY_PAPER/             # Validate manuscript
rxiv clean MY_PAPER/                # Clean generated files

🎨 Figure Generation

rxiv figures MY_PAPER/              # Generate all figures
rxiv figures --force                # Force regeneration
rxiv build --force-figures          # Build with fresh figures

📚 Bibliography Management

rxiv bibliography add 10.1000/doi   # Add DOI to bibliography
rxiv bibliography fix               # Fix bibliography issues
rxiv bibliography validate          # Validate bibliography

📦 Publishing

rxiv arxiv MY_PAPER/                # Prepare arXiv submission
rxiv track-changes MY_PAPER/ v1.0.0 # Track changes vs git tag

⚙️ Configuration

rxiv config show                    # Show current configuration
rxiv config set key value           # Set configuration value
rxiv config get key                 # Get configuration value
rxiv config reset                   # Reset to defaults

🔧 System

rxiv setup                          # Setup development environment
rxiv version                        # Show version
rxiv version --detailed             # Show detailed system info
rxiv --help                         # Show help

🐳 Docker Support

rxiv build --engine docker          # Use Docker engine
rxiv config set general.default_engine docker  # Set Docker as default

Installation

🚀 Universal Install (Recommended)

# One command installs everything automatically
pip install rxiv-maker

# Verify installation
rxiv check-installation

What gets installed:

Python packages (matplotlib, numpy, etc.)
LaTeX distribution (for PDF generation)
Node.js + Mermaid CLI (for diagrams)
R language (optional, for statistical figures)
System libraries (automatically detected)

🎛️ Installation Options

# Full installation (default)
pip install rxiv-maker

# Minimal installation (Python + essential LaTeX only)
RXIV_INSTALL_MODE=minimal pip install rxiv-maker

# Core installation (Python + LaTeX, skip Node.js/R)
RXIV_INSTALL_MODE=core pip install rxiv-maker

# Python packages only (skip all system dependencies)
RXIV_SKIP_SYSTEM_DEPS=1 pip install rxiv-maker

🍺 Homebrew (macOS) - Deprecated

# Still supported but deprecated in favor of universal installer
brew tap henriqueslab/rxiv-maker
brew install rxiv-maker

📋 Development Install

git clone https://github.com/henriqueslab/rxiv-maker.git
cd rxiv-maker
pip install -e .                       # Modern hatch-based build system

🔧 Auto-completion Setup

# For bash users
rxiv --install-completion bash

# For zsh users  
rxiv --install-completion zsh

# For fish users
rxiv --install-completion fish

🔄 Migration from Make Commands

Existing users can continue using Make commands or migrate to the CLI:

Make Command	CLI Command	Notes
`make setup`	`rxiv setup`	Setup environment
`make pdf`	`rxiv build`	Build PDF
`make validate`	`rxiv validate`	Validate manuscript
`make clean`	`rxiv clean`	Clean files
`make arxiv`	`rxiv arxiv`	Prepare arXiv
`make pdf FORCE_FIGURES=true`	`rxiv build --force-figures`	Force figures
`MANUSCRIPT_PATH=path/ make pdf`	`rxiv build path/`	Custom path

📖 Complete migration guide: docs/MIGRATION.md
📚 Complete CLI reference: docs/CLI_REFERENCE.md
📋 CLI modernization changelog: docs/CHANGELOG_CLI.md

⚡ GitHub Actions (Team collaboration)

Prerequisites: GitHub account only
Setup Time: 5 minutes
Guide: Automated cloud builds guide

📝 VS Code (Enhanced editing)

Prerequisites: VS Code editor
Extension: VS Code Extension for syntax highlighting

Core Workflow

Write manuscript in Markdown (01_MAIN.md)
Configure metadata in YAML (00_CONFIG.yml)
Create figures with Python/R scripts or Mermaid diagrams
Validate with make validate
Build PDF with make pdf

Documentation

📚 Complete Documentation Index

Getting Started

Installation Guide - Complete setup for all platforms
User Guide - Complete usage instructions

Platform Guides

Local Development Setup - Platform-specific installation
Docker Engine Mode - Containerized development
Google Colab Tutorial - Browser-based PDF generation
GitHub Actions Guide - Automated cloud builds

Advanced Features

Change Tracking - Version diff PDFs
Troubleshooting - Common issues and fixes

Development

VS Code Extension - Enhanced editing experience
API Documentation - Code reference

Quick Commands

make pdf                              # Generate PDF
make validate                         # Validate manuscript  
make pdf MANUSCRIPT_PATH=MY_PAPER     # Custom manuscript
make pdf FORCE_FIGURES=true           # Force figure regeneration
make pdf-track-changes TAG=v1.0.0     # Track changes vs git tag
make clean                            # Clean output files
make setup                            # Install dependencies

Quick Help

Issues? Check Troubleshooting Guide
Platform problems? See Installation Guide
Need help? Visit GitHub Discussions

Project Structure

rxiv-maker/
├── MANUSCRIPT/              # Your manuscript files
│   ├── 00_CONFIG.yml       # Metadata and configuration
│   ├── 01_MAIN.md          # Main manuscript content
│   ├── 02_SUPPLEMENTARY_INFO.md  # Optional supplementary
│   ├── 03_REFERENCES.bib   # Bibliography
│   └── FIGURES/            # Figure generation scripts
├── output/                 # Generated PDFs and artifacts
├── src/                    # Rxiv-Maker source code
└── docs/                   # Documentation

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

git clone https://github.com/henriqueslab/rxiv-maker.git
pip install -e ".[dev]" && pre-commit install

Release Process

For maintainers releasing new versions:

Create GitHub release with tag v1.4.0
PyPI publishing happens automatically
Homebrew formula updates manually or daily
See Release Process Guide for details

🔧 Troubleshooting Installation

If installation fails or components are missing:

# Check what's installed
rxiv check-installation --detailed

# Repair broken installation
rxiv check-installation --fix

# Or manually repair
python -m rxiv_maker.install.manager --repair

# Reinstall system dependencies
python -m rxiv_maker.install.manager --mode full

Common Issues:

No admin rights: Use RXIV_INSTALL_MODE=minimal
Behind proxy: System package managers may fail
Docker/CI: Use RXIV_SKIP_SYSTEM_DEPS=1
Partial install: Run repair command above

How to Cite

If you use Rxiv-Maker in your research, please cite our work:

BibTeX:

@article{saraiva_2025_rxivmaker,
  author       = {Saraiva, Bruno M. and Jacquemet, Guillaume and Henriques, Ricardo},
  title        = {Rxiv-Maker: an automated template engine for streamlined scientific publications},
  journal      = {Zenodo},
  publisher    = {Zenodo},
  year         = 2025,
  month        = jul,
  doi          = {10.5281/zenodo.15753534},
  url          = {https://zenodo.org/records/15753534},
  eprint       = {https://zenodo.org/records/15753534/files/2025__saraiva_et_al__rxiv.pdf}
}

APA Style: Saraiva, B. M., Jacquemet, G., & Henriques, R. (2025). Rxiv-Maker: an automated template engine for streamlined scientific publications. Zenodo. https://doi.org/10.5281/zenodo.15753534

Related Projects

Rxiv-Maker VS Code Extension - Enhanced editing experience with syntax highlighting, IntelliSense, and project integration

Acknowledgments

We extend our gratitude to the scientific computing community, especially the matplotlib and seaborn communities for their plotting tools, the LaTeX Project for professional typesetting, and Mermaid for accessible diagram generation.

License

MIT License - see LICENSE for details. Use it, modify it, share it freely.

Name		Name	Last commit message	Last commit date
Latest commit History 374 Commits
.github		.github
EXAMPLE_MANUSCRIPT		EXAMPLE_MANUSCRIPT
FIGURES		FIGURES
MANUSCRIPT		MANUSCRIPT
docs		docs
git_submodules		git_submodules
notebooks		notebooks
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.env		.env
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
appveyor.yml		appveyor.yml
mermaid-config.json		mermaid-config.json
noxfile.py		noxfile.py
pyproject.toml		pyproject.toml
requirements-dev.lock		requirements-dev.lock
requirements.lock		requirements.lock
uv.lock		uv.lock

License

HenriquesLab/rxiv-maker

Folders and files

Latest commit

History

Repository files navigation

Rxiv-Maker

Key Features

Key Benefits

System Requirements

Core Requirements

Python Dependencies

Optional Dependencies (Local Development Only Without Docker)

Platform-Specific Setup

Quick Troubleshooting

Quickstart

🚀 Modern CLI (Recommended)

📋 Alternative Setup Options

Modern CLI Usage

Quick Start

Key CLI Commands

🔧 CLI Features

📚 Complete CLI Reference

📖 Manuscript Management

🎨 Figure Generation

📚 Bibliography Management

📦 Publishing

⚙️ Configuration

🔧 System

🐳 Docker Support

Installation

🚀 Universal Install (Recommended)

🎛️ Installation Options

🍺 Homebrew (macOS) - Deprecated

📋 Development Install

🔧 Auto-completion Setup

🔄 Migration from Make Commands

Core Workflow

Documentation

Getting Started

Platform Guides

Advanced Features

Development

Quick Commands

Quick Help

Project Structure

Contributing

Release Process

🔧 Troubleshooting Installation

How to Cite

Related Projects

Acknowledgments

License

About

Topics

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

Packages