DOCSEARCHbyAlgolia
Submit Docs

feishu2md

repository·main·Indexed 24 days ago

https://github.com/wsine/feishu2md

A Go-based tool to download Feishu (Lark) documents and convert them into Markdown files. It supports exporting single docx documents, entire folders, and Wikis. The tool is available as a CLI and a Docker-based web service, featuring local image downloading and raw JSON response dumping.

Tokens
1.8K
Snippets
2
Records
20
Agent score
81%

What's inside feishu2md

  1. Overview of feishu2md

    main
    feishu2md is a tool written in Go designed to download Feishu (Lark) documents and convert them into Markdown files. It supports downloading individual documents, entire folders, or entire Wikis. It is available as a CLI tool and a Docker-based web service.

  2. Run feishu2md via Docker

    main

    The Docker version provides a web interface. You can run it using a single command or Docker Compose.

    Docker Run:

    docker run -it --rm -p 8080:8080 -e FEISHU_APP_ID=<your id> -e FEISHU_APP_SECRET=<your secret> -e GIN_MODE=release wwwsine/feishu2md

    Docker Compose:

    version: '3'
services:
  feishu2md:
    image: wwwsine/feishu2md
    environment:
      FEISHU_APP_ID: <your id>
      FEISHU_APP_SECRET: <your secret>
      GIN_MODE: release
    ports:
      - "8080:8080"

    Usage:

    1. Start the service: docker compose up -d.
    2. Access https://127.0.0.1:8080 in your browser.
    3. Paste the Feishu document link to download.
    # docker-compose.yml
version: '3'
services:
  feishu2md:
    image: wwwsine/feishu2md
    environment:
      FEISHU_APP_ID: <your id>
      FEISHU_APP_SECRET: <your secret>
      GIN_MODE: release
    ports:
      - "8080:8080"

  3. Configure Feishu API Credentials

    main

    To use feishu2md, you must create a Feishu enterprise self-built application to obtain an APP_ID and APP_SECRET.

    Required Permissions:

    • docx:document:readonly: Get basic document information and all blocks.
    • docs:document.media:download: Download images and attachments.
    • drive:file:readonly: Get file lists from folders.
    • wiki:wiki:readonly: Get knowledge space node information.

    Setup via CLI: Use the config command to generate a configuration file with your credentials:

    feishu2md config --appId <your_id> --appSecret <your_secret>

    To verify your configuration or see the config file path, run:

    feishu2md config

  4. Use feishu2md CLI to download documents

    main

    The CLI version is available for download from the Releases page. Ensure the executable is in your PATH.

    Download a single document

    Provide the Feishu docx URL (obtained via Share > Enable link sharing > Copy link):

    feishu2md dl "https://domain.feishu.cn/docx/docxtoken"

    Batch download a folder

    Downloads all documents within a specific folder. Note: This feature is not supported in the Docker version.

    feishu2md dl --batch -o output_directory "https://domain.feishu.cn/drive/folder/foldertoken"

    Batch download a Wiki

    Downloads all documents within a Wiki using the Wiki settings URL.

    feishu2md dl --wiki -o output_directory "https://domain.feishu.cn/wiki/settings/123456789101112"

  5. Configure download output and behavior

    main

    The download process is governed by a configuration file (loaded via core.ReadConfigFromFile). Key behaviors include:

    • Output Directory: Files are saved to the directory specified in the configuration.
    • Title as Filename: If TitleAsFilename is enabled in the config, the output .md file will use the document's title (sanitized) instead of the document token.
    • Image Handling: If SkipImgDownload is false, the tool will download images locally and update the Markdown links to point to the local files. Images are stored in the directory specified by ImageDir in the config.
    • JSON Dump: Using the --dump flag will also save the raw JSON response from the Feishu API (containing the document and blocks) as a .json file named after the document token.

  6. Use the download command to export Feishu content

    main

    The download command allows you to convert Feishu documents, folders, or Wikis into Markdown files. Depending on the flags used, it can handle single documents, entire drive folders, or entire Wiki spaces.

    Supported modes:

    • Single Document: Provide a direct document URL. The tool will download the content and save it as a .md file.
    • Batch Folder Download: Use the --batch flag with a folder URL to recursively download all docx files within that folder and its subfolders.
    • Wiki Download: Use the --wiki flag with a Wiki URL to recursively traverse the Wiki structure and download all docx nodes.

    Note: Feishu 'Docs' (the legacy format) is no longer supported. The tool focuses on docx type content.

  7. CLI Command Reference

    main

    The feishu2md CLI supports the following commands and options:

    Commands:

    • config: Read config file or set fields (--appId, --appSecret).
    • download, dl: Download documents.
    • help, h: Show help.

    dl (download) Options:

    • --output, -o <value>: Specify the output directory (default: ./).
    • --dump: Dump JSON response of the OPEN API.
    • --batch: Download all documents under a folder.
    • --wiki: Download all documents within the wiki.

  8. Initialize a new Client with NewClient

    main
    Use NewClient to create a new *Client instance. You must provide your Feishu appID and appSecret. The client is pre-configured with a 60-second timeout and a rate limiter (4 requests per 4 seconds) to handle API limits gracefully.

  11. Download Feishu/Larksuite documents to Markdown

    main
    Use the download command (or its alias dl) to convert Feishu/Larksuite documents, folders, or wikis into Markdown files. You must provide the document/folder/wiki URL as a positional argument.

  12. Manage configuration with the config command

    main

    The config command allows you to view, initialize, or update your Feishu API credentials.

    • If no configuration file exists: The command will create a new configuration file at the default path (retrieved via core.GetConfigFilePath()) using the provided appId and appSecret.
    • If a configuration file exists: The command will read the existing file. If you provide an appId or appSecret via the command line, these values will overwrite the existing ones in the file.

    After execution, the command prints the current configuration in a pretty-printed format.