WeRead notes pulled into Obsidian, and why the synced files stay read-only

WeRead highlights and reviews become Obsidian Markdown files

Tencent's WeRead keeps a reader's highlights, thoughts, chapter comments and book reviews inside the account, where no other tool can query them. This plugin takes that account data and writes it into a vault as plain Markdown files you can search. It targets Obsidian users who read in the WeRead app and take notes in Obsidian, and in particular the subset who render their library through Dataview and minimal cards, which the project links to a wiki page.

The scope runs well past highlights. The bookshelf view supports search, filtering, sorting and grouping by year, alongside a sync log. Opening a book opens a detail page in a new tab with 4 tabs: highlights grouped by chapter, notes in reverse chronological order, community highlights, and reviews that combine your own with selected community ones. The header carries cover, reading progress, reading duration, category and publisher, and a floating button jumps from the detail view straight to the local note file.

Placement is configurable enough to fit an existing vault. You can create subfolders by book title or category, pick from several filename formats, and add your own YAML fields to the frontmatter, such as tags or reading status. A scheduled auto sync runs on an interval you set. Public account articles sync too, not only books, and a switch pushes the day's reading notes into Daily Notes at a position you define.

Two credential paths and the features the fallback loses

WeRead exposes this data through an Agent API that takes an API Key, and the plugin also accepts a session Cookie. In settings, the API Key area carries a `扫码获取` button: an account already signed in returns a key straight away, an account that is not signed in pops a QR code, and once WeChat has scanned it the field fills in and a green check appears beside it. On mobile you copy the key from weread.qq.com and paste it into the same box.

Routing then happens on its own. Calls go to the V2 Agent API first and fall back to the Cookie path when that fails, so the reader sees one sync button regardless of which credential is configured. The 2.0 rewrite is what put the Agent API and the Key at the centre of that arrangement.

That fallback is where the interesting reading starts, because it is not feature-equivalent. Popular highlights are the community's highest-ranked lines per book, and the book detail view marks that tab as needing an API Key. A session that has quietly dropped to Cookie keeps syncing your own highlights while the community layer goes unfetched, and nothing is raised at the moment of fallback. Cookie credentials carry a documented weakness of their own: they can expire after long disuse, which is the stated reason the project points new users at the API Key path first.

Searching the plugin list, then running Sync Weread from the palette

Install runs through the Obsidian community plugin list. Search `weread`, pick `Weread Plugin`, click `install`, then click `Enable`. The README gives a manual route as well, downloading a build from the project's GitHub releases page.

Set the credential up before the first run. Open settings, click `扫码获取` in the API Key area, and confirm the green check. On a phone, copy the key from this address and paste it into the same field:

https://weread.qq.com/api/skills/apikeyGet

Then trigger a sync from the WeRead button on the left ribbon, or open the command palette with `Cmd+P` on macOS and `Ctrl+P` on Windows, type `Weread`, and run `Sync Weread`:

Sync Weread

Output follows the minimal theme (`theme:minimal`) unless you switch templates, and the project points readers at its wiki page for pairing the result with Dataview and minimal cards. Read the warning below before your second run, because the first run's files are not a safe place to type.

Building from source is a separate path, and the working commands sit in package.json:

"clean": "rimraf dist main.js",
"build": "svelte-check && npm run lint && webpack",
"deploy": "NODE_ENV=development webpack && ./sync.sh",
"lint": "eslint . --ext .ts --fix"

`build` gates the bundle behind a Svelte type check and the linter before webpack runs, so a broken view or a lint error stops the build outright.

Popular highlights fetch twenty community lines per book

Turning on `同步热门划线` in settings gives each book a community layer: the top 20 highlights by popularity, merged into your own lines chapter by chapter and annotated with how many other people have read each one. The merged template marks community text with a pin and a flame marker so it separates from yours, while the separated template shows the community block on its own, grouped by chapter. One of the four built-in themes, the separated variant with popular highlights, splits the note into 3 blocks for your highlights, community highlights and your notes.

That layer is cached locally. The default window is 7 days and the TTL is configurable, so the knob decides how many days pass before a sync returns to the community endpoint for every book it touches. This is also the feature to check first when a sync runs on Cookie after a fallback, because the community data needs the API Key credential and nothing in the log reports its absence.

Reviews travel the same path and land in the same file. The reviews tab of the book detail view merges your own review of the book with selected community reviews, so annotation and opinion end up together in one note rather than two.

Overwrite sync deletes whatever you typed into a synced file

Every note this plugin writes belongs to the plugin. Each run replaces the whole note file instead of merging into it, so any hand annotation you add to a book's note is gone the next time that book syncs. The project's own answer is to keep your writing in separate files and link in with Obsidian Block references, the pattern it recommends for anyone doing permanent notes.

The Daily Notes integration repeats the same warning with a sharper edge. You set the Daily Notes directory and the file format separately, and if your daily notes come from Periodic Notes you can match that plugin's naming:

YYYY/[W]ww/YYYY-MM-DD

Reading notes then get inserted between 2 headings of your choosing. Content inside that range is overwritten, and you are warned not to type within it. A span holding your own sentences is a span the next sync will clear, and there is no per-line merge behaviour described.

Retry behaviour compounds this. The known issues entry says a dropped connection is fixed by clicking sync again, and that notes already synced will not be updated again. The completed TODO list separately records that the sync logic was rewritten to judge by note count rather than delete and rebuild the file on every run. Read those together and the operating rule is clear: a file you hand-edited is overwritten, and a note the plugin has already synced is skipped on the retry path.

Four built-in themes, and none of them editable

Templates are the plugin's main surface. Four built-in themes ship with it, and the README groups all templates into 3 types carrying different rights. Built-in templates can be neither edited nor deleted. Custom templates are yours to edit, copy and export. Old templates, migrated from earlier versions, cannot be edited either, and can only be duplicated before changes become possible.

That leaves a single path in: copy a built-in theme, which creates the duplicate and sets it as the one in use, then open the editor to change template content and settings. Exports download as JSON files, and imports accept a local file or a URL. Themes can be shared with other users, which is what the separate community themes guide covers in detail.

Choosing among the 4 built-in layouts decides where your own thinking sits. The merged template puts highlights and thoughts inline with community markers, which suits fast review. A separated template shows clean highlights first, then gathers notes together at the bottom. The WeChat official note theme carries heavier metadata, for generating book notes. The fourth, separated with popular highlights, keeps your highlights, community highlights and notes as three independent blocks. Combined with custom frontmatter fields and per-book folders, file layout ends up almost entirely template-driven, so an opinionated vault takes planning rather than defaults.

A TypeScript entry point beside two linter configs

The package entry is `main.ts`, not a compiled file, while the clean target is `rimraf dist main.js`, so the declared entry and the build artefact are different files. package.json declares version 2.3.0, and the Obsidian package it compiles against sits at ^1.4.11 alongside TypeScript ^5.6.0. The deploy path runs webpack in development mode and hands off to `sync.sh`, a shell script at the repository root, while shipping metadata lives in `versions.json` and `version-bump.mjs` next to `RELEASE_NOTES.md`.

Two lint configurations sit side by side at the root, `.eslintrc` and `eslint.config.mjs`, while the lint script passes `--ext .ts`. The build chain runs `svelte-check` first as well, covering the Svelte sources that the lint pass does not name.

Dependency pinning is inconsistent in a way worth knowing before you patch anything. Most entries in both dependency blocks carry caret ranges, but three are exact:

"esbuild": "0.13.12",
"tslib": "2.3.1",
"@types/set-cookie-parser": "2.4.10"

`esbuild` is the one to note, because no script in package.json invokes it; it rides along pinned next to the webpack path the build actually uses. Svelte and nunjucks are the runtime pieces behind the views and the template rendering. The project carries an MIT licence, and the last push to the default branch landed on 2026-09-06.

Keeping your own writing outside the synced file

This is a tool for moving your own WeRead activity into a vault, not for moving books. The disclaimer is explicit that the program does not scrape any book content and supplies only the logged-in user's books and note information. Book text is therefore not part of what it fetches, and the sync covers metadata, highlights, highlight thoughts, chapter comments and book reviews rather than page content. If your goal is a searchable corpus of what you read, this is the wrong tool and nothing in its settings changes that.

The alternative worth taking seriously is the one the README points to itself: write permanent notes in separate files and reference them from the synced note. The plugin can then overwrite its own files on every single run while your thinking stays intact, at the cost of a link hop instead of one self-contained file.

The acknowledgements credit wereader, a Kindle plugin and a Hypothesis plugin as prior art without comparing any of them, so within what is documented here this is the only approach written up in full.

Editorial conclusion

Adopt it if your highlights live in WeRead and your thinking lives in Obsidian, and treat every synced file as read-only output that you link into from notes kept elsewhere. Do not adopt it for book text, for an offline library, or for any habit of typing inside a synced note. Before enabling it, confirm the API Key scan returns a key on your account, because the community highlights tab and the cached top 20 lines depend on that credential, and the Cookie fallback drops them without an error. Set the insertion range for Daily Notes last.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. zhaohongxuan/obsidian-weread-plugin on GitHub