PanDiff

You can run PanDiff in a containerized environment by mounting your local documents directory as a volume. This avoids the need to install Pandoc and npm locally.

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

You can configure Git to use PanDiff as a difftool. This allows you to use git pandiff to view prose diffs instead of the standard line-based diff.

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

PanDiff requires Pandoc and npm to be installed on your system. Once those are available, install PanDiff globally using npm:

npm install -g pandiff

Pandiff applies specific 'critic' styles depending on the requested output format to ensure the diff is visually represented correctly in the target medium:

• LaTeX: Uses \color{Maroon} for deletions, \color{OliveGreen} for insertions, and \color{RedOrange} for substitutions.
• DOCX: Uses standard Word Track Changes styling (via HTML tags that Pandoc converts to track changes).
• HTML: Uses <span class="del"> and <span class="ins"> tags, often wrapped in a github-markdown-css styled container if standalone is enabled.
• Markdown: Uses custom syntax like {--deletion--}, {++insertion++}, and {~~subst1~>subst2~~}.

The pandiff CLI tool allows you to compare files and generate a diff. It supports three primary modes of operation based on the number and type of files provided:

1. Compare two files: Provide two files as positional arguments to generate a diff between them. pandiff FILE1 FILE2 [OPTIONS]

2. Track changes in a Word document: Provide a single .docx file to extract track changes. pandiff FILE.docx [OPTIONS]

3. Normalise a Markdown file: Provide a single .md file to normalise its content. pandiff FILE.md [OPTIONS]

Output is written to stdout.

# Compare two files
pandiff file1.md file2.md

# Track changes in a docx file
pandiff document.docx

# Normalise a markdown file
pandiff input.md

To use PanDiff in GitLab CI, use the davidar/pandiff image and set the entrypoint to /bin/sh to allow running the pandiff command directly.

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

To generate a prose diff between two files, provide the old file followed by the new file as arguments to the pandiff command.

pandiff test/old.md test/new.md

To generate an HTML version of the diff, use the -o (output) flag and the -s (standalone) flag to ensure a complete HTML document is produced.

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

PanDiff can output a .docx file that utilizes Microsoft Word's native 'Track Changes' feature. This is useful for collaborative editing.

# Diffing two files into a docx
pandiff old.md new.md -o diff.docx

# Processing a single file (e.g. to convert existing docx to track changes format)
pandiff test/track_changes_move.docx

You can use the davidar/pandiff Docker image within a GitHub Actions workflow to automatically generate PDF diffs when Markdown files are pushed.

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

To generate a PDF version of the diff, specify the output file with a .pdf extension using the -o flag.

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