WordScope

WordScope is an Obsidian plugin for counting readable Chinese and English text in the active Markdown note. It presents whole-note counts, common-character statistics, and user-defined term statistics in a right sidebar view.

Features

• Counts the entire active Markdown note.
• Shows total count, Chinese characters, English words, supported punctuation marks, and digit characters.
• Shows matches for seven built-in common Chinese characters: 的, 了, 地, 著, 是, 也, and 而.
• Lets you define custom characters or terms in the plugin settings.
• Opens and closes the statistics view from the binary ribbon icon.
• Provides the 開啟字數統計 command in the command palette.
• Provides a manual refresh button that reads the latest editor content, including unsaved changes.
• Refreshes automatically when you open or switch Markdown notes.

WordScope does not refresh continuously while you edit. Use the refresh button when you want to recalculate the current note. Selected-text counting is not implemented.

Markdown handling

The plugin renders Markdown with Obsidian's MarkdownRenderer and extracts readable text from the rendered result.

It keeps headings, paragraphs, formatted text, link display text, WikiLink display names, quotes, lists, and callout body text. It excludes YAML frontmatter, Markdown syntax, URLs behind links, code blocks, inline code, images, media, embeds, and non-body controls.

All word, common-character, and custom-term statistics use the same extracted readable text.

Counting rules and limitations

• Chinese counting currently recognizes characters in the basic U+4E00–U+9FFF range. Rare extension characters, Japanese kana, and Korean characters are not included in the Chinese count.
• English words use ASCII letters. Apostrophe-connected forms such as don't count as one word; accented letters and other non-ASCII letter forms are not fully supported.
• Digits include ASCII and full-width decimal digits.
• Punctuation counting uses a defined set of common Chinese and English punctuation marks, not every Unicode punctuation character.
• Custom terms are case-sensitive and counted as non-overlapping literal strings.
• Custom terms can be separated by ASCII commas, Chinese commas, or line breaks. Empty and duplicate entries are removed.
• A custom term that duplicates one of the seven built-in common characters is shown only in the common-character section.
• A selected Markdown fragment is not currently available as a statistics mode.

Installation

Community Plugins

After the plugin is published in the Obsidian Community Plugins directory:

1. Open Settings → Community plugins.
2. Select Browse and search for WordScope.
3. Install and enable the plugin.

Manual installation

1. Download main.js, manifest.json, and styles.css from the matching GitHub release.
2. Create <Vault>/.obsidian/plugins/word-count/.
3. Copy the three files into that folder.
4. Reload Obsidian and enable WordScope under Community plugins.

Usage

1. Open a Markdown note.
2. Select the binary icon in the left ribbon, or run WordScope: 開啟字數統計 from the command palette.
3. Select the ribbon icon again to close the statistics view. If the right sidebar is collapsed or another sidebar tab is active, selecting the icon reveals WordScope instead.
4. Use the refresh button in the statistics view after editing a note.

To configure custom terms, open Settings → WordScope, then enter one or more terms separated by commas or line breaks. Settings are stored per vault and shared by all notes in that vault.

Local data and privacy

Note content is processed locally in memory through Obsidian's Markdown rendering APIs. This plugin does not contain telemetry or make explicit network requests. Obsidian itself, remote resources referenced by a note, and Markdown processors registered by other plugins may have their own behavior during rendering.

The only persistent plugin data is the custom-term list, stored in the vault's plugin data through Obsidian's loadData() and saveData() APIs. The plugin does not modify note files.

Compatibility

• Minimum Obsidian version: 1.7.2
• macOS: Tested
• iOS: Tested on iPhone. Plugin installation, sidebar display, note switching, manual refresh, and custom-term settings and statistics were verified.

Automated tests cover counting rules, Markdown source preparation, DOM text extraction, common and custom terms, refresh scheduling, and settings persistence logic. Representative DOM tests do not replace verification against the real Obsidian runtime.

Development

npm test
npm run check
npm run build

The production build creates main.js. A Community Plugins release must attach main.js, manifest.json, and styles.css as individual release assets.

Author

Sapling Works

License

WordScope is licensed under the PolyForm Noncommercial License 1.0.0.

Noncommercial use is permitted under the license terms. Commercial use requires separate permission from Sapling Works.