Chinese Comprehensible Input

Desktop — reading view	Mobile — word lookup

The same note rendered for reading. A runnable demo lives at resources/example.md.

Turn any Chinese note in Obsidian into a learner-friendly comprehensible-input reading environment. Dictionary-aware tokenization, exposure tracking, SRS, and optional OpenAI-compatible AI story generation. Works on desktop and mobile (no Node/Electron at runtime).

Tour the interface

A quick visual walkthrough. The green numbers on each screenshot map to the lists below; deeper explanations live in docs/.

Reading toolbar (desktop)

• 1 · Edit — toggle between read and edit (type Chinese with annotations off).
• 2 · Known, 3 · Unknown, 4 · Partial — tap a word to set its status.
• 5 · Add custom word — tap characters to build a dictionary entry.
• 6 · Highlighter — arm tap-to-format mode (see Formatting).
• 7 · Lightbulb — tap the first and the last word of a phrase, then Explain it, Proof read it or Simplify it (needs AI; see Explain).
• 8 · Status / HSK — one button that shows how words are coloured (by learning status or by HSK level); tap it to switch to the other.
• 9 · More — the display menu (below).
• 10 · Note status bar — Known / Partial / Unknown / New %, top HSK; tap for full stats.

These toolbar images are rendered from the plugin's own code and stylesheet on Obsidian's default light theme (node scripts/render-screenshots.mjs), so they are regenerated rather than re-captured when the interface changes.

Display menu (the "More" button)

• 1 · Script — Automatic, Traditional, or Simplified, without leaving the note.
• 2 · Show / hide colors — per-status (or per-HSK) tint toggles.
• 3 · Display mode — 2-line, 3-line, or None. What goes on each row is yours to choose — see Display modes.
• 4 · Known-word popups — allow tapping words you already know.
• 5 · Font size, Line spacing, Annotation size — reader sizing, adjustable while you read.
• 6 · Stats, Generate story, Mnemonics for this note… — open vocabulary stats / AI story generation / fill in, regenerate or remove the mnemonics of the note's words.

Colors & the 1–3 line stack (3-line mode)

A word's status drives its color and how much help is shown:

1. Known (green) — characters only; you don't need help.
2. Partial (yellow) — adds pinyin / meaning for a word you half-know.
3. New / untracked (blue) — full gloss + pinyin + characters.
4. Unknown (red) — full gloss + pinyin + characters, flagged for attention.

Those are background tints. The font color of each of the three rows — characters, pinyin, English — is separately settable under Settings → Display → Advanced display → Reader text colors (off by default, so your theme stays in charge). See Display modes & colors.

Traditional Chinese (Taiwan / Hong Kong)

Settings → Script & region → Text script is Automatic by default: both scripts are recognised, each word is shown the way you read it, and a mixed vault works with nothing to switch. Your vocabulary is shared between the scripts — mark 學習 known and 学习 is known too.

Automatic costs about 29 MB of extra index. Choosing Simplified avoids that but cannot read a Traditional note — it falls apart into single characters — so change it only if you know your notes are Simplified and memory is tight.

Pronunciation can be switched to the Taiwan reading for the ~500 words the dictionary records one for (垃圾 lè sè rather than lā jī). It does not cover the neutral-tone difference (謝謝 xièxiè, 東西 dōngxī) — CC-CEDICT has no data for those. Zhuyin is not supported yet.

Your notes are never rewritten, and words are never converted between scripts for display — about 540 Simplified headwords map to more than one Traditional form and there is no frequency data to pick correctly, so the plugin shows you the form you actually read. See Traditional Chinese & regional pronunciation.

Open the Chinese view (mobile)

1. From a normal note, tap 中 in the header to open the Chinese view.

Word lookup card (mobile)

1. Word, pinyin & meaning — headword, reading, traditional form, definitions.
2. "I know" — tick characters / pinyin / translation; this sets the word's status.
3. Per-word stats — HSK, times seen, last seen, status, SRS due date.
4. Exposure history — recent sightings, feeding the stats and charts.
5. Actions — Ignore, Mnemonic (write your own emoji line + story, or generate them with AI), Explain (AI: a thorough usage note you can save, see Explain; added in 0.9.0, so it is not in this older screenshot), Edit, or Enhance (AI, see below).

Tap-to-format & highlights (mobile)

1. Highlighter button — blue = add formatting (tap again → red remove → off).
2. Mode banner — tap a start word then an end word; Formats ▾ picks the format / highlight color, Exit leaves.
3. The applied highlight spanning the selected words.

Left: the Formats menu (Bold, Italic, headings, quote, and nine highlight colors). Right: the red remove mode — tap a span to strip its formatting. Full details in Formatting & highlighting.

AI dictionary Enhance (mobile)

A sparse dictionary entry can be enriched by your configured AI provider.

Left → right, before and after tapping Enhance:

1. "Dictionary entry enhanced" confirmation.
2. Enriched definitions + grammar — full senses replace the bare "variant of…".
3. Revert — undo the enhancement.

Flashcard review (mobile)

1. Stats view — Dashboard / Flashcards / Words.
2. Review queue — Unclassified, Due (SRS), or Smart story.
3. Progress through the queue (sorted by frequency) · Skip.
4. The card — headword, times seen, Reveal pinyin, example sentence.
5. Grade — Known / Partial / Unknown, or Ignore.

Vocabulary stats & Smart stories

Tracked / known / partial counts and a comfort-HSK level; cumulative progress per-HSK coverage over time, and a Topic coverage radar showing which subjects your vocabulary covers; and Smart-story generation that weaves your due words into a level-appropriate story. See Spaced repetition and Story generation.

Why This Plugin Exists

Learning a language should be enjoyable. Unfortunately, many learners experience the opposite: endless flashcards, grammar drills, vocabulary lists, and a constant feeling that progress is slow and difficult.

When I started learning Chinese, the biggest breakthrough was discovering Comprehensible Input.

The core idea is simple: instead of memorizing isolated words and grammar rules, you learn by consuming content that is just slightly above your current level. You acquire the language naturally through reading and listening, much like children learn their native language.

Tools such as DuChinese have shown how powerful this approach can be. Reading stories designed for your level is far more engaging than spending hours reviewing flashcards. For a long time, comprehensible input allowed me to progress while enjoying the process.

However, as your Chinese improves, a new problem appears.

At beginner and intermediate levels, common vocabulary appears frequently enough that repeated exposure naturally reinforces it. But as you advance, you start learning increasingly rare words. These words may only appear occasionally, making it difficult to retain them through reading alone. This is the point where many learners feel forced to return to flashcards and traditional spaced repetition systems.

The problem is that flashcards often break the flow and enjoyment of language learning. Instead of reading interesting content, you end up reviewing isolated vocabulary items again.

This plugin explores a different approach.

Spaced Repetition Through Stories

Instead of using flashcards, this plugin uses stories and meaningful content as the vehicle for spaced repetition.

With the help of AI, it becomes possible to generate or adapt content that naturally includes the vocabulary you need to review. Rather than seeing a word on a card, you encounter it inside a story, dialogue, article, or topic that interests you.

The goal is to combine the effectiveness of spaced repetition with the enjoyment of comprehensible input.

You can import Chinese texts that interest you, track your vocabulary knowledge, and receive content tailored to the words that need reinforcement. Learning becomes less about reviewing cards and more about reading Chinese every day.

A Better Reading Experience

Many Chinese reading tools provide pinyin and translations for every word. While helpful at first, this creates another problem: learners naturally rely on the easiest information available.

If English translations are always visible, your eyes drift toward English. If pinyin is always displayed, you start reading pinyin instead of recognizing characters.

As a result, character recognition develops more slowly than it should.

This plugin takes a different approach.

Words can be marked as:

• Known
• Partially known
• Unknown

Based on that knowledge, the plugin can selectively display characters, pinyin, or translations only where they are actually needed.

Words you already know remain visible as Chinese characters only, encouraging character recognition and reading fluency. Support is shown only for vocabulary that still requires assistance.

The result is a reading experience that provides help when necessary without constantly encouraging dependence on pinyin or translations.

Help While You Read

Reading real Chinese raises questions a dictionary cannot answer. The plugin can help when you get stuck, without taking you out of the text. This part uses AI, is optional, and the rest of the plugin works fully without it.

• Why does this word work here? Tap a word and choose Explain: when to use it, how learners get it wrong, similar words and the radical of each character. Save it as a note if it is worth keeping.
• What is this sentence doing? Tap the lightbulb, then the first and last word. You get the meaning, the structure, the job of every word and the grammar points.

1. Lightbulb — armed. 2. Hint — tap the last word. 3. Explain / Proof read / Simplify — pick what happens. 4. Exit.

Left: a phrase explained (1 · meaning, 2 · the job of every word, 3 · what it cost, 4 · save). Right: proof reading (1 · Apply one fix into your note, 2 · copy the corrected text, or Apply all).

• Is my Chinese right? Proof read finds real mistakes in what you wrote, suggests the simplest fix, and puts it into your note with one tap.
• Too hard to read? Simplify asks the AI for several easier ways to say the same thing, measures each against the HSK lists and the words you know, and shows the simplest with the numbers.
• I keep forgetting the tones. Mnemonics give each character a picture of its meaning followed by its tone number, written by the plugin so the tone is always right. Fill in a whole note at once from the ⋯ menu.
• You stay in control. Every answer shows what it cost, you can tell the AI how you like things explained (language, level, focus), and nothing is saved to your vault until you say so.

See Explain & proof read and Mnemonics.

Measure Real Progress

Another important aspect of language learning is feedback.

Many learners have only a vague sense of their progress. They know they have studied for months or years, but they cannot easily quantify what they have learned.

By tracking vocabulary knowledge over time, this plugin provides measurable insights into your progress:

• How many words you know
• Which words are improving
• Which words are being forgotten
• Whether your vocabulary is growing over time

Seeing tangible progress can be highly motivating, especially during the long journey of learning Chinese. The goal is not only to make learning more effective, but also to help learners stay motivated by making their improvement visible.

The Vision

The long-term vision of this project is simple:

Make Chinese learning feel more like reading and less like studying.

By combining comprehensible input, AI-generated content, vocabulary tracking, and story-based spaced repetition, this plugin aims to make language acquisition both effective and enjoyable—even beyond the intermediate stages where traditional comprehensible-input tools begin to struggle.

See NOTICE.md for license notes (CC-CEDICT, HSK).

Install

Requires Obsidian 1.13.0 or newer (since 0.5.1 — the settings tab uses Obsidian's declarative settings API so every setting is searchable).

Available in the official Obsidian community-plugin store: Settings → Community plugins → Browse → search Chinese Comprehensible Input → Install → Enable. To test the latest beta builds instead, install via BRAT. Full step-by-step guide (store, BRAT, or manual) in docs/install.md.

Documentation

Detailed guides live in docs/. Each settings section also links to the relevant page from inside Obsidian. Highlights:

• Install (BRAT or manual) — get the plugin into your vault
• FAQ — top issues and where the fix is
• OpenAI setup, privacy, and cost
• Ollama tips: model choice and getting good output
• Mnemonics — hand-written and AI-generated memory hooks, personalising the prompt
• Explain — an AI usage note for one word (senses, grammar, examples, common mistakes, similar words, each character's radical), previewed before you save it
• Story generation, end to end
• Display modes & colors
• Traditional Chinese & regional pronunciation — Taiwan / Hong Kong script, Taiwan readings, and what is not covered
• Formatting & highlighting — tap-to-format mode, colored highlights, Highlightr support
• Themes & plugin compatibility — Things-style checkboxes, Highlightr, sync tools, and the limits inside the Chinese view
• E-ink readers — the built-in E-ink mode (underlines instead of colour tints, HSK level as a number) and the CSS snippet it grew out of
• Word states (new / partial / known / unknown / ignored)
• Exposure tracking
• Spaced repetition
• Vault-mirror sync (for users who don't sync .obsidian/)
• Conflict resolution between devices
• Backups and going back to an older version — automatic copies before an update, and the way back after a downgrade

Limitations

• Mobile + Ollama needs a reachable LAN/Tailscale host (localhost from the phone points at the phone). See Ollama tips.
• OpenAI mode sends prompt + target words to OpenAI's servers — fine for most users, see the privacy section.
• The bundled seed dictionary is tiny; real use needs CC-CEDICT (see Data below).

Dev

npm install
npm run dev        # watch build
npm run build      # type-check + production bundle
npm test           # vitest
npm run test:cov   # coverage report + threshold enforcement
npm run check-release

GitHub Actions runs the same validation set on every PR and on pushes to main: build, tests, coverage, and the release guard. Actual BRAT publishing stays manual so the tagged release assets and notes are reviewed before going live.

Development policy:

• Use a dedicated branch for each bugfix, feature, or release-prep change. Preferred prefixes: fix/, feat/, release/.
• Merge changes to main through PRs after CI passes.
• External PRs must be approved by the maintainer before merge.

See CONTRIBUTING.md for how to report bugs, suggest features, and open a PR (it's an issues-first project — please open an issue before a non-trivial PR).

To install the dev build into a vault:

1. Build: npm run build.
2. Copy manifest.json, main.js, styles.css into <vault>/.obsidian/plugins/chinese-comprehensible-input/.
3. Enable in Obsidian → Community plugins.

Data

A tiny seed dictionary is bundled for development. For real use, drop a CC-CEDICT shard at <vault>/.cci-dictionary.json (array of {simplified, traditional, pinyin, definitions, hsk?}). See NOTICE.md for license notes.

Privacy

• No vault content leaves your device unless you enable an AI provider. Story generation, Enhance, mnemonics, Explain, Proof read and Simplify are the features that transmit text (the words, sentence or selection involved, never the whole vault), and they stay off until you configure a provider.
• In OpenAI-compatible mode, story generation sends prompt text and target words to the provider you configured.
• The optional CC-CEDICT download contacts mdbg.net to fetch the dictionary. It is triggered only when you press the download button, and it uploads nothing — it is a plain download.
• API keys are stored locally in Obsidian's secret storage and are not written to synced vault files.
• No telemetry, no analytics, no usage reporting of any kind.

Permissions & network

What this plugin can access, why, and when. These mirror the capability rows on the Obsidian community plugin scorecard.

Network — three endpoints, none contacted unless you act:

Vault access

• Read — reads the Chinese note you have open, to tokenize and annotate it.
• Write — writes generated stories, and, if you enable the optional sync mirror, sanitized settings/vocabulary JSON inside your vault. Backups are written to the plugin's own folder, outside your notes; a restore you choose can rewrite the sync-mirror files you already have.
• Enumerate — lists Markdown file paths to build the vocabulary index. Paths and Chinese text are read locally and never transmitted.

Clipboard — used only when you click the vocabulary export or import buttons in Settings. The plugin never reads your clipboard in the background.

Not used at all: no shell or child_process execution, no eval, no innerHTML-style HTML injection, no direct Node filesystem access, no auto-update mechanism.

Data storage

• Settings, vocabulary state, SRS state, and exposure history are stored in the plugin's local Obsidian data blob.
• Before the plugin version changes, a compressed copy of that blob (and, if you use the sync mirror, this device's mirror files) is saved in the plugin's own folder (backups/), never in your vault. See Backups.
• If you enable the optional sync mirror, sanitized settings and vocabulary data are also written to JSON files inside your vault. API keys stay local.
• The bundled dictionary is only a small seed set. Normal use expects a user-supplied CC-CEDICT shard at <vault>/.cci-dictionary.json.