Getting Started

Export Feishu Knowledge Base and generate the same directory structure Static Page Generator supports Markdown file organization for publishing as a static website.

Borrowing the good writing ability of Feishu Docs, non-technical personnel who do not understand Markdown and Git can easily write documents, and ultimately deploy documents in the form of static page generation. In this way, we can continue to maintain the CI process and GitHub PR to review document changes.

You can visit the original Feishu Wiki for a comparison of this document.

🍏

GitHub Repo: https://github.com/longbridgeapp/feishu-pages

Overall process

Features

• Feishu-docx - Support to convert Feishu new document Docx to Markdown or other formats ( currently only supports Markdown )
• Supports most commonly used document formats, as well as complete directory structure export, see: Supported Formats
• URL path customization
• Download images and attachments
• Internationalization support
• Integration with GitHub Actions
• Generate Meta information in MDX format supported by Docusaurus for directory structure organization (based on sidebar_position )
• Export Artboard as Image (since v0.7.0)

Prepare

📌

Before starting to use Feishu Open Platform, you must first complete the configuration work, obtain some necessary information, and configure the necessary permissions. Please read this page before continuing.

Create Feishu app and grant permissions

1. Visit https://open.feishu.cn/app Create a new app and get:

   • App ID - App ID of Feishu Open Platform.
   • App Secret - Please take care to keep the App Secret and do not leak it to the Internet.

2. Enable the robot application capability for the application.

3. Enable the docx: document: readonly and wiki: wiki: readonly permissions for the app.

4. Release the official version of the application and ensure approval .

5. Create a new group Feishu Pages in Feishu IM, add the application as the group bot, the Knowledge Base administrator adds it in "Wiki Workspace Settings" - > "Permission Settings" - > "Add Administrator", and add this Feishu Pages group as an administrator .

   • Otherwise you will encounter permission denied: wiki space permission denied error. ref

Feishu Permissions

Your Feishu application requires the following permissions, which are required for tools to access through the Feishu API.

• docx:document:readonly
• wiki:wiki:readonly
• drive:drive:readonly
• board:whiteboard:node:read

Get the Feishu Knowledge Base space_id

We need to configure FEISHU_SPACE_ID environment variables, which is the space_id of Feishu Knowledge Base. You can access the Knowledge Base settings interface and get it from the URL.

For example: https://your-company.feishu.cn/wiki/settings/6992046856314306562 here 6992046856314306562 for space_id .

Environment variables configuration

Feishu Pages supports .env files, if the root directory has a .env file, it will be automatically read.

Please refer to .env.default to configure environment variables.

If you need to use it in the CI process of GitHub Actions, it is recommended to add it to Secrets and get it through environment variables.

Installation

Feishu Pages can be imported into the Static Page Generator project as an Npm.

For example, we have a static page website project for Docusaurus .

cd your-project/
yarn add feishu-pages

Then you can execute yarn feishu-pages to generate pages.

Configuration

We can configure the necessary parameters required by feishu-pages through environment variables (ENV), so that you can easily use feishu-pages in processes such as GitHub Actions.

If you want to keep it simple, you can also use .env files to configure environment variables, taking care to avoid leaking FEISHU_APP_SECRET to the Internet.

Name	Description	Required	Default
FEISHU_ENDPOINT	Feishu API Endpoint For LarkSuite you can use: https://open.larksuite.com	NO	https://open.feishu.cn
FEISHU_APP_ID	Feishu App ID	YES
FEISHU_APP_SECRET	Feishu App Secret	YES
FEISHU_SPACE_ID	Feishu Knowledge Base ID	YES
ASSET_BASE_URL	Base URL of resource files (images, attachments), configure the URL prefix of img src through this configuration	NO	/assets
OUTPUT_DIR	Output directory	NO	./dist
BASE_URL	Special the relative doc URL prefix, e.g. /docs/. Default is / Recommended to use the full URL to avoid relative path problems. e.g.: https://your-host.com/docs	NO	/
ROOT_NODE_TOKEN	From which node to start exporting, the value is NODE_TOKEN (for example: XpKYwA6oqiGMfFkLVwCcwykunzV ) can be found in the Knowledge Base URL. For example: /wiki/XpKYwA6oqiGMfFkLVwCcwykunzV The default is empty, starting from the root node of Knowledge Base.	NO

Usage

Exporting Docs

After you finish writing the document, you can export it through the yarn feishu-pages command, which accesses your corresponding Knowledge Base through the Feishu API FEISHU_SPACE_ID and exports all documents in turn, and converts them into Markdown files.

cd your-project/
yarn feishu-pages

According to the default configuration above, Markdown files and exported image files will be generated in the ./dist directory. If you want to adjust the directory, you can set OUTPUT_DIR environment variables yourself.

💡

Documents with Page Mata marked as hide: true in the document will be excluded, and you can use it to hide some documents that you do not want to make public.

All Markdown exported filenames will follow the Knowledge Base directory tree and organize folders and filenames according to the slug in Page Meta.

Cache

In the ${OUTPUT_DIR}/.cache folder, the exported cache is stored, due to the optimization of the export process of feishu-pages.

By default, you don't need to care about this, just configure this folder with CI Cache in the CI process. See: GitHub Actions

If an export exception is found and the Cache does not meet expectations, please submit the issue and delete this folder.

FAQs

Rate Limit Related Errors

Error: request trigger frequency limit

The Feishu API has a total frequency limit of 100 requests per minute. This project implements a delay of 300ms before each request to avoid exceeding this frequency. If you encounter such problems, please submit an issue.

There will be a blank area when exporting the artboard image.

This is due to an issue with exporting images from Feishu Artboard. If you use GitHub Actions provided by Feishu-pages, ImageMagick will be used to fix these images.

If you exported it manually, you can fix it with the following command (please install ImageMagick first):

find ./dist -name "*-board.png" -exec mogrify -trim {} +

License

MIT