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/
- 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
.zipfile. 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.
- Open the reader. Click Open PDF or bundle, or drop a
.pdffile on the page. - Select text on a page. Then press H or click + Note.
- Write the note in Markdown. To add an image, drop or paste it into the editor.
- Press Esc or Ctrl+Enter to finish the note.
- Click Export bundle (or press Ctrl+S) to save your work as a
.zipfile. - To continue later, open the
.zipfile 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.
| 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.
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: ",
"mark": "fill",
"created": 1795000000000,
"updated": 1795000000000
}
]
}pis the page index. The first page is 0.x,y,wandhare fractions of the page width and the page height. Thus, the positions do not change with the zoom.markisfill,line,boxorhatch.- In
md,img:<id>refers to the fileimages/<id>.<ext>. createdandupdatedare 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.
- 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.
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.
- Push the repository to GitHub. Use
mainas the branch name. - On GitHub, go to Settings → Pages.
- Under Build and deployment → Source, select GitHub Actions.
- 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
maindeploys the site. - When the workflow finishes, open
https://<your-username>.github.io/<repository-name>/. - 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.
You need Node.js 20 or later.
npm install
npm startThen 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.
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 testTo use a Chrome that is already on your computer, set CHROME_PATH, for example CHROME_PATH=/usr/bin/google-chrome npm test.
| 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. |
| 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.
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.
Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct. To report a security problem, read SECURITY.md.
