Feishu Wiki To Docusaurus Migration Design

Summary

Build a new Docusaurus documentation site from the Feishu wiki subtree rooted at NclNwZsMKi2L07kpYW1czK9Nnv7 as a one-time snapshot migration.

Scope

• Source: the full Feishu wiki subtree under NclNwZsMKi2L07kpYW1czK9Nnv7
• Current observed size: 39 wiki nodes, up to 3 levels deep
• Output: a local Docusaurus project with imported docs and local image assets
• Migration mode: one-time snapshot only

Explicit Decisions

• Tree-internal Feishu links become site-internal routes
• Tree-external Feishu links remain external Feishu links
• Images are migrated into local static assets
• File attachments such as installers, archives, and packages are not migrated
• If an attachment appears in content, keep its original external link instead of downloading it
• Do not build sync, CMS editing, permission mirroring, comment migration, or attachment archival

Goals

• Preserve document hierarchy from the Feishu wiki tree
• Preserve readable content including headings, paragraphs, lists, tables, code blocks, and links
• Make migrated images work without depending on Feishu temporary asset URLs
• Produce a Docusaurus project that builds locally with standard commands

Non-Goals

• Pixel-perfect reproduction of Feishu document rendering
• Automatic incremental sync from Feishu
• Migration of comments, reactions, permissions, or embedded app state
• Import of non-image attachments into the site

Architecture

Content Source

The importer reads the wiki tree recursively from the root node token. Each node is resolved to its underlying docx object and fetched as Markdown content.

Importer

A local one-time importer script will:

1. Walk the wiki tree and collect node metadata
2. Build a stable mapping from node_token to target doc path and route slug
3. Fetch each document body as Markdown
4. Rewrite links based on the node mapping
5. Download supported image assets into the local static directory
6. Skip non-image attachments while preserving their original external links
7. Write docs files and sidebar metadata
8. Emit a summary of migrated items and failures

Site

The generated content is hosted by the Docusaurus docs plugin. The site keeps the wiki hierarchy through nested doc folders and sidebar categories.

File Structure

Planned project structure:

docs/
  intro.md
  getting-started/
  tools/
  help-center/
  api/
static/
  img/
    feishu/
scripts/
  import-feishu-wiki.mjs
  lib/
    feishu-client.mjs
    normalize-title.mjs
    rewrite-links.mjs
    download-assets.mjs
docusaurus.config.ts
sidebars.ts
package.json

Notes:

• docs/ stores the migrated Markdown pages
• static/img/feishu/ stores downloaded images
• scripts/import-feishu-wiki.mjs orchestrates the one-time migration
• scripts/lib/ contains small focused helpers only as needed

Document Generation Rules

Paths And Slugs

• Each wiki node becomes one Markdown document
• Folder structure follows the wiki tree structure
• File and folder names use normalized slugs derived from titles
• Front matter includes at least:
  • title
  • slug
  • optional sidebar metadata when needed

Link Rewriting

• If a link target points to a node inside the migrated subtree, rewrite it to the generated site route
• If a link target points outside the subtree, keep the original Feishu URL
• If a link cannot be resolved confidently, leave it as the original URL

Images

• Download image assets referenced by the document content
• Store images under static/img/feishu/ with stable generated filenames
• Rewrite document references to local static paths
• If an image download fails, leave the original URL in the document and report the failure

Attachments

• Do not download or store installers, zip files, archives, or other non-image attachments
• Keep original external links for those assets when present in the Markdown

Sidebar Strategy

• Generate sidebars.ts from the collected tree structure
• Preserve category nesting to match the source wiki tree
• Keep the root landing page discoverable as the default entry point

Error Handling

• If one document fetch fails, continue migrating the rest and report the failed node at the end
• If one image download fails, continue the document migration and keep the original image URL
• If unsupported resource types appear, skip them and report them in the importer summary

Verification

Success is defined by the following checks:

1. The importer runs to completion and reports one output document per wiki node
2. The generated site passes npm run build
3. Manual spot checks confirm:
   • root landing page renders
   • nested categories under tool deployment render
   • API docs render
   • at least one page with images renders correctly
   • at least one page with tables and code blocks renders correctly
   • tree-internal links point to site routes
   • tree-external links still point to Feishu
   • attachment files were not imported into the site

Risks

• Some Feishu Markdown may need cleanup for Docusaurus compatibility
• Temporary or protected Feishu asset URLs may fail during download and require fallback handling
• Title normalization must avoid collisions between similarly named pages

Implementation Boundary

This design only covers the one-time migration path and the resulting Docusaurus project. It intentionally excludes ongoing synchronization and broader content platform concerns.