docrev

CLI tool for Word ↔ Markdown round-trips. Handle reviewer feedback on academic papers: import track changes, review interactively, manage comments, validate DOIs, and build to PDF/DOCX/LaTeX.

Install

npm install -g docrev

The rev command is now available globally.

Prerequisites

• Node.js 18+ - Download
• Pandoc - For building PDF/DOCX (pandoc.org)
• pandoc-crossref - For figure/table refs (optional, install)

# macOS
brew install pandoc pandoc-crossref

# Ubuntu/Debian
sudo apt install pandoc

# Windows
winget install JohnMacFarlane.Pandoc

Verify installation:

rev --version
rev install    # Check for missing dependencies

Shell Completions (Optional)

Enable tab completion for rev commands:

# Bash - add to ~/.bashrc
eval "$(rev completions bash)"

# Zsh - add to ~/.zshrc
eval "$(rev completions zsh)"

Features

• Integrated build system - Combine sections → paper.md → PDF, DOCX, or LaTeX
• Import from Word - Diff Word docs against your Markdown, generating CriticMarkup annotations
• Section-aware import - Import directly to modular section files (intro.md, methods.md, etc.)
• Interactive review - Accept/reject track changes with a TUI
• Comment management - List, filter, resolve, and reply to reviewer comments
• Response letter generation - Auto-generate point-by-point response from comments
• DOI validation - Check and find DOIs via Crossref/DataCite APIs
• Cross-reference conversion - Auto-convert "Figures 1-3" to @fig:label syntax (handles complex patterns)
• Equation extraction - Extract LaTeX equations from Word documents (OMML → LaTeX)
• Citation validation - Check citations against bibliography

Quick Start

Start from Word Document

# Import existing Word doc → creates section files + rev.yaml
rev import manuscript.docx

# Import to specific directory
rev import manuscript.docx -o my-paper/

# Preview without creating files
rev import manuscript.docx --dry-run

New Project from Template

# Create a new paper project
rev new my-paper

# or with a specific template
rev new my-thesis --template thesis

# List available templates
rev new --list

Build Workflow

cd my-paper

# Edit your sections
# introduction.md, methods.md, results.md, discussion.md

# Build PDF and Word
rev build

# Build specific format
rev build pdf
rev build docx
rev build tex
rev build all    # PDF + DOCX + TEX

Review Workflow

# Import reviewer's Word doc to section files
rev sections reviewed.docx

# Review track changes interactively
rev review methods.md

# See remaining comments
rev comments methods.md

# Rebuild
rev build docx

Commands

Build & Create

Import & Export

Review & Edit

Cross-References

Comments & Replies

Bibliography & DOIs

Validation & Analysis

Multi-Reviewer & Git

Configuration

Convenience Commands

Grammar & Style

Spelling

Direct DOCX Editing

Project Structure

A typical rev project:

my-paper/
├── rev.yaml           # Project config (title, authors, build settings)
├── introduction.md    # Section files
├── methods.md
├── results.md
├── discussion.md
├── references.bib     # Bibliography
├── figures/           # Images
├── paper.md           # Combined output (generated)
├── my-paper.pdf       # PDF output (generated)
└── my-paper.docx      # Word output (generated)

Configuration (rev.yaml)

title: "Your Paper Title"
authors:
  - name: First Author
    affiliation: Institution
    email: author@example.com

sections:
  - introduction.md
  - methods.md
  - results.md
  - discussion.md

bibliography: references.bib
csl: nature.csl           # Optional citation style

crossref:
  figureTitle: Figure
  tableTitle: Table
  figPrefix: [Fig., Figs.]
  tblPrefix: [Table, Tables]

pdf:
  documentclass: article
  fontsize: 12pt
  geometry: margin=1in
  linestretch: 1.5
  toc: false                 # Table of contents

docx:
  reference: template.docx   # Optional reference doc
  keepComments: true
  toc: false                 # Table of contents

Annotation Syntax (CriticMarkup)

{++inserted text++}      # Insertions
{--deleted text--}       # Deletions
{~~old~>new~~}           # Substitutions
{>>Author: comment<<}    # Comments

Template Variables

Use template variables in section files (processed during build):

Last updated: {{date}}
Version: {{version}}
Word count: {{word_count}}

Comment Replies

Reply to reviewer comments with your name:

# Set your name (once)
rev config user "Gilles Colling"

# Interactive: go through each comment
rev reply methods.md

# Non-interactive: reply to specific comment
rev reply methods.md -n 1 -m "Done, added clarification"

Creates a conversation thread:

{>>Reviewer: Please clarify this<<} {>>Gilles Colling: Added in next paragraph<<}

Claude can also reply programmatically using the non-interactive mode.

Cross-Reference System

Use dynamic references in your source:

![Caption](figures/img.png){#fig:heatmap}

See @fig:heatmap for the results.

When importing from Word, hardcoded refs are auto-converted:

• Figure 1 → @fig:heatmap
• Fig. 2a → @fig:model
• Figs. 1-3 → @fig:heatmap; @fig:model; @fig:hierarchy
• Figures 1, 2, and 3 → @fig:one; @fig:two; @fig:three
• Fig. 1a-c → @fig:one (expands letter suffixes)
• Figs. 1a-3b → all panels from 1a to 3b

Build Outputs

DOI Management

Check and find DOIs for your bibliography:

# Validate all DOIs in references.bib
rev doi check references.bib

# Look up missing DOIs automatically
rev doi lookup references.bib --confidence medium

# Fetch BibTeX from a DOI
rev doi fetch 10.1038/nature12373

# Add a citation by DOI
rev doi add 10.1038/nature12373

Features:

• Validates DOIs via Crossref API (+ DataCite for Zenodo/Figshare)
• Smart lookup using title, author, year, and journal matching
• Filters out supplement/figure DOIs and F1000 reviews
• Confidence levels: high, medium, low (use --confidence low to see all matches)
• Skip entries with nodoi = {true} or % no-doi comment

Dependencies

• Node.js 18+
• Pandoc - Document conversion
• pandoc-crossref - Cross-references (optional but recommended)
• mammoth - Word document parsing
• diff - Text diffing

License

MIT