Lexis

简体中文

Lexis turns ordinary Markdown atomic notes into a personal glossary that appears where you read. A note title and its aliases become terms. When one of those terms appears again, Lexis highlights it automatically, shows the original note on hover, and can open that note for the full context.

The main workflow is simple: write an atomic note for a concept, person, method, or name once; recognize it everywhere afterwards. This works in Markdown, PDF, supported EPUB readers, browser pages, and Zotero. Your notes remain the source of truth.

When a term does not deserve its own note, one Markdown file can also hold many lightweight inline entries. A novel cast, abbreviations, or a small project glossary are examples of this secondary storage form.

If some entries later need deliberate memorization, the same notes can optionally become FSRS cards. Review is a secondary layer, not a requirement for using the dictionary, highlights, or hover cards.

Your vault remains the database. Lexis needs no account, hosted service, or proprietary dictionary format.

A glossary made from your own notes

Common questions

Can Obsidian show my atomic note whenever I encounter its term again?

Yes. Lexis indexes note titles and aliases as terms. When a term appears in a supported reading surface, it is highlighted automatically; hover shows the source note, and click can open that note. The explanation stays in the Markdown atomic note instead of being copied into a separate plugin database.

Can I build a personal dictionary in Obsidian using only Markdown?

Yes. A dictionary can be a folder of ordinary notes, a tag, an individual note, an index note's direct links, or several inline entries inside one note. Lexis does not lock definitions into JSON or a proprietary database.

Can one Markdown file hold several glossary entries?

Yes. Inline entries are the compact alternative to atomic notes. They are useful for a novel cast, abbreviations, or other small terms that do not need separate files. Titles, aliases, categories, and entry colors remain available.

Can Obsidian automatically highlight every occurrence of my dictionary terms?

Yes. Lexis matches titles and aliases across supported views, highlights them in context, and opens the source note in a hover card. Each dictionary can be shown or hidden independently.

Can I use the same Obsidian dictionary in PDFs, EPUBs, websites, and Zotero?

Yes. Lexis supports Obsidian's built-in PDF viewer and compatible EPUB readers; the optional Lexis Web and Lexis for Zotero companions reuse the same local Markdown dictionary. Documents must have selectable text.

Can a Markdown dictionary also work as a spaced-repetition deck?

Yes. Lexis includes FSRS review for whole notes, question-and-answer syntax, and cloze cards. Review is optional: automatic highlighting and hover definitions work without turning every entry into a card.

Core workflows

Use atomic notes as dictionary entries

Point Lexis at one or more folders, tags, individual files, or index-note links. Each atomic note title becomes an entry, frontmatter aliases become additional matching terms, and the note body remains its explanation. This is the default workflow: encounter the term, see the note, and open it when more context is needed.

Keep lightweight entries in one file

Mark a note with lexis-inline: true, then write Name / Alias=> annotation. Spaces around / are optional, the delimiter is configurable, and \/ writes a literal slash. Inline entries take precedence when a legacy delimiter still matches flashcard syntax. This is useful for recurring characters, abbreviations, places, objects, and other entries that do not need separate atomic notes.

---
lexis-inline: true
---

## Characters
Yalda / Yal {captain}:: A painter who appears under several names.
Otto:: Keeps the notebook everyone else forgets.

Entry colors make people or concepts easier to recognize without tying meaning to a raw color. Under Inline entries → Entry colors, one row may contain aliases such as captain / commander / ENTJ; spaces around / are optional and every name resolves to the same color. Use the preferred name at the end of an inline entry, such as {captain}. Typing { or placing the cursor inside {} opens fuzzy suggestions from existing entry colors; names used in notes but missing from the rules are listed at the top of the Entry colors settings. A one-file entry uses lexis-color: captain in frontmatter. You may also write a hex color directly, such as {#8b5cf6} or lexis-color: "#8b5cf6". Entry colors override category, tag, dictionary, and global colors.

Inline entries can be grouped by file or heading. Heading groups may follow the nearest heading or a fixed level from H1 to H6. With H2 selected, nested headings such as H3 and H4 inherit their nearest H2 group, which is useful for global categories such as characters and settings. In an inline note, typing the configured heading marker and a space opens fuzzy suggestions collected from headings at that level across all inline notes.

Read with the same lexicon everywhere

Lexis highlights known entries and shows their notes on hover in:

• Obsidian Markdown, Live Preview, Canvas nodes and edge labels, and the built-in PDF viewer
• compatible epub.js-based EPUB readers
• Chromium browsers through Lexis Web
• Zotero Reader through Lexis for Zotero

Selected text can be added to a dictionary, saved as an occurrence, or attached as an alias. Obsidian remains the source of truth; the browser and Zotero companions communicate with it over an authenticated loopback-only bridge.

Each Obsidian dictionary has its own highlight switch. Lexis Web keeps a separate visibility profile for each website: open the extension popup to show or hide dictionaries on the current site. Browser choices do not overwrite Obsidian settings, and the current page updates immediately.

Optional: review selected entries

Lexis works as a complete reading glossary without review. If a few entries are worth deliberate practice, they can reuse the same Markdown notes and dictionary structure:

Install

Obsidian

Install Lexis from Settings → Community plugins → Browse. For manual installation, download main.js, manifest.json, and styles.css from the latest Obsidian release into <vault>/.obsidian/plugins/lexis/.

Browser companion

1. Download Lexis Web 1.2.4 for Chrome or Lexis Web 1.2.4 for Firefox.
2. Extract it, open chrome://extensions, enable Developer mode, and choose Load unpacked.
3. Enable Local bridge in Lexis settings, then copy its port and access token into Lexis Web.

Chrome does not auto-update unpacked extensions. Replace the extracted folder with a newer browser release when needed.

Zotero companion

1. Download Lexis for Zotero 0.2.2 (lexis-zotero-0.2.2.xpi).
2. In Zotero, open Tools → Plugins, choose Install Plugin From File, and select the XPI.
3. Enter the same local bridge port and token in Lexis for Zotero.

After the first manual installation, Zotero can update the add-on from its update feed.

Quick start

1. In Settings → Lexis, add one or more dictionary folders.
2. Read a Markdown, PDF, or EPUB document. Matching entries are highlighted; hover to open the card.
3. Select unfamiliar text and add it to a dictionary. Lexis can save the surrounding sentence as an occurrence.
4. Keep reading. Open Lexis Home only if you want to review selected entries or inspect long-unseen ones.

The interface language can be switched between Chinese and English in Lexis settings. Translations are kept together by message key in src/i18n.ts, so adding another language does not require searching through the UI code.

Where data lives

Dictionary notes and note-level FSRS fields stay in vault Markdown files. Encounters, review states, plans and history live in the visible Data folder under Settings → Lexis → Data storage (default Lexis-data; existing visible encounter folders are reused). Directory changes require the check button; undo discards the draft. Existing users' history is migrated without age pruning until they confirm a retention period there (suggested: 90 days). Current schedules are not reset. The hidden .obsidian/plugins/lexis/data.json contains configuration only, not learning records. Browser settings and its temporary dictionary cache remain in extension storage. Update every device before reviewing with the new storage format; sync both configuration and the visible data folder.

Note blocks

Use a lexis code block to render memory, relationship, and occurrence data inside an entry note:

• curve — retention curve
• rel — outgoing and incoming links grouped by heading
• rel {{heading}} — missing backlinks under that heading; replace the placeholder with the actual heading, without braces
• occ — unsaved occurrences
• derived — dictionary notes linking to this entry, regardless of heading; it does not infer word derivation
• blank — all applicable sections

Relation types come from heading text rather than a fixed list. Any Markdown heading level (# through ######) works. For example:

cold.md:

## Antonyms
[[warm]]

```lexis
rel
```

warm.md:

```rel
Antonyms
```

The first note shows warm; the second automatically shows cold, which links to it. No reciprocal [[cold]] needs to be written. Antonyms is only an example for {{heading}}, not a reserved name. The block adds missing reverse links without repeating outgoing links already written in the note.

Use lexis-home for a compact home summary, or lexis-heatmap for the heatmap alone.

Daily goals are configured in Settings → Lexis → Review → Review goals. Today's target is fixed when the dashboard first opens; changes apply tomorrow. Each cloze counts separately, regardless of whether answers are shown individually or together. Only remembered cards count as completed, once per day, across review entry points.

Create saved plans on Lexis Home. A lexis-home block can show one plan by name:

```lexis-home
plan: Mathematics
```

Without plan:, the block shows the combined plans, or the dictionary when no plans are saved. Goals, plans, and daily target snapshots are stored in the existing Lexis settings file; no extra data folder is created.

Why a personal lexicon

Lexis starts from one claim: vocabulary is infrastructure, not a study subject. Every field brings its own terms, and the half-known ones are exactly those your eyes learn to skip.

• A dictionary that is always present can become part of memory. Clark and Chalmers' extended-mind thesis describes a trusted, constantly available external store functioning like recall. Lexis aims for those conditions: one lexicon, available by hover on every reading surface.
• Highlighting supports noticing. Research on textual enhancement finds that visually enhanced forms attract attention and can improve learning over unenhanced input (eye-tracking study, vocabulary and grammar study). It does not remove the need to retrieve a memory.
• Words are learned through re-encounter. A lookup is an event; a word seen repeatedly in real context becomes knowledge. Global highlighting turns ordinary reading into a source of those encounters.
• Noticing is not retention. Lexis therefore separates attention from review. The highlighter gets the term noticed; FSRS schedules retrieval practice.

Lexis does not promise faster reading or learning without effort.

Why highlights fade, reviews move, and entries retire

• Salience is scarce. Repeated visual cues lose force—the same family of effects behind banner blindness. As FSRS stability S grows, a highlight fades toward a configurable floor: final opacity = base opacity × [1 - S/(S+20) × (1-fade floor)]. A support should recede when the skill is internalized.
• A hover can reveal friction. Testing-effect and desirable-difficulty research make retrieval attempts informative. A hover is noisy—it may mean curiosity, not forgetting—so Lexis may move a review date closer but never counts the hover as a review or changes a difficulty score.
• Importance appears through use. At add time, nobody knows whether an entry will become foundational or never appear again. Lexis surfaces long-unseen entries with evidence and lets you retire, keep, or master them; it never decides automatically.
• A personal lexicon is an OED for one reader. The Oxford English Dictionary grew from dated, sourced citation slips. Lexis applies the same pattern to one person's reading history: definitions and occurrences accumulate from actual encounters.

Privacy and architecture

• Dictionary data stays in ordinary Markdown files in your vault.
• Review state is stored in lexis-* frontmatter fields.
• The optional bridge listens only on a configurable loopback port and requires a token.
• The browser and Zotero companions do not become separate databases.
• Scanned PDFs without a text layer cannot be highlighted.
• Settings has top-right Reload and Check for updates actions. Checks contact GitHub only on click; a newer compatible release requires confirmation before downloading. Only the three plugin code assets are replaced, with rollback on failure. Development folders can reload but cannot self-update.

See the full Lexis Privacy Policy.

Development

The repository contains all three clients:

• Obsidian: src/, bundled to main.js
• Browser: pkg/browser-extension/
• Zotero: pkg/zotero-extension/

The Obsidian source is TypeScript. Run npm install once, then use npm run typecheck, npm run build, or npm run dev. Releases still contain the mobile-compatible main.js, manifest.json, and styles.css only.

Issues and contributions are welcome in the GitHub repository.