5.4 KiB

Raw Blame History

📊 Note Statistics Plugin

Version: 1.0.0
Status: Enabled by default
File: plugins/note_stats.py

What It Does

Calculates and displays comprehensive statistics for every note, including word count, reading time, character count, line count, links, images, code blocks, tasks, and more. Stats appear in the bottom of the UI.

Requirements

No additional dependencies required. Uses built-in Python libraries only.

Installation

Already enabled by default! No configuration needed.

To Disable/Enable via API

Disable:

curl -X POST http://localhost:8000/api/plugins/note_stats/toggle \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Enable:

curl -X POST http://localhost:8000/api/plugins/note_stats/toggle \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Statistics Provided

📝 Content Metrics

Words - Total word count
Characters - With and without spaces
Lines - Total lines in the note
Paragraphs - Number of paragraphs
Sentences - Estimated sentence count

⏱️ Reading Time

Calculated at 200 words per minute
Displayed in minutes

🔗 Links & References

Total Links - All links (markdown + wikilinks)
Internal Links - Links to other notes (.md files and wikilinks)
External Links - HTTP/HTTPS URLs
Wikilinks - [[note]] and [[note|display]] count
Images - ![alt](image.png) count

💻 Code Blocks

Inline Code - `code` count
Code Blocks - ```language ` blocks
Languages Used - List of detected languages

✅ Tasks

Total Tasks - All - [ ] and - [x] items
Completed - - [x] checked tasks
Pending - - [ ] unchecked tasks
Progress - Percentage complete

📑 Structure

Headings - H1, H2, H3 counts
Lists - Bullet and numbered lists
Blockquotes - > quote blocks
Tables - Markdown table count

How It Works

Client-Side Calculation

Statistics are calculated in real-time in your browser as you type, providing instant feedback without server roundtrips.

On Save (Hook: `on_note_save`)

When a note is saved, the plugin:

Parses the markdown content
Calculates all statistics
Logs key metrics to Docker logs (for monitoring)

Hooks Used

on_note_save - Logs stats to Docker after save

Viewing Statistics

In the UI

Open any note
Look at the bottom of the screen
Click to expand/collapse the stats panel
Statistics update in real-time as you type

In Server Logs

# Docker (any host OS)
docker-compose logs -f | grep "note_stats"

# Running locally (Linux / macOS)
python run.py 2>&1 | grep "note_stats"

# Running locally (Windows / PowerShell)
python run.py 2>&1 | findstr "note_stats"

Example output (single line, prefixed with uvicorn's INFO:):

INFO:     note_stats projects/website.md | 1,234 words | 6 sentences | ~6m read | 89 lines | 15 links (5 internal) | 8/12 tasks

Optional sections (lists, tables, links, tasks) only appear when their count is non-zero.

Configuration

No configuration needed. The plugin works out of the box.

Customization (Optional)

To change the reading-speed assumption used for reading_time_minutes, edit the constant near the top of note_stats.py:

WORDS_PER_MINUTE = 200  # Change to your average reading speed

Architecture

Client-Side (Frontend)

Statistics are calculated in JavaScript (app.js)
Updates in real-time as you type
No API calls required for stats display
Instant feedback, zero latency

Server-Side (Backend)

Plugin logs stats to Docker when notes are saved
Uses on_note_save hook
Provides monitoring and tracking
No API endpoints needed

Use Cases

📝 Writing Goals

Track word count to meet daily writing targets.

⏱️ Content Planning

Estimate reading time for blog posts or documentation.

✅ Task Management

Monitor task completion progress across notes.

📊 Content Analysis

Understand structure and complexity of notes.

🔗 Link Auditing

Find orphaned notes or track reference density.

Troubleshooting

Issue: Stats not showing in UI

Check: Is plugin enabled? curl http://localhost:8000/api/plugins
Check: Hard refresh browser (Ctrl+Shift+R)
Fix: Save the note again to recalculate stats

Issue: Wrong statistics

Cause: Complex markdown formatting
Fix: Plugin uses regex parsing - very complex markdown may vary
Note: Statistics are estimates, not exact counts

Issue: Performance on large notes

Note: Plugin is optimized for notes <100KB
For large files: Stats calculation may take a moment on first save

Technical Details

Calculation Methods

Words: Split on whitespace, excluding code blocks
Reading Time: words / 200 minutes
Links: Regex match [text](url) markdown links + [[wikilinks]]
Wikilinks: Regex match [[target]] and [[target|display]] (Obsidian-style)
Tasks: Match - [ ] and - [x]
Code Blocks: Match ```language fences **Headings:** Match#, ##, ###` at line start

Performance

Client-side calculation - Zero latency, no server roundtrips
Real-time updates - As you type, stats refresh instantly
Lightweight - Typical calculation: <10ms
No caching needed - Calculated on-demand in browser

5.4 KiB Raw Blame History