User Guide¶

Complete guide for productive scientific writing with Rxiv-Maker.

Prerequisites

Before diving into the user guide, complete the First Manuscript Tutorial to get familiar with the basics.

📖 Core Concepts¶

What is Rxiv-Maker?¶

Rxiv-Maker is a framework that converts Markdown into professional, publication-ready PDFs. It's designed specifically for scientific preprints and academic manuscripts, with features that automate figure generation, citation management, and LaTeX typesetting.

Key Benefits: - Write in Markdown - Focus on content, not formatting - Automated Figures - Generate publication-ready figures from Python/R scripts - Self-Updating - Dynamic content that updates with your data - Git-Friendly - Version control for manuscripts and figures - Reproducible - Complete workflow from data to publication

How It Works¶

graph LR
    A[Markdown + Scripts] --> B[Rxiv-Maker]
    B --> C[LaTeX Processing]
    C --> D[Publication PDF]

    E[Data Files] --> B
    F[Bibliography] --> B
    G[Figures] --> B

Write your manuscript in enhanced Markdown
Add figure generation scripts (Python/R)
Configure metadata and settings
Generate professional PDF with one command

🖊️ Daily Writing Workflow¶

Basic Writing Cycle¶

The core writing cycle is simple and fast:

Standard WorkflowFast IterationFull Rebuild

# 1. Validate manuscript
rxiv validate

# 2. Edit your content
# Open 01_MAIN.md and make changes

# 3. Generate PDF
rxiv pdf

# Skip validation for faster builds
rxiv pdf --skip-validation

# Skip figure regeneration
rxiv pdf --skip-figures

# Both for maximum speed
rxiv pdf --skip-validation --skip-figures

# Clean everything and rebuild
rxiv clean
rxiv pdf --force-figures

Writing Session Tips¶

Start of Session: - Run rxiv validate to check manuscript health - Generate a preview PDF to see current state - Review any validation warnings

During Writing: - Make incremental changes - Generate PDFs frequently to catch issues early - Use --skip-validation for faster iteration

End of Session: - Run full validation: rxiv validate --detailed - Generate final PDF: rxiv pdf - Commit changes to Git with descriptive message

📁 Manuscript Structure¶

File Organization¶

A typical Rxiv-Maker manuscript has this structure:

my-manuscript/
├── 00_CONFIG.yml              # Metadata and settings
├── 01_MAIN.md                 # Main manuscript content
├── 02_SUPPLEMENTARY_INFO.md   # Optional supplementary
├── 03_REFERENCES.bib          # Bibliography
├── FIGURES/                   # Figure generation scripts
│   ├── figure_01.py          # Python figure script
│   ├── figure_02.R           # R figure script
│   └── static_image.png      # Static images
├── DATA/                      # Data files (optional)
│   └── experiment_data.csv
├── src/                       # Analysis modules (optional)
│   └── analysis_utils.py
└── output/                    # Generated PDFs (auto-created)
    └── manuscript.pdf

Configuration File (00_CONFIG.yml)¶

The configuration file controls metadata and formatting:

# Basic metadata
title: "Your Manuscript Title"
short_title: "Short Title"  # For headers

# Author information
authors:
  - name: "First Author"
    affiliation: "1"
    email: "[email protected]"
    corresponding: true
  - name: "Second Author"
    affiliation: "1,2"

affiliations:
  - id: "1"
    name: "Institution Name"
  - id: "2"
    name: "Second Institution"

# Document settings
abstract: "Your abstract text here"
keywords: ["keyword1", "keyword2", "keyword3"]
bibliography: "03_REFERENCES.bib"

# Optional settings
line_numbers: false
draft_watermark: false

✍️ Writing in Enhanced Markdown¶

Rxiv-Maker extends standard Markdown with scientific features:

Text Formatting¶

**Bold text** for emphasis
*Italic text* for subtle emphasis
__Underlined text__ when needed
***Bold and italic*** for strong emphasis
`inline code` for technical terms

Headings and Structure¶

# Main Section (Level 1)
## Subsection (Level 2)
### Sub-subsection (Level 3)

Abstract, Introduction, Methods, Results, Discussion, Conclusion
are common sections for scientific papers.

Mathematical Notation¶

Inline math: $E = mc^2$

Display equations:
$$
\frac{\partial u}{\partial t} = \nabla^2 u
$$
{#eq:diffusion}

Reference equations: See Equation @eq:diffusion

Citations and References¶

Single citation: [@smith2023]
Multiple citations: [@smith2023; @jones2024]
In-text citation: @smith2023 showed that...
With page numbers: [@smith2023, p. 42]

## References
<!-- Bibliography automatically generated here -->

Lists and Tables¶

Unordered list:
- First item
- Second item
  - Nested item

Ordered list:
1. First step
2. Second step
3. Third step

Simple tables:
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

📊 Working with Figures¶

Figure Syntax¶

![Figure caption text](FIGURES/figure_script.py)
{#fig:label}

Reference in text: See Figure @fig:label

Figure Options¶

![Caption](FIGURES/figure.py)
{#fig:label width="0.8\\linewidth" tex_position="t"}

Available options: - width: Figure width (e.g., 0.8\\linewidth, 12cm) - tex_position: LaTeX position (t=top, b=bottom, h=here, p=page) - caption_width: Custom caption width

Figure Types¶

Rxiv-Maker supports multiple figure sources:

Python ScriptsR ScriptsStatic Images

# FIGURES/analysis_plot.py
import matplotlib.pyplot as plt
import numpy as np

# Generate data
x = np.linspace(0, 10, 100)
y = np.sin(x)

# Create figure
plt.figure(figsize=(8, 6))
plt.plot(x, y)
plt.xlabel('Time')
plt.ylabel('Signal')
plt.title('Analysis Results')

# Save (rxiv-maker handles this automatically)
plt.tight_layout()
plt.show()

# FIGURES/analysis_plot.R
library(ggplot2)

# Load data
data <- read.csv("DATA/experiment.csv")

# Create plot
p <- ggplot(data, aes(x = time, y = signal)) +
  geom_line() +
  theme_minimal() +
  labs(title = "Analysis Results",
       x = "Time", y = "Signal")

# Save
ggsave("analysis_plot.png", p, width = 8, height = 6, dpi = 300)

![Static image](FIGURES/diagram.png)
{#fig:diagram}

Supported formats: PNG, JPG, SVG, PDF

For detailed figure documentation, see the Figures Guide.

📚 Citation Management¶

BibTeX File (03_REFERENCES.bib)¶

@article{smith2023,
    title = {Important Research Findings},
    author = {Smith, John and Doe, Jane},
    journal = {Nature},
    volume = {123},
    pages = {456--789},
    year = {2023},
    doi = {10.1038/nature12345}
}

@book{jones2024,
    title = {Comprehensive Research Methods},
    author = {Jones, Alice},
    publisher = {Academic Press},
    year = {2024},
    isbn = {978-0-12-345678-9}
}

Citation Commands¶

# Validate citations
rxiv validate

# Check for undefined citations
rxiv validate --citations-only

# Fetch BibTeX from DOI
curl -H "Accept: application/x-bibtex" https://dx.doi.org/10.1038/nature12345

🔧 Common Tasks¶

Quick Command Reference¶

# Essential commands
rxiv init my-paper          # Create new manuscript
rxiv pdf                    # Generate PDF
rxiv validate              # Check manuscript
rxiv clean                 # Clean generated files

# Advanced commands
rxiv arxiv                 # Prepare arXiv submission
rxiv track-changes v1 v2   # Compare versions
rxiv check-installation    # Verify setup

# Build options
rxiv pdf --verbose         # Show detailed output
rxiv pdf --draft          # Add draft watermark
rxiv pdf --force-figures  # Regenerate all figures

Git Integration¶

# Initialize repository
git init
git add .
git commit -m "Initial manuscript"

# Daily workflow
git add 01_MAIN.md FIGURES/
git commit -m "Add results section and analysis"

# Before major changes
git checkout -b feature/new-analysis

# Validation pre-commit hook
echo "rxiv validate" > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

🚀 Advanced Topics¶

Python Code Execution¶

Execute Python code blocks that update manuscript content:

{{py:exec
import pandas as pd
df = pd.read_csv("DATA/results.csv")
sample_size = len(df)
mean_value = df['measurement'].mean()
}}

Our analysis of {{py:get sample_size}} samples shows
mean = {{py:get mean_value:.2f}} units.

Learn more: Python Execution Guide

LaTeX Injection¶

For advanced typesetting:

Advanced notation: {{tex: $\langle\psi|\phi\rangle$}}
Scientific units: {{tex: \SI{273.15}{\kelvin}}}

Learn more: LaTeX Injection Guide

Reproducible Workflows¶

Create fully reproducible manuscripts:

# Document environment
pip freeze > requirements.txt

# Include in repository
git add requirements.txt DATA/ src/
git commit -m "Add reproducible environment"

Learn more: Reproducible Workflows Guide

📖 Additional Resources¶

Documentation¶

Getting Started

New to Rxiv-Maker? Start here

Installation First Manuscript
Advanced Features

Unlock the full power of Rxiv-Maker

Python Execution LaTeX Injection
Troubleshooting

Solutions for common issues

Troubleshooting Guide
Examples

Learn from real manuscripts

Example Repository

Community¶

GitHub Discussions - Ask questions and share tips
GitHub Issues - Report bugs and request features
VS Code Extension - Enhanced editing experience

Ready to write your manuscript? Head back to the First Manuscript Tutorial or explore Advanced Features.