yuque-sorting

yuque-sorting

yuque-sorting is the desktop Obsidian companion for current YuqueOut exports.

完整中文操作手册请参阅：YuqueOut 与 Yuque Sorting 使用说明。

Workflow

1. In YuqueOut, choose 64-bit (default) or 72-bit GUIDs. Markdown identities and _yuque_order.json are generated automatically.
2. Copy the exported knowledge base into an Obsidian vault.
3. Install this folder as .obsidian/plugins/yuque-sorting/ and enable it. If data.json is absent, sync that file first or explicitly run 初始化本地目录顺序 for a genuinely new vault.
4. Run 恢复原语雀目录顺序. New export IDs adopt exported identities once; later explicit runs restore order only.

Precise drag and drop

• Drop on the upper 30% of a title row to insert before it.
• Drop on the lower 30% to insert after it.
• Drop in the highlighted center of a folder or folder-note to move the item inside it.
• Follow the insertion line, target highlight, and pointer label for the exact action that will happen when released.
• Bind a custom hotkey to 撤销上一次语雀拖拽 in Obsidian. The current session keeps up to 50 safe undo steps without a timeout or repeated completion notices.

New files use f- identities and folders use independent d- identities. The suffix is Base62: 64-bit uses 11 alphanumeric characters and 72-bit uses 13. Legacy f:/d: identities remain readable. The plugin also detects exact duplicate GUIDs, can replace every vault identity without changing order, and keeps up to three on-demand backup files outside the always-loaded data.json.

The manifest is never imported automatically. An exportId initializes once unless the user explicitly invokes manifest-based order restoration; the plugin never deletes or rewrites it.

Synced order data

An absent data.json leaves the plugin waiting without creating a competing local file. The settings page offers 检查同步数据 and explicit local initialization. While running, the plugin checks for external data.json changes and reloads a valid stable version. Independent changes to different folders can merge; overlapping changes pause writes and offer a choice after backing up the discarded version as data-recovery-*.json. Invalid, missing, or partially written data pauses writes rather than replacing it. A sync service can still choose not to download a remote version; the plugin cannot inspect a version that never reaches this vault.

The settings page also provides a read-only unmanaged-item audit, searchable multi-selection for GUID generation/regeneration, historical-vault takeover, and strict paired folder-note display. Pairing requires a direct folder/folder.md relationship plus identical d-token/f-token suffixes; hiding is DOM-only and never removes the note from ordering or disk.

Compatibility note

Desktop 跨Vault合并（自动复制） copies the contents of a selected source directory into the current Vault. Both fields offer native directory selection and absolute-path entry; an empty target means the current Vault root. Missing target directories are created only after final confirmation. Same-level conflicts offer whole-item replacement (with backups), renaming, or source-order numbering. Source files/order and unaffected target sibling order are preserved. Manual transfer-package import/export has been removed. See the Chinese guide for restrictions, cancellation, and recovery. No additional runtime dependency is required.

The File Explorer sorting hook uses Obsidian's internal Folder.sort implementation. It is guarded and falls back to Obsidian's default order if a future Obsidian release changes that internal interface. Ordinary folders moved in Windows Explorer are inherently weaker because their identity is stored in data.json; moving them inside Obsidian is recommended. Note identities remain stable because the guid travels in frontmatter.

Development

Builds always update dist/. To also deploy into a local test Vault, set YUQUE_ORDER_TEST_PLUGIN_DIR, or create the ignored .yuque-sorting.local.json with a testPluginDir property pointing to that Vault's plugin directory. Without either setting, no Vault is modified. Deployment replaces only the three plugin artifacts and verifies that data.json is unchanged.

npm install
npm test

构建插件产物到 dist/：

npm run build

打包插件：

npm run pack

The build emits main.js beside manifest.json and styles.css, copies all three plugin artifacts into dist/, and deploys only those files to the configured test vault. Set YUQUE_ORDER_TEST_PLUGIN_DIR to override the default test-vault plugin directory. data.json and guid-backups are never copied or removed.

To update a manually loaded plugin, take the whole dist/ folder and copy its three files into .obsidian/plugins/yuque-sorting/. Never overwrite data.json there — it holds the order data and identities for that specific vault.