YNote Sync

English | 简体中文 | 한국어 | 日本語

YNote Sync is an unofficial, desktop-only Obsidian plugin for synchronizing a Youdao Note workspace with an Obsidian vault.

It is designed as a working two-way client rather than a read-only exporter: it can pull cloud changes, track local changes, review conflicts, and push approved changes back to Youdao Note.

[!WARNING] This project is under active development. Back up both your Obsidian vault and important Youdao notes before using it with production data.

Features

• Quick sync: incrementally pull cloud changes, review the local workspace, resolve conflicts, and push selected changes.
• Initial/full pull with resumable jobs, progress reporting, and local state.
• Local create, edit, delete, rename, and move tracking.
• Markdown, Native Note, MindMap, LXTable, Draw.io, Excalidraw, Canvas, images, attachments, and arbitrary binary files.
• Native viewers/editors for supported Youdao formats, including MindMap and LXTable.
• Markdown image and attachment upload with resource association.
• Cloud trash, history preview, conflict review, and safe force operations.
• A local repository manager for filtering untracked files, conversion state, resources, and synchronization anomalies.
• Web Cookie, Client Token (YNOTE_PC), and MCP authentication profiles.
• English and Simplified Chinese plugin UI.

Feature availability depends on the selected provider and file format. Some native formats are editable, while others are currently view-only or require a compatible Obsidian community plugin.

Requirements

• Obsidian 1.8.0 or later.
• Obsidian desktop; mobile is not supported.
• A Youdao Note account and a supported authentication profile.
• Node.js 20 or later when building from source.

Installation from source

There is no stable community-plugin release yet.

git clone <repository-url>
cd obsidian-ynote
npm install
npm run build

Create the following directory in your vault:

<vault>/.obsidian/plugins/ynote-sync/

Copy these files into it:

main.js
manifest.json
styles.css

Restart Obsidian, open Settings → Community plugins, and enable YNote Sync.

Getting started

1. Open Settings → YNote Sync → Account & connection.
2. Select a provider and authentication mode.
3. Configure the synchronization root and test the connection.
4. For a new vault, run Initial/full pull to establish a trusted baseline.
5. For normal daily use, click the sync icon in the left ribbon or run YNote Sync: Start sync from the command palette.
6. Review the plan and conflicts before approving cloud writes.

The plugin stores credentials, synchronization state, reports, and caches under the configured root:

.ynote-sync/

Do not commit this directory, cookies, Client Tokens, logs, or captured network traffic.

Everyday workflow

Start sync

The primary command performs one coordinated workflow:

1. Compare the applied cloud version with the latest cloud version.
2. Pull and apply cloud increments when required.
3. Read the locally recorded workspace changes.
4. Present conflicts and selectable local operations.
5. Push only the operations approved by the user.

The left-ribbon sync button and the command-palette entry use the same implementation.

Full pull

Use Initial/full pull only for first-time initialization, rebuilding a vault, or recovery. It is separate from quick daily synchronization.

Local files

Use the file or folder context menu to push a specific item. The local repository manager can scan, filter, convert, and queue multiple local files.

Native files

• Native Note files are downloaded faithfully and opened in the plugin's native viewer. Conversion to Markdown is explicit.
• MindMap and LXTable use dedicated views and preserve their native payloads.
• Draw.io and Excalidraw integrate with compatible Obsidian plugins when available.

Safety model

• Cloud writes always go through Plan → Review → Apply.
• Conflict and remote-version checks are repeated before applying writes.
• Local deletion, cloud deletion, rename, and move are recorded as pending workspace operations.
• Reset and repair commands do not silently write to the cloud.
• Credentials and logs are kept outside normal plugin settings and are redacted in reports by default.

Project structure

obsidian-ynote/
├── src/
│   ├── adapters/          Special-file adapters
│   ├── assets/            Embedded resource handling
│   ├── auth/              Authentication and credential storage
│   ├── commands/          Command and file-menu entry points
│   ├── converter/         Native-to-Markdown conversion
│   ├── local-repository/  Local repository manager
│   ├── provider/          Web, MCP, and CLI provider boundaries
│   ├── sync/              Pull, Push, Journal, conflict, and job logic
│   ├── ui/ and views/     Obsidian modals and custom views
│   └── main.ts            Plugin lifecycle and registration
├── scripts/               Diagnostics and provider smoke-test CLIs
├── schemas/               Provider and Web model schemas
├── tests/                 Unit and integration tests
├── manifest.json          Obsidian plugin manifest
├── styles.css             Plugin styles
└── package.json           Build and development commands

Runtime data is written to .ynote-sync/ inside the configured vault root. On upgrade, the plugin automatically renames the legacy .youdao-sync/ directory when .ynote-sync/ does not already exist. If both directories exist, neither is overwritten and the plugin reports the conflict.

Development

npm install
npm run typecheck
npm test
npm run build

Useful diagnostic commands:

npm run ynote:doctor
npm run ynote:web:smoke
npm run ynote:mcp:smoke

Publishing a GitHub Release

1. Update all release metadata with one command:

   ./set-version.sh 0.1.4
   

   This synchronizes manifest.json, package.json, package-lock.json, and versions.json. The equivalent npm command is npm run version:set -- 0.1.4.

2. Commit and push the release source.

3. In GitHub Actions, run Release Obsidian plugin and enter that exact version without a v prefix.

The manual workflow type-checks, tests, builds, validates the release metadata, and publishes main.js, manifest.json, styles.css, and ynote-sync-x.y.z.zip as Release assets.

Commands that can modify cloud data require explicit confirmation or an explicit apply flag. Never use real credentials in fixtures, logs, issues, or screenshots.

Current limitations

• The Web provider is the most complete synchronization path.
• Native Note round-trip rich-text editing is not complete; explicit Markdown conversion may be lossy.
• Some advanced MindMap, LXTable, Draw.io, and Excalidraw features still need compatibility testing.
• Mobile Obsidian is not supported.
• Automatic background or scheduled cloud synchronization is not enabled.

This project is not affiliated with or endorsed by Youdao.

Licensed under the MIT License.