Skip to content

Quick Reference - Rxiv-Maker Cheat Sheet

Syntax and command reference for rxiv-maker workflows.

Table of Contents

Essential Commands

Daily Workflow

Command Purpose
rxiv pdf Generate PDF from manuscript
rxiv validate Check manuscript structure and references
rxiv clean Remove generated output files
rxiv pdf --skip-validation Generate PDF without validation step

Project Management

Command Purpose
rxiv init <name> Create new manuscript
rxiv get-rxiv-preprint Clone official example manuscript
rxiv create-repo <name> Create manuscript repository with GitHub
rxiv repos List all manuscript repositories

Advanced Commands

Command Purpose
rxiv arxiv Prepare arXiv submission package
rxiv track-changes v1 v2 Generate visual diff between versions
rxiv docx Export to Microsoft Word format
rxiv changelog View release notes
rxiv upgrade Upgrade rxiv-maker

Build Options

# Skip steps for faster iteration
rxiv pdf --skip-validation        # Skip validation
rxiv pdf --skip-figures          # Don't regenerate figures
rxiv pdf --force-figures         # Force regenerate all figures

# Output control
rxiv pdf --verbose               # Detailed build output
rxiv pdf --quiet                 # Minimal output
rxiv pdf --debug                 # Debug information

# Combined workflows
rxiv pdf --docx                  # Generate PDF and DOCX
rxiv pdf --validate              # Generate PDF with validation

Markdown Syntax

Important: Rxiv-Maker Markdown Conventions

Rxiv-maker uses specialized syntax for scientific manuscripts that differs from standard markdown:

  • Title: Set in 00_CONFIG.yml (title: field), NOT in markdown
  • Sections: Use ## for all major sections (Abstract, Introduction, Methods, etc.)
  • Subsections: Use ### for subsections within major sections
  • NO # headings: Level 1 headings are not used in manuscript body
  • Figure captions: Go on same line as label: {#fig:id} **Bold title.** Description.
  • Table captions: Go on same line as label: {#tbl:id} **Bold title.** Description.
  • References: Auto-generated - do NOT add "## References" section

Comments (Hidden in Output)

<!-- This won't appear in the PDF -->
<!-- TODO: Add more details about the methodology -->
<!-- HIDDEN: Alternative phrasing -->

Headings

Manuscript heading structure:

## Introduction          # Major sections (Abstract, Introduction, Methods, etc.)
### Subsection Title     # Subsections within major sections

Notes: - Title is defined in 00_CONFIG.yml (title: field), not in markdown - # heading is NOT used in manuscript body (reserved for title only, not rendered) - ## starts all major sections: Abstract, Introduction, Results, Methods, Discussion, etc. - ### creates subsections within those major sections - Do NOT use # for sections in your manuscript

Text Formatting

**Bold text**
*Italic text*
***Bold italic***
`inline code`
~~Strikethrough~~

Lists

# Unordered
- Item 1
- Item 2
  - Nested item

# Ordered
1. First
2. Second
3. Third

[Link text](https://example.com)
[Link with title](https://example.com "Hover text")

Scientific References

Figures

@fig:label              # "Fig. 1"
@fig:label A            # "Fig. 1A" (panel reference)
@sfig:label             # "Fig. S1" (supplementary)
@sfig:label B           # "Fig. S1B"

Tables

@tbl:results            # "Table 1"
@stable:data            # "Table S1" (supplementary)

Equations

@eq:formula             # "Eq. (1)"

Sections

@sec:methods            # "Section 2"

Supplementary Notes

@snote:details          # Links to supplementary note section

# Definition (in 02_SUPPLEMENTARY_INFO.md):
{#snote:details} **Detailed Analysis**
Content of the supplementary note...

Figures

Figure Syntax

Correct format (label and options on same line as image, caption follows):

![Alt text description](FIGURES/script.py)
{#fig:label width="\textwidth" tex_position="t"} **Caption starts bold.** Rest of caption explaining the figure in detail.

# Reference in text
See Figure @fig:label for details.

Important: - Label {#fig:label} goes on the SAME line as the image markdown - Caption follows immediately after, starting with **bold text.** - Alt text in ![...] is for accessibility, caption comes after the label

Figure Options

![Alt text](FIGURES/plot.py)
{#fig:label width="\textwidth" tex_position="t" caption_width="\textwidth"}

Available Options: - width="\textwidth" - Full text width - width="0.8\textwidth" - 80% of text width - tex_position="t" - Position: t=top, b=bottom, h=here, p=page - caption_width="\textwidth" - Caption width

Figure Types

Python Script: 

![Analysis results](FIGURES/analysis_plot.py)
{#fig:analysis} **Analysis Results.** Detailed description of what the analysis shows.

R Script: 

![Statistical comparison](FIGURES/comparison_plot.R)
{#fig:comparison} **Statistical Comparison.** Description of the statistical findings.

Static Image (PDF/PNG): 

![Workflow diagram](FIGURES/workflow.pdf)
{#fig:workflow} **Workflow Overview.** Explanation of the workflow steps.

Note: Always include descriptive captions starting with bold text after the label.

Citations & References

Citation Syntax

[@author2023]                      # [1]
[@author2023; @smith2024]          # [1, 2]
@author2023 showed that...         # Author (2023) showed...
[@author2023, p. 42]              # [1, p. 42]

Citation Styles

In 00_CONFIG.yml: 

# Numbered citations [1, 2, 3]
citation_style: "numbered"

# Author-date citations (Smith, 2023)
citation_style: "author-date"

Inline DOI Resolution

Enable in 00_CONFIG.yml: 

enable_inline_doi_resolution: true

Usage in Markdown: 

Recent work 10.1038/nature12345 shows...
# Auto-converts to: Recent work @smith2023 shows...
# BibTeX entry generated automatically

BibTeX Entry Format

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

Mathematical Expressions

Inline Math

The equation $E = mc^2$ shows the relationship.

Display Equations

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

# Reference
See Equation @eq:diffusion for the model.

Common Math Symbols

$\alpha, \beta, \gamma$           # Greek letters
$\sum_{i=1}^{n}$                  # Summation
$\int_{0}^{\infty}$               # Integral
$\frac{a}{b}$                     # Fraction
$\sqrt{x}$                        # Square root
$x^2, x_i$                        # Superscript, subscript

Python Code Execution

Execute Python Code

{{py:exec
import pandas as pd
import numpy as np

df = pd.read_csv("DATA/results.csv")
sample_size = len(df)
mean_value = df['measurement'].mean()
std_dev = df['measurement'].std()
}}

Inject Variables into Text

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

Format Specifiers

{{py:get value}}           # Default formatting
{{py:get value:.2f}}       # 2 decimal places
{{py:get value:.3e}}       # Scientific notation
{{py:get value:,}}         # Thousands separator
{{py:get value:.1%}}       # Percentage

Common Patterns

# Calculate from CSV
{{py:exec
import pandas as pd
df = pd.read_csv("DATA/data.csv")
correlation = df['x'].corr(df['y'])
p_value = 0.001
}}

Correlation: r = {{py:get correlation:.3f}} (p < {{py:get p_value:.3f}})

# Statistical summary
{{py:exec
import numpy as np
data = [1.2, 1.5, 1.3, 1.4, 1.6]
mean = np.mean(data)
sem = np.std(data) / np.sqrt(len(data))
}}

Result: {{py:get mean:.2f}} ± {{py:get sem:.2f}}

Configuration Reference (00_CONFIG.yml)

Basic Metadata

title: "Your Manuscript Title"
short_title: "Short Title"
abstract: "Abstract text here"
keywords: ["keyword1", "keyword2", "keyword3"]

Authors

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

affiliations:
  - id: "1"
    name: "University Name"
  - id: "2"
    name: "Institute Name"

Citation Settings

bibliography: "03_REFERENCES.bib"
citation_style: "numbered"                    # or "author-date"
enable_inline_doi_resolution: true           # Auto-fetch DOI metadata

Document Settings

line_numbers: false
draft_watermark: false
track_changes: false

Tables

Simple Tables

Format: Label goes after the table, caption follows on same line:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

{#tbl:results} **Table Title.** Description of what the table shows and its key findings.

Reference: See Table @tbl:results

Supplementary Tables

| Header 1 | Header 2 |
|----------|----------|
| Data 1   | Data 2   |

{#stable:data} **Supplementary Data.** Additional supporting information.

Reference: See @stable:data

Alignment

| Left | Center | Right |
|:-----|:------:|------:|
| L1   | C1     | R1    |
| L2   | C2     | R2    |

{#tbl:aligned} **Alignment Example.** Demonstration of column alignment options.

Common Patterns

Manuscript Structure

Important: Title is set in 00_CONFIG.yml, NOT in markdown. All manuscript sections use ##:

## Abstract
Abstract text appears in a dedicated abstract section.

## Introduction
Background and motivation...

## Results
Findings and data...

## Methods
Experimental procedures...

## Discussion
Interpretation and implications...

## Data availability
Links to datasets...

## Code availability
Links to source code...

## Author contributions
Who did what...

## Acknowledgements
Funding and contributions...

<!-- References are auto-generated from citations, NOT manually added -->

Notes: - Title comes from 00_CONFIG.yml (title: field) - All major sections start with ## - ### for subsections within major sections - References/Bibliography auto-generated - do NOT add "## References" section

Figure with Analysis

{{py:exec
# Analysis code
import pandas as pd
df = pd.read_csv("DATA/experiment.csv")
effect_size = df['treatment'].mean() - df['control'].mean()
}}

![Experimental results](FIGURES/experiment_plot.py)
{#fig:experiment} **Treatment Effect Analysis.** Comparison between treatment and control groups showing significant differences.

Figure @fig:experiment shows a treatment effect of {{py:get effect_size:.2f}} units.

Multiple Figure Panels

![Multi-panel figure](FIGURES/multipanel.py)
{#fig:multipanel} **Multi-panel Analysis.** (A) Overview of the experimental setup, (B) Detailed view of cellular structures, (C) Quantification of measured parameters.

As shown in @fig:multipanel A, the overview reveals...
The detail in @fig:multipanel B shows...
Quantification in @fig:multipanel C confirms...

Troubleshooting Quick Fixes

Common Issues

LaTeX Errors: 

# Check LaTeX installation
rxiv check-installation

# Verbose output for debugging
rxiv pdf --verbose --debug

Figure Generation Failed: 

# Force regenerate all figures
rxiv pdf --force-figures

# Check figure script runs standalone
python FIGURES/figure_script.py

Citation Errors: 

# Validate citations
rxiv validate

# Check BibTeX file syntax
# Ensure all citation keys in markdown match BibTeX entries

Build Performance: 

# Fast iteration (skip validation and figures)
rxiv pdf --skip-validation --skip-figures

# Clean and rebuild
rxiv clean
rxiv pdf

File Issues

Output Directory: 

# Custom output location
rxiv pdf --output-dir custom_output/

# Clean specific output
rm -rf output/

Missing Dependencies: 

# Check Python environment
python --version  # Should be 3.11+

# Verify rxiv-maker installation
rxiv --version