PanDiff

Features

• Prose diffs for any document format supported by Pandoc
• Supported output formats:
  • CriticMarkup
  • HTML
  • PDF, via LaTeX
  • Word docx with Track Changes
• Respects document structure, so won't produce broken markup like wdiff

Installation

First install Pandoc and npm, then run:

npm install -g pandiff

Usage

pandiff test/old.md test/new.md

{~~Old~>New~~} Title
====================

{--![image](minus.png)--}

{++![image](plus.png)++}

1.  Lorem ipsum dolor {++sit ++}amet
2.  {++[consectetur adipiscing
elit](https://en.wikipedia.org/wiki/Lorem_ipsum)++}
3.  Lorem{-- ipsum--} dolor sit amet

I really love *italic {~~fonts~>font-styles~~}* {~~here.~>there.~~}

``` diff
 print("Hello")
-print("world.")
+print("world!")
 print("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt")
```

Don’t go around saying {--to people that --}the world owes you a
living. The world owes you nothing. It was here first. {~~One~>Only
one~~} thing is impossible for God: To find{++ any++} sense in any
copyright law on the planet. Truth is stranger than fiction, but it is
because Fiction is obliged to stick to possibilities; Truth isn’t.

Options

pandiff --help

Usage: pandiff [OPTIONS] FILE1 FILE2
      --bibliography=FILE
      --csl=FILE
      --columns=NUMBER
      --extract-media=PATH
  -F, --filter=STRING
  -f, --from=FORMAT
  -h, --help
      --highlight-style=STRING
      --lua-filter=FILE
      --template=STRING
      --mathjax=BOOL
      --mathml=BOOL
  -o, --output=FILE
      --pdf-engine=STRING
      --reference-dic=FILE
      --reference-links
      --resource-path=PATH
  -s, --standalone
  -t, --to=FORMAT
  -v, --version
      --wrap=STRING
      --metadata

Git integration

Configure git by running the following commands:

git config --global difftool.pandiff.cmd 'pandiff "$LOCAL" "$REMOTE"'
git config --global alias.pandiff 'difftool -t pandiff -y'

Now you can use git pandiff wherever you would usually use git diff.

HTML output

pandiff old.md new.md -s -o diff.html

PDF output

pandiff old.md new.md -o diff.pdf

Word Track Changes

pandiff old.md new.md -o diff.docx

pandiff test/track_changes_move.docx

Here is some text.

{++Here is the text to be moved.++}

Here is some more text.

{--Here is the text to be moved.--}

Docker Image

You can run pandiff inside a docker container locally on your machine by mounting the needed directory as a volume, using the following command.

docker run -v ~/documents/my-md-documents:/data davidar/pandiff -o diff.pdf old.md new.md

The docker image also allows you to create diff views inside github actions or a gitlab ci/cd pipeline.

GitHub Action

name: Markdown Diff

on:
  push:
    paths:
      - '**.md'
  workflow_dispatch:

jobs:
  compile-markdown-to-pdf:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run pandiff
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/work \
            -w /work \
            davidar/pandiff \
            pandiff -o diff.pdf old.md new.md

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: diff-pdf
          path: diff.pdf

Gitlab CI example

stages:
  - diff

compile_markdown_to_pdf:
  stage: compile
  image:
    name: davidar/pandiff
    entrypoint: ["/bin/sh", "-c"]

  script:
    - pandiff -o diff.pdf old.md new.md
  artifacts:
    paths:
      - diff.pdf