Migrating Yuque Notes to Local Markdown

For data safety, offline access, and integration with a local knowledge base, I needed to bulk-export Yuque notes to local Markdown. I ended up using yuque-dl to pull hundreds of documents plus images in one pass, and along the way contributed a "download all knowledge bases at once" feature back to the tool via a PR.

Background

Yuque is Alibaba's online knowledge-management tool, with notes stored in the cloud. My Yuque workspace held 27 private knowledge bases and 360+ documents, all of which needed to be exported as local Markdown.

Comparing options

Option	Tool	Best for	Pros	Cons
Option 1	yuque-dl	Bulk-downloading whole knowledge bases	Auto-downloads images, keeps structure, incremental	Needs Node.js, private repos need a cookie
Option 2	Official export + yuque2markdown	No extra tool	Official	Manual, .lakebook conversion may lose formatting
Option 3	yuque-hexo	Syncing to a Hexo blog	Good blog integration	Not for pure local archiving
Option 4	Open API, self-coded	Custom needs	Flexible	High dev cost

I went with Option 1, yuque-dl (2200+ stars) — least hassle, images and directory structure in one step.

Steps

Step 1: Install yuque-dl

npm i -g yuque-dl
yuque-dl --version  # confirm install

Requires Node.js 18.4+.

Step 2: Get the cookie (required for private knowledge bases)

Private knowledge bases need login credentials:

1. Log in to Yuque in the browser
2. Press F12 to open DevTools
3. Go to the Application tab
4. Left pane Cookies -> select https://www.yuque.com
5. Find _yuque_session and copy its Value

Warning

A cookie is a login credential, equivalent to a password. Don't leak it; discard it when done.

Step 3: Download

Method 1: download a single knowledge base

yuque-dl "https://www.yuque.com/<username>/<repo-slug>" \
  -t "<cookie>" \
  -d "<output-dir>" \
  --hideFooter

Method 2: download all knowledge bases at once (recommended)

# Enumerate all knowledge bases under the account and download them one by one
yuque-dl user -t "<cookie>" -d "/path/to/output"

Internally it fetches the knowledge-base list via GET /api/mine/books, so you don't need to find slugs manually.

Method 3: download several specified knowledge bases

# Specify multiple knowledge-base URLs
yuque-dl batch "<url1>" "<url2>" "<url3>" \
  -t "<cookie>" \
  -d "/path/to/output" \
  --hideFooter

Method 4: download one or more documents

# A single document
yuque-dl doc "https://www.yuque.com/<username>/<repo-slug>/<doc-slug>"

# Multiple documents
yuque-dl doc "<url1>" "<url2>"

Common parameters

Param	Description
-t <token>	cookie value (required for private repos)
-d <dir>	output dir, default download; the tool auto-creates a subfolder per knowledge base
-i	skip images
--hideFooter	don't append a footer (update time, source link)
--incremental	incremental download, only new/updated docs
--ignoreAttachments	skip attachments (suffixes like mp4,pdf)
--toc	output a document tree
-p <password>	password for password-protected public repos

Actual migration result

Item	Count
Knowledge bases	27
Markdown documents	368
Image files	1,026
Total size	318 MB
Time	~4 minutes

Each knowledge base became a folder, preserving the original hierarchy.

Open-source contribution

During the migration I found yuque-dl didn't support exporting all knowledge bases at once, so I opened a PR: PR #102, adding the user and batch subcommands.

File	Change
src/api.ts	added getUserBooks() — calls /api/mine/books to enumerate knowledge bases
src/index.ts	added downloadBooksFromUrls() and downloadAllBooks()
src/cli.ts	registered the batch and user subcommands
README.md	docs and feature checklist

Before the PR is merged, user and batch can be used by forking the repo and building locally.

Pitfalls

1. yuque-dl only accepts knowledge-base URLs, not user-space URLs — https://www.yuque.com/username throws No found book id; you must use https://www.yuque.com/username/repo-slug.
2. API enumeration needs login — api/mine/books returns data only with a cookie, otherwise 401.
3. Cookies expire — _yuque_session has a limited lifetime; if you get 401 mid-batch, re-fetch it.
4. -d is the parent dir — the tool creates a subfolder named after the knowledge base inside it. So -d ./yuque yields ./yuque/thesis/...; don't pass -d ./yuque/thesis or you get ./yuque/thesis/thesis/....
5. Rate-limit yourself — wait 1-2 seconds between knowledge bases during bulk downloads to avoid Yuque's risk control.
6. Proxy caveat — if you set HTTP_PROXY/HTTPS_PROXY, since Yuque is a domestic service add NO_PROXY='yuque.com' to bypass the proxy, or you may get 410.

Ongoing maintenance

• Read in Obsidian: open the export directory as a vault.
• Incremental sync: yuque-dl "url" -t "cookie" -d "dir" --incremental, or once user is merged, yuque-dl user -t "cookie" -d "dir" --incremental.
• Cross-platform migration: Markdown is a universal format, directly importable into Notion, Logseq, etc.