#17 Can I Link a Local Folder?
Yes — and it's powerful. Link a project directory and PenPage becomes a live editor for your entire folder tree. Sub-folders, nested files, AI agent configs — everything syncs both ways, automatically.
Two ways to link
- Any folder — right-click a folder → Link Directory to connect it to a folder on disk.
- Directory workspace (🗂️) — a whole workspace dedicated to local and network folders, kept separate from your other notes. (#6 Workspaces)
Both use the same two-way sync described below.
Link an entire directory tree
File Link doesn't just connect one file — it connects an entire directory, including sub-folders up to 4 levels deep. Every .md file becomes a PenPage page. Every sub-directory becomes a nested PenPage folder.
- Click the link icon on a folder (or right-click → Link Directory)
- Select a directory from your computer
- PenPage scans the tree and shows a sub-directory picker — choose which sub-folders to include
- Done — your directory tree is now live in PenPage
One link, your whole AI project
This is where it gets exciting. Link your project root and PenPage automatically discovers all the .md files your AI tools use:
| AI Tool | What PenPage picks up |
|---|---|
| Claude Code | CLAUDE.md, .claude/agents/, .claude/rules/, .claude/plans/ |
| Gemini CLI | GEMINI.md and related config |
| Codex CLI | AGENTS.md and agent definitions |
One link → agents, rules, plans, skills, prompts — all editable in PenPage's rich editor. AI reads your changes instantly. No copy-paste, no switching windows.
See #16 AI Coding Agent for the full edit-run-sync workflow.
Two-way sync
Every change syncs bidirectionally — PenPage to disk, disk to PenPage.
| Event | What happens |
|---|---|
| Edit a page in PenPage | File on disk updates automatically |
| Edit a file on disk | PenPage picks up the change on next sync |
| Both sides changed | Auto-fork — creates two versions, no data lost |
| File deleted on disk | Page moved to Trash |
| Page deleted in PenPage | .md file removed from disk |
When does sync happen?
- Page switch: current page syncs immediately
- Tab focus: switch back to PenPage → all linked folders rescan
- Background: periodic rescan every 60 seconds
- Manual: right-click folder → Sync Directory
Conflict? PenPage never overwrites either side. If both changed, it creates two versions — you decide which to keep.
AI project mode: When PenPage detects a .penpage directory, file changes always win in conflicts — so your AI tool's output is never overwritten by a stale PenPage copy.
Link Update — discover new sub-folders
Added new directories to your project after linking? Right-click the linked folder → Link Update. PenPage scans for new sub-directories and offers to link them — no need to unlink and re-link.
Unlink
Want to disconnect? Right-click the folder → Unlink Directory.
- Pages stay in PenPage — nothing is deleted
- Files on disk are untouched
- Only the live sync connection is removed
- You can re-link the same directory anytime
Smart deduplication
PenPage uses content hashing to prevent duplicates:
- Linking a directory that overlaps with existing pages? Duplicates are detected and skipped
- Rescanning finds and cleans up duplicate
.mdfiles automatically - Empty
.mdfiles (from pages you never edited) are auto-removed
Browser requirements
File Link requires the File System Access API:
| Browser | Support |
|---|---|
| Chrome / Edge (desktop) | Full support — recommended |
| Safari / Firefox | Not available |
| Mobile browsers | Not available |
Your browser remembers which directories you've granted access to. After restarting, PenPage checks permissions silently — no re-grant dialog in most cases.
If you just want to take notes...
File Link is designed for power users and developers. If you're just writing notes:
- PenPage's built-in storage is simpler and faster
- For cross-device access, use Cloud Sync (#12)
- For backup, use the one-click Save/Restore (#7)
Supported file types
.md and .markdown only. Hidden files (starting with .) are skipped.