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.

One sentence per line¶

The manuscript rxiv init generates puts each sentence on its own line. Markdown joins consecutive lines into a paragraph, so the PDF and Word output are identical either way.

The difference shows up in version control. Reword one sentence in a paragraph written as a single long line, and the diff marks the whole paragraph as changed:

- Cells were imaged every 30 s. Segmentation used Otsu thresholding. Tracks shorter than 10 frames were discarded.
+ Cells were imaged every 15 s. Segmentation used Otsu thresholding. Tracks shorter than 10 frames were discarded.

Written one sentence per line, the same edit points at the sentence that moved:

  Cells were imaged every 30 s.
- Segmentation used Otsu thresholding.
+ Segmentation used Otsu thresholding with a 3-pixel median pre-filter.
  Tracks shorter than 10 frames were discarded.

This matters most when co-authors review a revision, or when you generate a tracked-changes file with rxiv docx --track-changes. The engine treats both styles the same, so this is a convention rather than a requirement.

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¶