Skip to content

PDF Incremental Reading Workflow

Jump to bottom
hugomarins edited this page May 4, 2026 · 19 revisions

PDF Incremental Reading Workflow

This page documents how to use the Incremental Everything plugin to incrementally read long PDFs by breaking them into chapters or sections, each managed as a separate Incremental Rem.

Overview: The Full Incremental Workflow

The Incremental Everything approach to PDFs is designed to support deep reading without feeling overwhelmed. The workflow typically looks like this:

  1. Split & Prioritize: Instead of one massive PDF to read, you create multiple Incremental Rems for the PDF (e.g., one per chapter or section) and assign each a priority.
  2. Read in the Queue: When a chapter is due, it appears in your Queue. The PDF Reader automatically opens at your last saved reading position.
  3. Extract & Organize: As you encounter important information, you use PDF highlights. With the PDF Highlight Toolbar utilities, you can easily turn these highlights into their own Incremental Rems, seamlessly organizing them into your Knowledge Base structure.
  4. Track Position & Deep Link: When you extract information (or toggle a highlight as incremental), the plugin automatically saves that highlight's page as your current reading position. Furthermore, if you extract sub-text from those Incremental Rems later, the new sub-extracts will smartly inherit a reference pin bridging directly back to the original PDF highlight!
  5. Manage Globally: Use the PDF Control Panel to manage all chapters from a single interface.

Step-by-Step Setup

The core idea is to link multiple Incremental Rems to the same PDF, each covering a different page range. This lets you:

  • Queue chapters independently with their own priorities and schedules
  • Use the PDF Control Panel to manage all chapters from a single interface
  • Switch between reading the PDF and processing your notes per chapter

1. PDF Structure Setup

📁 Book Title (folder rem, contains the PDF)
  ├── Chapter 1  ← Incremental Rem, PDF source, pages 1–50
  ├── Chapter 2  ← Incremental Rem, PDF source, pages 51–120
  └── Chapter 3  ← Incremental Rem, PDF source, pages 121–200
  1. Create a parent folder rem for the book and add the PDF as its source (or as a direct child rem).
  2. Create child rems for each chapter.
  3. Tag the first chapter as Incremental (Alt+X) and add the PDF as its source.
  4. Use Copy & Paste Rem Sources (below) to efficiently propagate the PDF source to all other chapters.
  5. Open PDF Control Panel (Command Palette → PDF Control Panel) on any of the rems with that PDF source to assign the page range to all chapters.

2. Copying and Pasting Sources

When you have many chapters, manually adding the PDF source to each one would be tedious. Two commands automate this:

Command Shortcut Description
Copy Rem Sources Ctrl+Shift+F1 Copies all sources from the focused Rem into a session clipboard
Paste Rem Sources Opt+Shift+V / Alt+Shift+V Adds the copied sources to all selected Rems (or the focused Rem if nothing is selected)

Workflow

  1. Focus your template chapter (the one already linked to the PDF).
  2. Press Ctrl+Shift+F1 → a toast confirms how many sources were copied (e.g., "📋 1 source copied").
  3. Select all remaining chapter rems in the outliner (hold Shift and click, or use Shift+↑/↓).
  4. Press Alt+Shift+V → each selected rem receives the same PDF source. A summary toast reports how many sources were added and how many were already present.
  5. Open PDF Control Panel on any chapter to set page ranges.

Tip

The paste operation is idempotent — sources already present on a target rem are silently skipped. You can safely run paste multiple times or on a mix of rems that already have the source and rems that don't.

Note

The clipboard is session-scoped — copied source IDs are stored in session storage and discarded when you close the tab. There is no cross-session contamination.

Copy and Paste source

3. PDF Control Panel

The PDF Control Panel (Command Palette → PDF Control Panel) is the central hub for managing all rems that share the same PDF.

Features:

  • Set and adjust the page range for each chapter
  • Edit priorities inline with visual feedback
  • View reading histories and time spent
  • Make rems Incremental without leaving the panel
  • Sort chapters by page range for logical reading progression

Hierarchical Tree View

The All Rems Using This PDF list builds a containment tree based on page ranges:

  • If a rem's range is fully contained within another's (e.g. a sub-section inside a chapter), it appears indented below the parent.
  • Depth-based indentation (16 px/level) makes nesting visible at a glance.
  • Rems without an assigned page range float below the tree at depth 0.

This is useful when you split a chapter into sub-sections during incremental reading — you can see the exact hierarchy without any manual tagging.

Overlap detection: If two siblings have genuinely overlapping ranges, an inline ⚠ overlap badge appears on both. Shared boundary pages (one chapter ends on page 265, the next starts on page 265) are not flagged.

Coverage badge: Parent rows show an X/Ypp badge with a tiny fill bar indicating how many pages are already covered by child rems. Hover to see the percentage (e.g. "25 of 30 pages covered by sub-rems (83%)"). This tells you at a glance how much of a chapter still needs to be sub-divided.

PDF Control Panel

4. PDF Highlight Toolbar Utilities

When you select text in the PDF Reader and create a highlight, the native RemNote popup toolbar appears. The plugin injects three powerful widgets into this toolbar to help you process and organize information on the fly:

Icon Tool Description
🔖 Set Bookmark Position Manually records your current reading position at this highlight's exact page. (Note: Using the extraction tools below will also do this automatically).
Create Incremental Rem Extracts the highlight into a standalone Incremental Rem and lets you choose precisely where it should live in your Knowledge Base hierarchy. See the [[dedicated guide here
Toggle Incremental Rem Quick-tags the highlight itself as an Incremental Rem without moving it. The button background turns blue to indicate the highlight is now actively tracked in your queue.
Pdf highlight menu buttons

Automatic Position Tracking

A major benefit of using the Create Incremental Rem or Toggle Incremental Rem tools while you are reviewing a chapter in the Queue is that the plugin automatically assumes you have read up to that highlight's page.

It will seamlessly update the bookmark/reading position for the current chapter, so the next time the item is due, you will be taken right back to where you left off — no need to manually click the 🔖 button.

🔖 Set Bookmark Position — Queue Behaviour

When you click 🔖 while reviewing in the Queue, the popup opens instantly (no search overhead) and shows a single "Update Current Queue Reading" button pre-targeted at the active chapter. Clicking it saves the bookmark and closes the popup automatically so you can continue reading without an extra click.

  • Outside the Queue, the popup falls back to showing all Incremental Rems linked to this PDF (the full list), letting you choose which chapter should receive the bookmark.

5. Document Notes (Side-by-Side Reading)

When reading a PDF or HTML Incremental Rem in the queue, you can easily pull up the document's notes in the right sidebar. This lets you read the source material and write notes simultaneously without constantly switching contexts.

  • Click the 📝 Document Notes icon in the document's top bar (next to the breadcrumbs).
  • The document's own Rem opens in the Right Sidebar.
  • You can write notes, organize extracts, or add new child rems directly into the document's hierarchy while the PDF remains visible on the left.
  • The sidebar dynamically syncs with the queue: it shows the notes when you are reviewing an applicable IncRem, and gracefully shows an empty state during flashcard turns.

Highlight IncRems: The sidebar also works when reviewing PDF Highlight or HTML Highlight Incremental Rems. Since highlights are linked to the source PDF/HTML document (not directly to the reading IncRem that created them), the sidebar automatically discovers all Incremental Rems that read the same source. If multiple are found, a selector is shown so you can choose which IncRem's notes to view. If only one exists, it is auto-selected.

PDF Side Notes

Document Notes Sidebar — Highlight IncRem Selector

6. Flexible Processing Modes

Each chapter rem can be opened in two modes, controlled by tags:

Default Mode (PDF Reader)

Without any special tag, selecting a chapter in the queue opens the PDF Reader at the configured page range. This is the standard reading mode.

ExtractViewer Mode

Add the extractviewer tag to a chapter rem to open it in the ExtractViewer instead. This lets you see your notes and children, process highlights, and work with your extracted material — all without losing the PDF source connection needed for the PDF Control Panel.

Toggle behavior simply by adding or removing the extractviewer tag:

State Opens in
No tag PDF Reader (configured page range)
#extractviewer tag ExtractViewer (notes and children)

#preferthispdf Tag (Multiple Sources)

If an Incremental Rem has multiple PDF sources, the plugin uses the #preferthispdf tag to decide which one to open — both in the queue/reader and in the PDF Control Panel.

Resolution logic (applies everywhere):

Situation Result
Only one PDF source Opens that PDF directly
Multiple sources, one tagged #preferthispdf Opens that specific PDF
Multiple sources, more than one tagged Shows a conflict warning toast; falls back to ExtractViewer / does not open the panel
Multiple sources, none tagged Falls back to the first PDF found (legacy behaviour)

To use it:

  • Add the tag #preferthispdf (or #prefer this pdf — whitespace is ignored) to exactly one of the PDF source rems.
  • The plugin will identify it as the primary PDF consistently across the queue, ExtractViewer, and PDF Control Panel.

Note

Previously, the PDF Control Panel command ignored this tag and always picked the first PDF it found, meaning the control panel and the queue could be operating on different PDFs for the same rem. This is now fixed — both use the same findPreferredPDFInRem() logic.

7. Inline PDF Range Management (Priority Editor)

For a faster workflow when the PDF is open on the right side of the screen, you can manage a rem's page range directly from the Priority Editor sidebar widget — without opening any popup.

The Priority Editor (shown to the right of every Incremental Rem in the editor) gains a 📄 PDF Range section whenever the current rem has a PDF source:

State What you see
No range set yet Dim 📄 — indicator in collapsed view; "No range" label in expanded view
Range set 📄 p.X–Y pill in collapsed (includes the current reading position in green parenthesis, e.g. (Z), if history exists); range badge + action buttons in expanded

Available actions in expanded view:

  • 📄 Range — Inline range editor
    • Tab cycles between Start → End fields; Enter saves.
    • Both fields auto-select their value on focus so you can just type the new number.
  • 📖 Position — Record reading position
    • Defaults to the last recorded page, or the first page of the range the first time.
    • Validates the entry: if the page is outside the rem’s assigned range, the border turns red and Save is disabled.
    • Enter saves when valid.
  • Reading stats — Total reading time (⏱️) and last recorded page appear below the buttons.
  • PDF Control Panel ↗ — Opens the full PDF Control Panel popup for deeper management.
Setting PDF range inline in Editor

Tip

Open a document, keep the PDF visible on the right side, and expand the Priority Editor on the left. You can then set and adjust page ranges for each chapter rem without ever leaving the document view.

Setting PDF range inline in Editor ---

Summary

Feature How
Link chapters to a PDF Add PDF as source to each chapter rem
Quickly propagate sources Copy Rem Sources (Ctrl+Shift+F1) → select chapters → Paste Rem Sources (Alt+Shift+V)
Assign page ranges PDF Control Panel (Command Palette → PDF Control Panel) or inline via the Priority Editor
Read a chapter Queue the chapter — opens PDF Reader at its configured pages
Process notes Add #extractviewer tag to open in ExtractViewer
Multiple PDF sources Tag one with #preferthispdf to designate the primary
See sub-section hierarchy Containment tree in the PDF Control Panel (depth-based indentation)
See chapter coverage Coverage badge (X/Ypp + fill bar) on parent rows in the PDF Control Panel
Record reading position 📖 Position button in Priority Editor, or History button in PDF Control Panel

Troubleshooting: Rem Not Appearing in the PDF Control Panel

Why this happens — an SDK limitation

The RemNote plugin SDK does not expose a query equivalent to "find all rems that have this rem as a source". There is no remsHavingThisAsSource() call the way there is remsReferencingThis() or taggedRem(). This means the plugin has no direct way to enumerate every rem that shares a given PDF source.

How the plugin searches

When you open the PDF Control Panel, getAllIncrementsForPDF discovers rems through three strategies executed in order:

Strategy What it covers Speed
1. Local tree scan Parent rem, all siblings, and descendants up to 3 levels deep — the most common case for chapter rems nested under the same book folder Fast
2. IncRem cache scan All rems currently tagged as Incremental — covers any IncRem anywhere in your KB that already went through the queue Medium
3. Persistent index (known_pdf_rems_*) A synced-storage list of rem IDs explicitly registered as users of this PDF — covers rems discovered in previous sessions or registered via the Copy/Paste commands Fast

The persistent index is updated in the following situations:

  • When a rem is found by strategies 1 or 2 (it gets added to the index automatically)
  • When you run Copy Rem Sources (the template rem is registered immediately for all its PDF sources)
  • When you run Paste Rem Sources (each target rem is registered for each PDF source that was added)

What to do if a rem is still missing

Note

If a rem you assigned the PDF source to does not appear in the PDF Control Panel list, it simply means the plugin has not "seen" it yet through any of the three strategies above.

Try these steps in order:

  1. Open the PDF Control Panel from the missing rem itself. Focus the rem, open the Command Palette, and run PDF Control Panel. The plugin will discover the rem via widget context detection and add it to the persistent index. The next time you open the panel from any other chapter, this rem will appear.

  2. Use Copy & Paste Rem Sources. Even if you already assigned the PDF manually, running Copy Rem Sources (Ctrl+Shift+F1) on the rem and then Paste Rem Sources (Alt+Shift+V) back onto it (i.e., target = itself) will write it into the index.

  3. Tag the rem as Incremental and queue it once. The IncRem cache scan (strategy 2) runs every time the panel opens and covers all rems tagged with #Incremental. Once the rem passes through the queue at least once, it will always be discoverable.

  4. Wait for the next full panel open from another chapter. Strategy 1 (local tree scan) searches siblings and cousins up to 3 levels. If all your chapters share the same parent folder, they will all be found the first time any one of them opens the Control Panel.

User's Manual

Clone this wiki locally