A secure, read-only web viewer for Obsidian vaults. Browse your notes, kanban boards, task databases, and media from any browser without opening Obsidian.
- Markdown rendering — full CommonMark + Obsidian extensions: wikilinks,
[[embeds]], tags, task lists, strikethrough, fenced code blocks with syntax highlighting - Frontmatter properties panel — all YAML frontmatter fields displayed with wikilink resolution
- Wikilink navigation —
[[Note Name]]and[[Note|Alias]]links resolve to real pages; broken links shown distinctly - Sidebar tree — collapsible folder tree for the full vault; active note highlighted
- Full-text search — instant client-side search across all note titles
- EPUB viewer — built-in reader for
.epubfiles - Attachment serving — images, audio, video, PDFs, and other attachments embedded inline
- Local and remote modes — read directly from the filesystem (
NOTES_MODE=local) or from a CouchDB instance synced via Obsidian LiveSync (NOTES_MODE=remote)
Notes with kanban-plugin: true in their frontmatter are rendered as read-only kanban boards, with columns parsed from ## Heading sections and cards from list items. Checked ([x]) and unchecked ([ ]) states are preserved.
.base database files are parsed and rendered as filterable, sortable tables. Supported features:
- Obsidian filter expression syntax (
file.hasTag(),contains(),and/orconditions, etc.) - Column ordering from the view's
orderfield - Sort by any property, ascending or descending
- Per-view filter merging (global + view-level)
- Field-aware cell rendering:
status,priority,due/scheduleddates,contexts,projects, andtagscolumns all display with visual styling
Individual task notes (.md files created by the TaskNotes plugin) are auto-detected by their frontmatter and rendered as structured task cards instead of plain notes.
Detection — a note is treated as a task if its frontmatter contains any of the following distinctive fields, or contains status paired with at least one task-related field:
| Distinctive (any one triggers) | Paired with status |
|---|---|
timeEntries, timeEstimate, recurrence, complete_instances | due, scheduled, priority, contexts, projects, blockedBy, completedDate |
Task card — rendered with:
- Status badge — colour-coded pill (blue = open, yellow = in-progress, green = done, muted = cancelled, purple = waiting/blocked)
- Priority badge — ⚡ urgent · ↑ high · → medium · ↓ low, each in its own colour
- Metadata rows — due date, scheduled date, contexts (as
#tagchips), projects (as resolved wikilinks), time estimate (auto-formatted from minutes), recurrence, blocked-by, completed date, time logged (summed fromtimeEntriesstart/end timestamps) - Tags — frontmatter tags rendered as chips
- Additional properties — any extra frontmatter fields not listed above, with wikilink resolution
- Note body — the markdown content below the frontmatter, rendered normally
Overdue due/scheduled dates are highlighted in red with a ⚠ indicator when the task is not yet done or cancelled.
.base files with type: tasknotesKanban are rendered as a full kanban board instead of a table:
- Columns are grouped by
groupBy.property(typicallystatus) and sorted alphabetically — matching Obsidian's board behaviour - Each card shows: a status circle indicator, a priority dot, the task title (linked, with strikethrough for done/cancelled), and configured metadata rows (dates with overdue callout,
@contextchips,#tagchips, project links) - Column headers show the group value with its status accent colour and a task count
Drawing files created by the Obsidian Excalidraw plugin are rendered as fully interactive, read-only vector drawings using the Excalidraw library (loaded from CDN at runtime). Both standalone .excalidraw files and Obsidian's double-extension .excalidraw.md wrapper format are supported, including LZ-string compressed drawing data.
- Full-page viewer — navigating to a drawing opens a dedicated full-canvas viewer; the drawing is automatically fitted to the viewport on load
- Inline embeds —
![[drawing.excalidraw]]in a markdown note renders the drawing as an embedded iframe panel, matching the style of other embeds - Download — the original
.excalidrawfile can be downloaded from the toolbar
Zoom & pan controls:
| Control | Action |
|---|---|
| Scroll wheel | Pan canvas |
| Ctrl + scroll | Zoom in / out |
| Left-click drag | Pan canvas |
| Middle-click drag | Pan canvas |
+ / - keys | Zoom in / out |
0 key | Reset zoom to 100% |
Shift + 1 | Fit drawing to screen |
| ⊡ Fit button | Fit drawing to screen |
− / + toolbar buttons | Step zoom out / in |
A ? button in the toolbar shows the full shortcut reference at any time.
Note: The Excalidraw viewer requires an internet connection on first load to fetch React and the Excalidraw library from
esm.sh. Subsequent renders are cached by the browser.
.base files with type: tasknotesCalendar are rendered as an interactive monthly calendar:
- Filtered tasks are placed on their
duedate (solid chip) and/orscheduleddate (outlined chip), respecting the view'sshowDueandshowScheduledoptions - Task chips are colour-coded by status and link directly to the task note
- Done/cancelled tasks are shown faded with strikethrough
- Today is highlighted with a coloured border and circled day number
- Past days are dimmed
- Prev / Next / Today buttons navigate months instantly in the browser — no page reload
firstDayoption (0 = Sunday, 1 = Monday) is respected from the view config
- Password authentication with brute-force protection (10 failed attempts → 15-minute lockout)
- HMAC constant-time password comparison to prevent timing attacks
- Strict Content Security Policy,
X-Frame-Options: SAMEORIGIN,X-Content-Type-Options, and other hardening headers - Session cookies:
HttpOnly,SameSite=Lax, optionallySecure(setVAULT_HTTPS=true) - Configurable session lifetime (default 7 days)
git clone <repo>cd VaultView
python -m venv venv &&source venv/bin/activate
pip install -r requirements.txt
cp example.env .env
# Edit .env: set VAULT_USERNAME, VAULT_PASSWORD, and VAULT_PATH
python app.py /path/to/your/vaultOpen http://localhost:5000.
git clone <repo>cd VaultView
cp example.env .env
# Edit .env: set VAULT_USERNAME, VAULT_PASSWORD, FLASK_SECRET_KEY, and VAULT_PATH
docker compose up -dOpen http://localhost:5000.
To use remote / LiveSync mode with CouchDB, swap the active service in docker-compose.yml (see the comments inside the file) and set the COUCHDB_* variables in your .env.
All configuration is via environment variables (or a .env file — copy example.env to get started).
| Variable | Required | Default | Description |
|---|---|---|---|
VAULT_USERNAME | Yes | — | Login username |
VAULT_PASSWORD | Yes | — | Login password |
FLASK_SECRET_KEY | No | random | Secret for session signing — set this to keep sessions across restarts |
NOTES_MODE | No | local | local or remote (CouchDB) |
VAULT_PATH | No | . | Path to vault directory (local mode) |
COUCHDB_URL | No | http://127.0.0.1:5984 | CouchDB URL (remote mode) |
COUCHDB_DB | No | obsidian | CouchDB database name (remote mode) |
COUCHDB_USER | No | — | CouchDB username (remote mode) |
COUCHDB_PASSWORD | No | — | CouchDB password (remote mode) |
VAULT_HTTPS | No | false | Set true to enable the Secure cookie flag when behind HTTPS |
VAULT_SESSION_DAYS | No | 7 | Session lifetime in days |
PORT | No | 5000 | Host port to expose (Docker Compose only) |
python app.py [vault_path] [--title "My Notes"] [--host 0.0.0.0] [--port 5000]
| Extension | Rendered as |
|---|---|
.md | Markdown note, TaskNotes card, or Kanban board |
.base | Database table, TaskNotes Kanban board, or TaskNotes Calendar |
.epub | Built-in EPUB reader |
.excalidraw | Interactive read-only Excalidraw drawing viewer |
| Images, video, audio | Inline embed |
| PDF, Office docs, archives | Download / pass-through |
| Package | Purpose |
|---|---|
flask | Web framework |
gunicorn | Production WSGI server |
markdown | Markdown rendering |
python-frontmatter | YAML frontmatter parsing |
pyyaml | .base file parsing |
pymdown-extensions | Task lists, strikethrough, fenced code (recommended) |
python-dotenv | .env file loading (recommended) |