PageProof

PageProof is meant for writers who like the look of Microsoft Word, but who want to switch to AI-friendly Markdown files. It shows a browser preview of your Markdown file:

• live, so that it updates whenever the Markdown file changes
• paginated, so that footnotes appear at the bottom of the page
• with support for citations from a bibliography file
• easily styleable by an AI agent

(If all you want is to view a simple Markdown document with fixed style, it's enough to use a browser extension such as Markdown Viewer.)

Internally, it uses pandoc for compiling Markdown to html, including citation handling. (Pandoc must be installed.) Note that Markdown can include scripts, so only preview Markdown you trust!

Installation and usage

npm install -g pageproof

# install as a skill for Codex
mkdir -p ~/.agents/skills/pageproof && cp "$(pageproof --skill-file)" ~/.agents/skills/pageproof/SKILL.md

# install as a skill for Claude Code
mkdir -p ~/.claude/skills/pageproof && cp "$(pageproof --skill-file)" ~/.claude/skills/pageproof/SKILL.md

This tool is designed to be usable by AI coding agents:

• Just say "Please start a live preview of MYFILE.md" and it should just work.
• If you want a different styling, just say so, for example "Please show it double-spaced."
• If PageProof finds errors in the document, the preview will show them (look for a button at the top right) and also make the background pink. You can ask the agent "Please fix the errors in my document" and it should know what to do.

To run it yourself at the command line:

pageproof FILE.md

This will start up a browser viewing the compiled document. When you close the browser, PageProof will automatically shut down.

Document and citation styles

Document styles can be specified at the command line. For example, to get double-spaced output with section numbering,

pageproof --style=doublespaced --style=numbered FILE.md

These styles are applied in order, after the base styles. The default list of base styles consists of just a single item, the msword style. To see a full list of available styles,

pageproof --styles

To override the base style list, or to add your own styles, see below under Configuration.

For one-off overrides, use --css=CSS to append literal CSS. This is intended for AI-agent-generated adjustments such as page geometry:

pageproof --css='@page { size: letter; margin: 0.5in; }' FILE.md

Such --css styles can be interleaved with --style styles, and they are applied in the order given on the command line.

Citations are handled by Pandoc with citeproc. Your Markdown document should include front-matter naming the bibliography file, such as

---
title: My Document
bibliography: myrefs.bib
---

and then you can cite using [@citeref]. To choose the citation format, use e.g.

pageproof --citations=chicago FILE.md

Available citation formats are listed by pageproof --styles.

Configuration

To specify the default document styles and citation style, specify the configuration in ~/.pageproof/config.yaml:

styles: [msword]
citations: ejil

Additional CSS stylesheets or CSL bibliography styles can be placed in ~/.pageproof/, as NAME.css or NAME.csl respectively. They will then be included in the pageproof --styles list, and you can select them with --style or --citations. In the case of name conflict, user-provided files take precedence over the built-in styles.

Third party notices

See THIRD_PARTY_NOTICES.md for a list of bundled third-party components: CSL styles, MathJax, and Paged.js.

WSL note

I run this under WSL, and it works fine for me for markdown files on either the WSL filesystem or the Windows filesystem. Apparently, some people have reported that the library that watches for file changes is less reliable for files stored on the Windows filesystem, but I haven't seen this myself.