User Guide¶

How to write, build, and export a manuscript with Rxiv-Maker day to day.

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

You write in enhanced Markdown, add figure scripts and a bibliography, then run rxiv pdf to produce a typeset PDF.

The writing cycle¶

rxiv validate   # check the manuscript
rxiv pdf        # build the PDF

rxiv pdf --skip-validation   # skip checks
rxiv pdf --skip-figures      # reuse cached figures

rxiv clean
rxiv pdf --force-figures

Build frequently to catch issues early. Run rxiv validate --detailed before a final build.

Manuscript 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 scripts and static images
├── DATA/                      # Data files (optional)
└── output/                    # Generated PDFs (auto-created)

Metadata and build options live in 00_CONFIG.yml. See the Configuration Reference for every setting.

Enhanced Markdown¶

Rxiv-Maker reads standard Markdown plus a few scientific extensions.

**Bold**, *italic*, `inline code`

# Section    ## Subsection    ### Sub-subsection

Inline math $E = mc^2$ and display math:
$$ \frac{\partial u}{\partial t} = \nabla^2 u $$
{#eq:diffusion}

Reference elements by label: Equation @eq:diffusion, Figure @fig:results.

Tables and lists use ordinary Markdown syntax. For raw LaTeX inside Markdown, see LaTeX Injection.

Figures¶

Point the image at a script (Python or R) or a static file; Rxiv-Maker runs the script during the build.

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

Reference it as Figure @fig:results.

Options: width, tex_position (t/b/h/p), caption_width. Supported static formats: PNG, JPG, SVG, PDF. For panel layouts, caching, and R examples, see the Figures Guide.

Citations¶

Add references to 03_REFERENCES.bib, then cite them inline:

Single [@smith2023], multiple [@smith2023; @jones2024], in-text @smith2023.

rxiv validate reports undefined or unused citations. Rxiv-Maker can also resolve bare DOIs pasted into the text (rxiv pdf --resolve-dois). To cite Rxiv-Maker itself, see How to Cite.

Export to Word (DOCX)¶

For co-authors who need track changes:

rxiv docx                     # PDF-equivalent Word file
rxiv docx --tables-as-images  # render all tables as images, matching the PDF

Figures, tables, citations, and formatting are preserved. Markdown tables become native Word tables; complex {{tex:...}} tables are rendered as images. Set docx.tables_as_images: true in 00_CONFIG.yml to make that the default.

Going further¶