# PDF To Notes > Transform a PDF book into GoodNotes-style handwritten study notes with strategic chunking, memory-retention techniques, and real-world applications. Optimized for large texts with ADHD-friendly features. Use when: converting book to notes; creating handwritten study materials; breaking down dense textbooks; "make notes from this PDF"; "create study notes from book"; "organize book into notes". - Skill: `arn-nj/pdf-to-notes` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds@latest add arn-nj/pdf-to-notes` - Raw SKILL.md: https://api.skillmd.com/api/skills/arn-nj/pdf-to-notes/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: arn-nj (https://skillmd.com/u/arn-nj) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/arn-nj/pdf-to-notes --- # PDF Book → GoodNotes Handwritten Study Notes ## What This Skill Does Given a PDF book or large text, produce: 1. **`_source_normalized.txt`** — normalized text extraction used as the semantic source of truth 2. **`_concept_inventory.json`** — semantic concept inventory extracted from the PDF/book + chapter map 3. **`_visual_briefs.json`** — mandatory per-chapter semantic visual briefs used by the Art Director phase before any sketch is drawn 4. **`_Flashcards.csv`** — mandatory active-recall export with header `Front, Back, Tags` 4. **`_GoodNotes_detailed.md`** — ADHD-friendly handwritten study notes, chunked by chapter/section or micro-section when needed 5. **`_GoodNotes_detailed_A4.pdf`** — A4 PDF for GoodNotes import 6. **`_book_mindmap_clean.mm`** — semantic Freemind mindmap 7. **`_book_mindmap_fixed.xmind`** — semantic XMind mindmap (concept-enriched) 8. **`_narrative_manifest.json`** — semantic narrative manifest for v2 deck generation 9. **`_pitch_deck.html`** — mandatory v2 cinematic Reveal.js deck generated from the narrative manifest 10. **`_Teleprompter_Script_.md`** — teleprompter script generated by `xmind-notes-to-deck-v2` 11. **`assets/` folder** — Excalidraw source scenes (`.excalidraw`) plus compiled PNG sketches for key concepts 12. **`assets/INDEX.md`** — Visual reference guide with sketch metadata 13. **`_INDEX.md`** — Master topic index with all pages and key concepts 14. **`_AI_Elaboration.json` or `_AI_Elaboration.md`** — optional external AI synthesis for page-level elaboration used by the XMind enrichment step All outputs go into a `/` subfolder. ## Systemic Execution Contract ### Execution Modes - `--standard`: output clean, hierarchical, engineering-focused outlines that map the exact technical architecture. - `--adhd`: prohibit introductory summaries, conversational text, and sections titled `Intro`; require immediate visual memory hooks (ASCII tables/diagrams), bold technical syntax anchors, and real-world-use-first ordering. Also exclude sections named `Header`, `Active Recall Prompts`, and `One-Page Revision` from notebook pages. ### Balanced Stack Multi-Model Orchestration Pipeline Every run must execute this strict routed backend architecture: 1. Phase 1 (Ingestion and Bulk Extraction): - Route raw PDF/book input to a primary mid-tier extractor model (for example GPT-5.4 or another 1M+ context model). - Perform comprehensive fact extraction and archetype classification before formatting. 2. Phase 2 (Markdown and Schema Formatting): - Route the extracted conceptual payload to a strict coding/schema model (for example Claude Sonnet 4.6). - This phase is solely responsible for GoodNotes markdown formatting, PNG orchestration, and flawless XML serialization for XMind. 3. Phase 3 (AI Elaboration and Lateral Analysis): - Fork clean conceptual outputs to an advanced reasoning model (for example GPT-5 or equivalent). - Generate `_AI_Elaboration.json` by extrapolating edge cases and downstream implications without hallucination or source-text repetition. ### Dynamic Content Archetype Classification Classify each chapter/section into one archetype before generating markdown pages or mindmap nodes. Use only the associated mandatory node set. - Type A: Conceptual Architecture or Frameworks - `Core Architecture Blueprint` - `Core Components & Governance` - `Key Integration Points` - `Systemic Trade-offs` - Type B: Procedural Workflows or Pipelines - `Execution Pipeline / Steps` - `Environment Prerequisites & Setup` - `Failure Recovery & Verification` - `Performance Optimizations` - Type C: Discrete Technical Components or Tools - `Functional Mechanics` - `Concrete Configuration & Code Snippets` - `Edge Cases & System Constraints` ## ADHD-Friendly Handwritten GoodNotes Design ### ✓ What's Included for ADHD Brains - **Micro-chunking**: 3–5 min read per page (prevents hyperfocus derailment + working memory overload) - **Handwritten aesthetic**: Warm, friendly fonts that feel personal and engaging - **Sepia paper background**: Warm aged-paper tone with handwritten fonts for authentic GoodNotes feel - **Frequent visual breaks**: Icons, ASCII diagrams, color-coded sections prevent text fatigue - **Index-first navigation**: a dedicated notebook index page reduces search friction and supports non-linear study - **Progressive challenge ordering**: foundational pages appear before advanced pages without adding metadata headers to every page - **Progress checkboxes**: ✓ dopamine hits after each micro-section (engagement + completion feedback) - **Action-first approach**: "Try This Right Now" before abstract explanation (executive scaffolding) - **Quick facts**: Flashcard Q&A format forces active retrieval (combat working memory limits) - **Real-world examples first**: Concrete scenarios before theory (interest-dependent attention) - **Hyperlinks + anchor navigation**: Jump to topics non-linearly (supports scattered attention patterns) - **Emoji + icons**: Visual cues for quick section identification (supports ADHD scanning) - **Whitespace heavy**: Breathing room between concepts (reduces cognitive load) ### ✗ What's Avoided - Long paragraphs (max 2–3 sentences per bullet) - Abstract language without concrete examples - Dense, wall-of-text sections that trigger avoidance - Vague or open-ended learning goals - Passive voice or hedging language ("might", "could") - More than 1 idea per bullet point - Review schedules that require memory ("study sometime next week") ## Procedure ### Mandatory Checkpoint Protocol (Fail-Fast) Apply this protocol after each procedure step. Do not continue when a checkpoint fails. Checkpoint format (required): - `CHECKPOINT : PASS - ` - `CHECKPOINT : FAIL - ` Fail-fast rule (required): - If any checkpoint is `FAIL`, stop immediately. - Do not proceed to the next step. - Do not attempt downstream regeneration until the failed step is fixed and re-validated. Checkpoint map: - `P` before Step 1: workflow plan exists and is approved before any generation starts. - `A` after Step 1: chapter inventory must be present and non-empty. - `B` after Step 2 preflight: each chapter/section must include mechanism, archetype, analogy, label-fusion intent, and composition intent. - `C` after Step 2 generation: visuals must not be template clones across chapters. - `D` after Step 2 validation: PNG count must be >= chapter count and all PNGs must pass integrity checks. - `E` after Step 3: notes must be non-empty, page count >= chapter count, and required sections must be present. - `F` after Step 4: `.mm` must parse and Level 1 chapter nodes must be >= chapter count. - `G` after Step 5: `.xmind` must exist and be valid. - `H` after Step 6.6: flashcards CSV header and minimum chapter coverage rules must pass. - `I` after Step 7: index TOC row count must be >= page count minus the notebook index page. - `J` after Step 8: PDF must exist and be non-trivial. - `K` final: all checkpoints must be PASS. ### Step 0 — Plan the Workflow Before Running Create a short execution plan before any generation step runs. Plan requirements: - Include `Inputs`, `Outputs`, `Dependencies`, and `Execution order`. - Include a per-step `checkpoint expectation`. - Include `rollback/retry strategy` for the first failed checkpoint. - Record the plan in `/checkpoints/workflow-plan.md`. Checkpoint `P`: - PASS when `workflow-plan.md` exists and covers all procedure steps with checkpoint criteria. - FAIL when planning is missing, incomplete, or execution starts before plan approval. ### Step 1 — Read and Normalize the PDF/Book Source - Extract the text from the PDF/book excerpt in full. - Identify chapter, part, or major section boundaries. - Note the document title, module structure, and key themes. - Flag dense chapters that should be split into multiple micro-pages. - Build an explicit lesson inventory table: `Section`, `Chapter`, `Order`. - Write the normalized extraction to `_source_normalized.txt`. Coverage requirement: - Use the chapter inventory as the source of truth for page counts, mindmap Level 1 nodes, flashcards, and PNG counts. Checkpoint `A`: - PASS when the chapter inventory exists and contains at least 1 detected chapter/major section. - FAIL when boundaries are missing/ambiguous and inventory is empty. ### Step 1.5 — Generate Semantic Chapter Briefs Before Any Sketching Create `_visual_briefs.json` from the extracted book text + chapter inventory. This is the mandatory semantic bridge between source ingestion and image generation. Do **not** jump directly from chapter headings into sketch rendering. Every chapter brief must include: - `chapterTitle` - `chapterSlug` - `archetype` - `coreMechanism` - `what` - `how` - `why` - `realWorldAnchor` - `mentalModel` - `edgeCase` - `primaryEntities` - `primaryFlow` - `mainConstraint` - `tradeoff` - `physicalAnalogy` - `labelFusion` - `compositionIntent` - `hotPath` - `secondaryPaths` - `mustShow` - `mustNotShow` - `visualSceneType` - `sceneObjects` - `objectToConceptMap` - `spatialLayout` - `entryPoint` - `exitPoint` - `failureBranch` - `comparisonAxis` - `evidenceArtifact` - `dominantMotion` - `forbiddenTemplate` - `objectPalette` - `shapeQuota` - `forbiddenGeometry` - `labelBudget` - `sceneTest` - `silhouettePlan` - `propDensity` - `asymmetryPlan` - `antiCardFraming` - `sceneTexture` - `premiumSceneTest` - `diagramIntent` - `formalFramework` - `sceneFamilyCandidates` - `selectedSceneFamily` - `selectionReason` - `formalCompanionSuggested` - `salienceGoal` - `silhouetteContrastRules` - `propInventory` - `textureInventory` Hard rule: - Full final notes are not required yet. - Strong semantic understanding is required before image generation. - If a chapter cannot produce a strong visual brief, stop and deepen extraction before sketching. - A title plus generic `what/how/why` summary is not enough; the brief must drive geometry, motion, object choice, visual salience, and scene-object diversity. - Resolve `diagramIntent`, `formalFramework`, `sceneFamilyCandidates`, `selectedSceneFamily`, and `selectionReason` before finalizing `visualSceneType`. - Prefer selecting `visualSceneType` and `objectPalette` from `content-to-sketch/references/canonical-scene-families.md` before inventing a new scene family. - For final learner-facing visuals, also apply `content-to-sketch/references/premium-sketch-language.md` so the brief carries silhouette, prop-density, asymmetry, anti-card-framing, and scene-texture intent. - When premium visuals are requested, structure the downstream render around `content-to-sketch/references/premium-generation-playbook.md` rather than jumping straight from brief text to final layout. - If the concept clearly maps to a formal framework (for example C4, BPMN, sequence, state, Wardley, or service blueprint), record that choice even if the final output will be a semantic sketch. - The final learner-facing image must not expose planning metadata such as scene names, mechanism lines, analogy lines, or must-show rules. Checkpoint `B`: - PASS only when every chapter has a complete semantic visual brief with mechanism, analogy, composition, and hot-path detail. - FAIL when briefs are shallow, title-only, or generic. ### Step 2 — Generate PNG Sketches (invoke content-to-sketch skill) **This step MUST run before notes, mindmap, or XMind generation.** PNG filenames produced here are embedded directly into notes, `.mm`, `.xmind`, and the narrative manifest. **Invoke the `content-to-sketch` skill** — do not reimplement its pipeline here. The skill owns: - Art Director metaphor extraction preflight - Excalidraw JSON generation with required style contract - Headless compilation via `scripts/compile-excalidraw.js` → `.png` - All validation gates **Brief to pass to content-to-sketch for each chapter:** - Input: the corresponding object from `_visual_briefs.json` — not just the chapter title - Output target: `/assets/_chapter_.png` - Minimum: 1 PNG per chapter - Archetype selection must be justified by the semantic visual brief and confirmed by the Art Director phase - The brief must explicitly carry the chapter mechanism, analogy, label-fusion plan, composition intent, hot path, main constraint, scene objects, scene type, object palette, shape quota, forbidden geometry, label budget, scene test, silhouette plan, prop density, asymmetry plan, anti-card-framing plan, scene texture, premium scene test, diagram intent, formal framework, scene-family candidates, selected scene family, selection reason, formal companion suggestion, salience goal, silhouette contrast rules, prop inventory, and texture inventory **After the skill completes:** 1. Confirm `assets/` folder exists with one `.excalidraw` and one `.png` per chapter. 2. Validate all PNGs with Pillow. 3. Run structural QA on `.excalidraw` sources (text containment + arrow hygiene): ```bash node /skills/content-to-sketch/scripts/validate-excalidraw-quality.js \ --dir "/assets" \ --report "/assets/validation_report.txt" ``` 4. Record the confirmed filename list — used verbatim in Steps 3, 4, 5, and 5.4. 5. `assets/INDEX.md` is created by the skill. Flow integrity rule: - Do not directly patch generated diagram files as the primary fix path. - If visuals are weak or generic, re-run `content-to-sketch` with improved semantic chapter briefs. - Treat direct, one-off diagram edits as exceptions only after the skill pipeline passes all gates. - If a sketch could plausibly fit any random chapter with only label changes, treat that as a semantic failure and regenerate. Checkpoints `C`, `D`: - `C` PASS only when chapter visuals are not near-identical templates and visibly encode the chapter mechanism/analogy through scene-specific geometry, motion, object mapping, hot-path salience, clean connector routing, non-box object diversity, and premium sketch-language cues where required. - `C` also requires structural QA with zero text-overflow errors and zero critical arrow endpoint-inside-node errors in `assets/validation_report.txt`. - `D` PASS only when every required PNG exists and integrity validation passes. ### Step 3 — Generate ADHD-Friendly GoodNotes Notebook See [handwritten-notebook-format-adhd](./references/handwritten-notebook-format-adhd.md). The notebook must begin with a dedicated index page, then continue with chapter pages. If a chapter is dense, split it into 2-3 micro-pages. Use the same notebook structure contract as `transcript-to-notes`, adapted for chapters. Required page sections: - `## Real-World Anchor` - `## What You'll Learn` - `## Deep Dive Explanation` - `## Mental Model / Analogy` - `## Visual Summary` - `## Visual Sketch` - `## Real-World Use First` - `## Process Flow / Steps` - `## Key Concepts` - `## Try This Right Now` Formatting rules mirror `transcript-to-notes`: - Keep bullets short and concrete. - Put the real-world example before deeper explanation. - Prefer one idea per bullet. - Ensure every Level 1 and Level 2 concept passes the Triad Test (What, How, Why). - Do not create sections titled `Intro`, `Introduction`, `Core Idea`, `Quick Facts`, or `Common Mistakes`. - In `--adhd` mode, every page must start with an immediate visual memory hook. - **Embed the real PNG path from assets/ — never write a placeholder.** - In `--adhd` mode, do not include sections named `Header`, `Active Recall Prompts`, or `One-Page Revision`. - Export all cards directly into `_Flashcards.csv` from page content anchors. Checkpoint `E`: - PASS only when notes are non-empty, include required sections, and pages >= detected chapter count. - FAIL if notes are placeholder-only or under-covered. ### Step 4 — Create Freemind Mindmap (`.mm`) See [mindmap format reference](./references/mindmap-format.md). Build a hierarchical XML Freemind file: - Root node: book title - Level 1: page/chapter titles - Level 2: use only the mandatory node set for the assigned archetype - Level 3+: elaborative subnodes from page content Archetype requirements match `transcript-to-notes` exactly. Do not include Flashcards as mindmap nodes. Never include nodes titled or themed as Flashcards, Q/A, Questions & Answers, Interesting Talking Points, Pitfalls & Clarifications, Narrative Flow, In This Section, or What You'll Learn. Never include instructional/meta coaching text as node content. Do not add `One-Page Revision` nodes. Make Level 3+ child nodes complete, context-rich phrases. **Critical**: escape ALL `&` as `&` in node TEXT attributes. Checkpoint `F`: - PASS only when `.mm` parses and Level 1 chapter nodes >= chapter count. - FAIL on XML parse errors or coverage mismatch. ### Step 5 — Convert .mm → .xmind Run the converter script (uses Python venv): ```bash source .venv/bin/activate python scripts/generate_valid_xmind.py /.mm /.xmind /_GoodNotes_detailed.md ``` Checkpoint `G`: - PASS only when `.xmind` opens as a valid archive and conversion succeeds. - FAIL on conversion error or invalid package. ### Step 5.4 — Build Narrative Manifest for V2 Create `/_narrative_manifest.json` from: - the final notes markdown - the finalized `.xmind` blueprint - generated PNGs in `/assets/` Use the shared extraction prompt template and JSON skeleton from `xmind-notes-to-deck-v2`. ### Step 5.5 — Generate Pitch Deck (V2 Only) After `.xmind` is produced and narrative manifest JSON is available, use v2 only. Required (v2 manifest-first, mandatory invocation of `xmind-notes-to-deck-v2`): ```bash cd skills/xmind-notes-to-deck-v2 npm run build npm run deck -- \ --input "/_narrative_manifest.json" \ --out "/_pitch_deck.html" \ --script-out "/_Teleprompter_Script.md" ``` Hard rule: - `pdf-to-notes` must invoke `xmind-notes-to-deck-v2`; manifest generation alone is not considered complete. - No fallback deck workflow is allowed. - If v2 prerequisites, deck HTML, or teleprompter script are missing, fail the run. ### Step 6 — PNG Generation Reference (Delegated) PNG generation is fully delegated to `content-to-sketch` in Step 2. ### Step 6.5 — Generate External AI Elaboration Artifact Create a separate AI synthesis file when you want richer XMind elaboration that is not limited to the notebook markdown text. Recommended format: - **JSON**: `_AI_Elaboration.json` - **Markdown**: `_AI_Elaboration.md` Rules mirror `transcript-to-notes`. ### Step 6.6 — Extract Flashcards CSV (Mandatory) Create a CSV file named `_Flashcards.csv` semantically from extracted book content + concept inventory + mindmap relationships. Generation method and rules: - Use the chapter inventory + mindmap concept graph to draft active-recall cards directly. - Keep generation independent of notebook formatting sections. - Exact header must be `Front, Back, Tags`. - Add `section:` and `chapter:` tags. - Hard fail if any parsed chapter has fewer than 3 cards. Checkpoint `H`: - PASS only when CSV header is exact and per-chapter minimum card rules pass. - FAIL on header mismatch or weak coverage. ### Step 7 — Generate Topic Index Create `_INDEX.md` inside the book folder. Structure: - title - table of contents with one row per note page after the notebook index page - All Key Concepts (A–Z) - Flashcard export summary - Quick-Find by Topic Checkpoint `I`: - PASS only when index TOC rows >= content page count. - FAIL when index is incomplete. ### Step 8 — Export A4 PDF ```bash source .venv/bin/activate python scripts/md_to_pdf_a4.py /.md /.pdf ``` Checkpoint `J`: - PASS only when PDF generation succeeds and output is non-empty. - FAIL on blank/near-empty output. ### Step 9 — Move Files Into Book Folder Ensure all outputs are inside `/` and scripts remain in `scripts/`. ## Python Environment - Virtualenv: `.venv` at workspace root - Required packages: `reportlab`, `markdown`, `xmind-sdk`, `svglib`, `pypdf` - Install once: `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt` - Use the venv Python at `.venv/bin/python` — **not** the system Python ## Quality Checklist - [ ] Step 2 (PNG) runs before Step 3 (notes) - [ ] Every chapter has at least one compiled PNG in `assets/` - [ ] PNG paths embedded in notes, `.mm`, `.xmind`, and narrative manifest visuals[] all resolve to real files - [ ] Notebook begins with a dedicated index page before chapter pages - [ ] No per-page time/difficulty metadata header is emitted - [ ] Every content page has: Real-World Anchor, What You'll Learn, Deep Dive Explanation, Mental Model / Analogy, Visual Summary - [ ] `_INDEX.md` exists in the book folder - [ ] `_Flashcards.csv` exists with exact header `Front, Back, Tags` - [ ] `_pitch_deck.html` exists - [ ] teleprompter script exists for the generated deck ### PNG Sketch Quality (content-to-sketch integration) - [ ] PNG count is explicit or derived from topic count - [ ] Every topic/chapter has at least one PNG - [ ] All PNGs in `assets/` with `INDEX.md` - [ ] All PNGs pass structural image validation - [ ] Each sketch has 15+ text labels - [ ] Text labels stay inside intended containers (no overflow errors) - [ ] Arrow endpoints attach to shape edges (no endpoint-inside-node errors) - [ ] validation_report.txt shows 0 errors (warnings should be reviewed and reduced) ## Completion and Validation Gate Do not mark any run successful until all gates pass: 1. All generated PNG files pass strict image integrity checking. 2. All bare ampersands in `.mm` are escaped to `&`. 3. Semantic Depth Quality Gate passes for all Level 1 and Level 2 concepts. 4. `_Flashcards.csv` is present with valid header and import-safe escaping. 5. Notes page count is greater than or equal to detected chapter count. 6. Mindmap Level 1 chapter nodes are greater than or equal to detected chapter count. 7. PNG count is greater than or equal to detected chapter count. 8. `_pitch_deck.html` exists and is generated via `xmind-notes-to-deck-v2`. 9. A teleprompter script exists for the generated deck. 10. Checkpoints `P` through `J` are all PASS. 11. Final checkpoint `K` is PASS. ## Related Skills - **content-to-sketch** — Generates the PNG sketches (auto-invoked in Step 2) - **transcript-to-notes** — Source of the canonical end-to-end step contract - **md-to-notes** — Alternative for markdown input