Yuque Document Sync

Problem

When syncing local Markdown into Yuque, the hard part is not one API call. It is resolving doc IDs and slugs, attaching new docs to the TOC, choosing stable titles, rewriting local links, avoiding repeated pushes, and handling remote drafts or conflicts. This skill narrows the surface area to one Yuque knowledge base and exposes yuque_cli.py for list, get, create, update, delete, toc, sync, pull, and status, with results that include doc ID, title, and slug for verification.

How It Works

• Core CRUD: Operate on documents inside a single Yuque knowledge base through OpenAPI. create appends the document to the TOC by default, while get, update, and delete accept either an integer ID or a more readable slug.
• Sync state: sync records local content hashes and remote latest_version_id values in .yuque-sync.json, pushing only changed documents and skipping unchanged ones instead of performing blind full updates.
• Local layouts: Supports flat, nested, and frontmatter Markdown arrangements. In frontmatter mode, files can declare slug and optional title; the YAML block is stripped before push.
• Body transformations: Rewrites inter-document links for Yuque, fixes bold-close spacing patterns such as **Label:** value, and reverses slug links back to local file links on pull.
• Safety rules: The token is passed only to setup and stored in .env; it is not echoed, hardcoded, or committed. Remote deletion requires explicit user confirmation.

Boundaries

This is best for managing Markdown documents and TOC state in one knowledge base. It does not own Yuque team, member, or repository management, and it does not perform cross-repo migration. TOC insertion appends to the repository root as a child node and cannot choose a parent or position. sync compares published versions using latest_version_id, so unpublished remote drafts may be overwritten. Ambiguous layouts, conflicts, and missing locally tracked files require explicit human choices rather than automatic action.