Skip to content

About

A PDF reader that allows highlighting and adding Markdown note.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

PDF Margin Notes

A PDF reader in one HTML file. Highlight text, write Markdown notes in the margin, and keep the PDF, the notes and the images together in one .zip bundle.

Try it: https://huodx.github.io/pdf-margin-notes/

PDF Margin Notes: a PDF page on the left, three Markdown notes in the margin on the right

Features

  • Highlights in four styles. Fill, underline, box and hatch, in black and white.
  • Markdown notes in the margin. Each note sits at the same height as its highlight. A line connects the two.
  • Images in notes. Drop or paste images into a note, or drop an image on a highlight.
  • Jumps in two directions. Click a highlight to go to its note. Click a note to go to its highlight.
  • A margin that you can resize. Drag the bar between the pages and the notes, from 4 : 1 to 1 : 1. The note text gets larger in a wide margin.
  • One bundle for everything. Export the original PDF, the notes, a Markdown copy of the notes and the images as one .zip file. Open the file again to continue.
  • Local and private. The reader runs in your browser. It does not send your files to a server.
  • Light. One HTML file, no build step, no framework. Four small libraries load from a CDN.

Use the reader

  1. Open the reader. Click Open PDF or bundle, or drop a .pdf file on the page.
  2. Select text on a page. Then press H or click + Note.
  3. Write the note in Markdown. To add an image, drop or paste it into the editor.
  4. Press Esc or Ctrl+Enter to finish the note.
  5. Click Export bundle (or press Ctrl+S) to save your work as a .zip file.
  6. To continue later, open the .zip file in the reader.

The reader also keeps a copy of your notes in the browser (IndexedDB). A browser can delete this copy, for example when you clear the site data. Thus, export the bundle to keep your work.

Keys and mouse actions

Action Result
Select text, then H Highlight the text and open a note.
Click a highlight Go to its note.
Click a note Go to its highlight.
Double-click a note, or Enter Edit the note.
Ctrl+Enter or Esc Finish the edit.
Drop or paste an image Add the image to a note.
J / K Go to the next note or the previous note.
+ / − / 0, Ctrl+wheel Zoom in, zoom out, fit the page width.
Drag the bar between pages and notes Resize the notes column. Double-click the bar to reset it.
Ctrl+S Export the bundle.
? Show all keys.

On macOS, use Cmd for Ctrl.

The bundle format

A bundle is a normal .zip file:

File Contents
document.pdf The original PDF. The reader does not change it.
notes.json All notes, with the positions of the highlights.
notes.md The same notes as one Markdown file, in page order.
images/<id>.<ext> The images of the notes.
README.txt A short description of the files.

notes.json has this structure:

{
  "format": "pdf-margin-notes",
  "version": 1,
  "exported": "2026-11-18T10:00:00.000Z",
  "pdf": { "name": "paper.pdf", "fingerprint": "…", "file": "document.pdf", "pages": 12 },
  "notes": [
    {
      "id": "k3m9qa",
      "rects": [{ "p": 0, "x": 0.112, "y": 0.304, "w": 0.71, "h": 0.016 }],
      "quote": "The highlighted text",
      "md": "**My note** with an image: ![](img:i4f8k2m7wq1)",
      "mark": "fill",
      "created": 1795000000000,
      "updated": 1795000000000
    }
  ]
}
  • p is the page index. The first page is 0.
  • x, y, w and h are fractions of the page width and the page height. Thus, the positions do not change with the zoom.
  • mark is fill, line, box or hatch.
  • In md, img:<id> refers to the file images/<id>.<ext>.
  • created and updated are times in milliseconds since 1970 (UTC).

When you open a bundle, the reader merges its notes with the notes in the browser. If a note is in both places, the reader keeps the version with the later updated time.

Privacy

  • The reader reads your PDF files, notes and images only in your browser. It does not upload them.
  • The page loads its libraries from jsDelivr and its fonts from Google Fonts. These services can see your IP address. To prevent this, copy the libraries and fonts into the repository, and change the URLs in index.html.

Deploy to GitHub Pages

The repository is ready for GitHub Pages. The workflow .github/workflows/pages.yml runs the tests, and then it publishes index.html and the examples folder.

  1. Push the repository to GitHub. Use main as the branch name.
  2. On GitHub, go to Settings → Pages.
  3. Under Build and deployment → Source, select GitHub Actions.
  4. Go to the Actions tab, select Deploy to GitHub Pages, and click Run workflow. The first automatic run can fail if it started before step 3. After step 3, each push to main deploys the site.
  5. When the workflow finishes, open https://<your-username>.github.io/<repository-name>/.
  6. Put this address in the Try it line at the top of this README.

You can also use Deploy from a branch with the main branch and the / (root) folder. The file .nojekyll tells GitHub Pages to publish the files as they are. With this method, the tests do not run before the deploy.

Run the reader on your computer

You need Node.js 20 or later.

npm install
npm start

Then open http://127.0.0.1:4173/. The local server loads the libraries from node_modules, so the reader works without the internet. To use the CDN URLs instead, run USE_CDN=1 npm start.

You can also use any static file server, for example python3 -m http.server. Then the libraries load from jsDelivr.

Note: some browsers block parts of the reader when you open index.html directly as a file (file://). Use a local server.

Tests

The tests use Playwright. They open the sample PDF, make highlights and notes, add images, test the jumps, the zoom and the drag bar, export a bundle and import it into a new browser profile.

npx playwright install chromium   # one time
npm test

To use a Chrome that is already on your computer, set CHROME_PATH, for example CHROME_PATH=/usr/bin/google-chrome npm test.

Project layout

Path Contents
index.html The complete reader: HTML, CSS and JavaScript.
examples/sample.pdf The sample PDF that the Try the sample PDF button opens.
examples/make-sample.py The script that makes the sample PDF (needs reportlab).
tests/ The Playwright tests and the local server.
docs/screenshot.png The screenshot in this README.
.github/workflows/ The workflows for the tests and for GitHub Pages.

Libraries

Library Version Use License
PDF.js (pdfjs-dist) 6.4.299 Shows the PDF pages and the text layer. Apache-2.0
marked 18.1.2 Changes Markdown into HTML. MIT
DOMPurify 3.4.17 Removes unsafe HTML from the notes. MPL-2.0 or Apache-2.0
fflate 0.8.3 Makes and opens the .zip bundles. MIT
IBM Plex Mono and IBM Plex Sans Google Fonts Fonts of the interface. SIL OFL 1.1

The versions in index.html and in package.json must be the same. A test checks this. See CONTRIBUTING.md for the steps to update a library.

Browser support

The reader works in current versions of Chrome, Edge, Firefox and Safari. It needs JavaScript modules, IndexedDB and the CSS round() function. The automated tests use Chromium.

Contributing

Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct. To report a security problem, read SECURITY.md.

License

MIT

About

A PDF reader that allows highlighting and adding Markdown note.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages