Skip to content

Quick Reference - Rxiv-Maker Cheat Sheet

Syntax and command reference for rxiv-maker workflows.

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)

Supplementary Prefix

The s prefix indicates supplementary elements: @sfig: (supplementary figure), @stable: (supplementary table), @snote: (supplementary note).

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

For configuration options, see the Configuration Reference.

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

For troubleshooting, see the Troubleshooting Guide.