docrev - Document Revision Tool

rev is a CLI tool for document workflows with Word ↔ Markdown round-trips.

Works for any document that goes through Word-based review: scientific papers, contracts, reports, proposals, manuals.

Content and Layout, Separated

In Markdown, you focus on content. Write text, add citations with [@key], insert equations with $...$ , reference figures with @fig:label. No fiddling with fonts or styles.

Layout is controlled in rev.yaml:

title: "My Document"
docx:
  reference: template.docx

Change the template, rebuild, and every document gets the new formatting.

Core Workflow

1. Create or import a project

rev new my-document          # Start from scratch
rev import manuscript.docx   # Start from existing Word doc

2. Build and share

rev build docx               # Generate Word document

Send to reviewers. They add comments and track changes in Word.

3. Import feedback

rev sync reviewed.docx              # Updates markdown with annotations
rev sync                            # Auto-detect most recent .docx
rev sync reviewed.docx --comments-only  # Insert comments only; never modify prose
rev verify-anchors reviewed.docx    # Report which anchors still match current prose

Use --comments-only when the markdown has been revised between sending the docx out and receiving it back. Without the flag, track changes from a stale draft would clobber newer edits. With it, only comments are imported, placed at fuzzy-matched anchors against the current prose. Run rev verify-anchors first to see which comments will land cleanly and which need manual placement.

4. View and address comments

rev status                   # Project overview
rev todo                     # List all pending comments
rev next                     # Show next pending comment
rev comments methods.md      # List all comments with context

5. Reply to reviewer comments

Always use the non-interactive reply mode:

rev reply methods.md -n 1 -m "Added clarification about sampling methodology"
rev reply results.md -n 3 -m "Updated figure to include 95% CI"

Replies appear as: {>>Reviewer: Original<<} {>>User: Reply<<}

6. Resolve addressed comments

rev resolve methods.md -n 1  # Mark comment #1 as resolved

7. Rebuild with comment threads

rev build docx --dual                 # Produces clean + annotated versions
rev build docx --show-changes         # Single DOCX with visible track changes
rev build docx --dual --show-changes  # One DOCX: tracked changes + threaded comments

--dual produces:

output/<title>.docx — clean, for submission
output/<title>_comments.docx — comment threads as Word comments

--show-changes produces a single audit DOCX (<title>-changes.docx) where every accepted/rejected revision is rendered as a visible Word track change. Useful when a co-author wants to see what changed since the last shared version.

--dual --show-changes combines both into one <title>-changes.docx: my {++..++}/{--..--} edits as tracked changes and the reviewer's {>>..<<} comments with my threaded replies. This is the file a supervisor opens, reviews next to each other, and hands back. Add --reference <docx> to realign comment anchors against a reviewer's copy first.

Outputs land in output/ by default; set outputDir: null in rev.yaml to keep them alongside paper.md (legacy layout). The basename is derived from title: unless overridden — set output: { docx: foo.docx, pdf: foo.pdf } in rev.yaml or pass -o, --output <path> on the CLI. See REFERENCE.md → "Choosing output filenames".

For pandoc flags rev doesn't surface directly (Lua filters, custom variables, templates), use --pandoc-arg (repeatable) or pandoc-args: in rev.yaml (both top-level and per-format). Run with --verbose to see the exact pandoc invocation. See REFERENCE.md → "Passing custom pandoc args" for details.

8. Archive reviewer files

rev archive                  # Move reviewer files to archive/

9. Generate response letter

rev response                 # Generate point-by-point response letter

Annotation Syntax (CriticMarkup)

{++inserted text++} - Additions
{--deleted text--} - Deletions
{~~old~>new~~} - Substitutions
{>>Author: comment<<} - Comments
{>>Author: comment [RESOLVED]<<} - Resolved comment

Quick Commands

Task	Command
Create project	`rev new my-project`
Create LaTeX project	`rev new my-project --template latex`
Import Word doc	`rev import manuscript.docx`
Sync Word feedback	`rev sync reviewed.docx`
Sync comments only (prose unchanged)	`rev sync reviewed.docx --comments-only`
Verify anchors against current prose	`rev verify-anchors reviewed.docx`
Sync PDF comments	`rev sync annotated.pdf`
Extract PDF comments	`rev pdf-comments annotated.pdf`
Extract with highlighted text	`rev pdf-comments file.pdf --with-text`
Append PDF comments	`rev pdf-comments annotated.pdf --append methods.md`
Project status	`rev status`
Next pending	`rev next`
List pending	`rev todo`
Filter by author	`rev comments file.md --author "Reviewer 2"`
Reply to all pending	`rev reply file.md --all -m "Addressed"`
Accept all changes	`rev accept file.md -a`
Build Word	`rev build docx`
Build PDF	`rev build pdf`
Build clean + annotated Word	`rev build docx --dual`
Build clean + annotated PDF	`rev build pdf --dual`
Build with visible track changes	`rev build docx --show-changes`
Show contributors	`rev contributors`
Lookup ORCID	`rev orcid 0000-0002-1825-0097`
Archive reviewer files	`rev archive`
Word count per section	`rev word-count`
Project dashboard	`rev stats`
Search all sections	`rev search "query"`
Pre-submission check	`rev check`
Validate citations	`rev citations`
Check grammar/style	`rev grammar`
Check spelling	`rev spelling`
Open PDF preview	`rev preview pdf`
Auto-rebuild on changes	`rev watch`
Check for updates	`rev upgrade --check`
Assign paragraph IDs, scaffold journey.md	`rev journey init`
Check manuscript against story/journey	`rev journey check`
Build story.md/journey.md to docx	`rev build story` / `rev build journey`

DOI Management

rev doi check references.bib         # Validate DOIs
rev doi lookup references.bib        # Find missing DOIs
rev doi add 10.1234/example          # Add citation from DOI

Validation

rev validate --journal nature        # Check journal requirements
rev validate --list                  # List 21 built-in journal profiles, plus custom ones
rev lint                             # Check broken refs, missing citations

Cross-References

Use in markdown files:

@fig:label - Figure reference (becomes "Figure 1" in Word)
@tbl:label - Table reference
@eq:label - Equation reference
{#fig:label} - Anchor for figures

Insert a figure with the format-portable syntax (renders in both PDF and Word):

![Caption text.](figures/foo.pdf){#fig:foo width=80%}

Raw \begin{figure}...\end{figure} LaTeX blocks are PDF-only. For docx builds, rev auto-translates the common shape (single \includegraphics with optional \caption{...} and \label{...}) to the markdown form above so figures still render. Exotic blocks (\subfloat, \rotatebox, multiple \includegraphics) are left alone and warned about — convert them by hand or supply a custom Lua filter via --pandoc-arg. Opt out of auto-translate with docx.translateRawFigures: false in rev.yaml.

Story & Journey Sidecars

Up to three optional files sit beside a manuscript for its whole life and are never part of a build:

story.md — the argument: a claim, an audience, and a few arcs. Each arc has a question, answer, evidence (a @fig:/@tbl:/@eq: label or a source, never a restated number), its limits, and the arcs it needs before it.
journey.md — one entry per paragraph (and per figure, table, equation, or code block, at its reading position): a stable ID, the arc(s) it serves, its job in one sentence, and what the reader leaves understanding. Front matter (before the first level-1 heading), back matter (acknowledgements, availability statements, references, supplementary material) and bold-label lines (**Keywords:** ...) need no entry unless given a marker.
information.md — the terms and populations a reader must hold: forms, as, one defined: @p:id (or known, or none), avoid. Checked for undefined terms, avoided wordings, use before definition, form collisions and unused entries. A journey entry's - negotiated: <who> <date> #<hash>: <decision> pins a paragraph settled with a co-author; rev check fails when it changes until rev journey ack <id>, as it does on an undefined term or an avoided wording.
supplement/journey.md — the supporting information's journey: one entry per table, figure, appendix or unnumbered section (### tbl.key [arcs]), in print order, with its section file (under supplement/sections/), tier (evidence, reference, development, archive) and the @p: paragraphs it supports. SI text cites items by key (Table [[tbl:key]]); position sets the labels (S1, S2, ... per kind, A1, A2, ... for archive items).

A paragraph's ID lives in the section file as  on the line before it — a semantic slug (intro.memory), not a position, so moving the paragraph keeps its ID. It survives rev sync/rev import and is dropped from every build.

rev journey init                     # assign IDs, scaffold journey.md
rev journey check                    # check the manuscript against story/journey
rev journey check --json             # same, as structured findings
rev journey ack <ids...>             # reconfirm negotiated paragraphs after an edit
rev build story                      # story.md → docx for co-authors
rev build journey                    # journey.md → docx for co-authors

rev journey check also runs as step 4 of rev check when journey.md exists. Findings (missing markers, orphan paragraphs, unclaimed arcs, arcs introduced before what they need, unresolved evidence, near-duplicate paragraphs, floats with no entry; for the supplement: section files missing or not placed, keys or literal Table S<n> labels that resolve to no item, the manuscript citing an archive item, evidence supporting no paragraph, a stale supplement/numbers.json label lock) are structure decisions made visible, not hard errors — the user decides which to act on. For drafting story.md/ journey.md with the user, or reading a manuscript into them, use the paper-sidecars skill if available.

Config: story:/journey:/supplementJourney: keys in rev.yaml override the default story.md/journey.md/supplement/journey.md filenames, and supplementSections: the supplement/sections directory.

Template Variables

Available in section files (processed during build):

{{date}} - Current date (YYYY-MM-DD)
{{date:MMMM D, YYYY}} - Custom format
{{title}} - Document title
{{author}} - First author
{{word_count}} - Total word count

Project Structure

my-document/
├── rev.yaml           # Project config
├── introduction.md    # Section files with annotations
├── methods.md
├── results.md
├── discussion.md
├── references.bib     # Bibliography
├── figures/           # Images
├── paper.md           # Combined sections (auto-generated)
└── output/            # Built artefacts
    ├── my-document.docx
    └── my-document.pdf

Set outputDir: null in rev.yaml to write outputs alongside paper.md instead.

PDF Comment Workflow

For reviewers who annotate PDFs instead of Word documents:

1. Extract comments from PDF

rev pdf-comments annotated.pdf              # Display all comments
rev pdf-comments annotated.pdf --by-author  # Group by reviewer
rev pdf-comments annotated.pdf --json       # Output as JSON

2. Import into markdown

rev sync annotated.pdf                      # Auto-import to sections
rev pdf-comments annotated.pdf --append methods.md  # Append to specific file

3. Build PDF with margin notes

rev build pdf --dual

Produces:

paper.pdf — clean version for submission
paper_comments.pdf — comments rendered as LaTeX margin notes

Supported PDF Annotations:

Sticky notes, text boxes, highlights, underlines, strikethrough, squiggly

When Helping Users

Setup: Ensure rev config user "Name" is set for replies
Sync phase: Run rev sync to get feedback (works with both Word and PDF)
Review phase: Use rev todo and rev next to navigate comments, rev reply to respond
Accept phase: Use rev accept -a or rev review to handle track changes
Build phase: Run rev build docx --dual or rev build pdf --dual for annotated versions
Archive phase: Run rev archive to move reviewer files
Validation phase: Run rev check before submission
Response letter: Use rev response to generate point-by-point responses

Critical: Ask Questions When Unsure

When addressing reviewer comments or editing documents:

Never guess methods or numbers - If a comment asks for clarification about methodology, sample sizes, statistical parameters, dates, or any quantitative information, ASK the user rather than inventing values
Placeholders are acceptable - Use [???] or [TODO: specify X] when information is missing rather than fabricating data
Search online for references - When comments request citations, use web search to find appropriate references rather than guessing
Clarify ambiguous requests - If a reviewer comment could be interpreted multiple ways, ask the user which interpretation they prefer
Verify existing values - When editing numbers that already exist in the document, confirm changes with the user if there's any doubt

Example scenarios requiring user input:

"Add a reference for this claim" → Search online OR ask user for specific citation
"Clarify the sample size" → Ask user for the correct number
"Specify the statistical test used" → Ask user which test was actually used
"Add the date of data collection" → Ask user for the actual date

For complete command reference, see REFERENCE.md.

docrev

SKILL.mdskill