Feishu Pages

简体中文

English

简体中文

English

Appearance

快速开始 ​

导出飞书知识库，并按相同目录结构生成 Static Page Generator 支持 Markdown 文件组织方式，用于发布为静态网站。

借用飞书文档较好的撰写能力，让不懂 Markdown 和 Git 的非技术人员可以轻松撰写文档，并也最终以静态页面生成的方式来部署文档。这样我们依然可以继续保持 CI 流程和 GitHub PR 的方式来 Review 文档变更。

可以访问此文档的 原始飞书知识库 对比看一下。

🍏

GitHub 项目地址：https://github.com/longbridgeapp/feishu-pages

整体流程 ​

Features ​

  • feishu-docx - 支持将飞书新版文档 Docx 转换为 Markdown 或其他格式（目前只支持 Markdown）
  • 支持绝大部分常用的文档格式，以及完整的目录结构导出，详见：支持的内容格式
  • URL 路径自定义
  • 图片、附件下载
  • 国际化支持
  • 与 GitHub Actions 结合
  • 生成支持 Docusaurus 支持的 MDX 格式的 Meta 信息，以实现目录结构组织（基于 sidebar_position）
  • 飞书画板图片导出（since v0.7.0)

Prepare ​

📌

在开始使用之前，必须先完成飞书开放平台的配置工作，获得一些必要的信息，和配置必要的权限，请认真阅读完此页再继续。

创建飞书应用并开通权限 ​

  1. 请访问 https://open.feishu.cn/app 创建一个新应用，并获得：

    • App ID - 飞书应用编号
    • App Secret - 请注意保管 App Secret，不要泄露到互联网。

  2. 为应用开启 机器人 应用能力。

  3. 为应用开启 docx:document:readonly 和 wiki:wiki:readonly 权限。

  4. 将应用发布正式版本，并确保审批通过。

  5. 在飞书 IM 中创建新群 Feishu Pages，将应用添加为该群机器人，知识库管理员在「知识空间设置」-> 「权限设置」->「添加管理员」中添加，把这个 Feishu Pages 群加成 管理员。

    • 否则会遇到 permission denied: wiki space permission denied 错误。 ref

Feishu Permissions ​

你的飞书应用需要开通下面几个权限，工具通过飞书 API 访问必须要这几项。

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

获取飞书知识库 space_id ​

我们需要配置 FEISHU_SPACE_ID 的环境变量，这个为飞书知识库的 space_id，你可以访问知识库设置界面，从 URL 中获取。

例如：https://your-company.feishu.cn/wiki/settings/6992046856314306562 这里面 6992046856314306562 为 space_id。

环境变量配置 ​

Feishu Pages 支持 .env 文件，如果执行的根目录有个 .env 文件，将会自动读取。

请参考 .env.default 配置环境变量。

如需在 GitHub Actions 的 CI 流程里面使用，建议添加到 Secrets 中，再通过环境变量的方式获取。

Installation ​

Feishu Pages 可以以 Npm 的方式引入到 Static Page Generator 的项目中。

例如我们有一个 Docusaurus 的静态页面网站项目。

bash
cd your-project/
yarn add feishu-pages

然后你就可以执行 yarn feishu-pages 来生成页面了。

Configuration ​

我们可以通过环境变量（ENV）来配置 feishu-pages 需要的必要参数，这样你可以轻易在 GitHub Actions 之类的流程中使用 feishu-pages。

如果你想简单一些，也可以用 .env 文件来配置环境变量，注意避免 FEISHU_APP_SECRET 泄露到互联网。

Name

Description

Required

Default

FEISHU_ENDPOINT

飞书 API 地址，默认是飞书国内版

飞书国际版，请配置：
https://open.larksuite.com

NO

https://open.feishu.cn

FEISHU_APP_ID

飞书应用 ID

YES

FEISHU_APP_SECRET

飞书应用 Secret

YES

FEISHU_SPACE_ID

飞书知识库 ID

YES

ASSET_BASE_URL

资源文件（图片、附件）的 Base URL
通过这个配置配置 img src 的 URL 前缀

NO

/assets

OUTPUT_DIR

输出目录

NO

./dist

BASE_URL

自定义文档里面相关文档输出的 URL 前缀，例如：/docs/，默认为 /
建议采用完整 URL 避免各种相对路径的问题。
e.g.: https://your-host.com/docs

NO

/

ROOT_NODE_TOKEN

从哪个节点开始导出，值为 NODE_TOKEN （例如：XpKYwA6oqiGMfFkLVwCcwykunzV）可以从知识库 URL 里面找到。
例如：/wiki/XpKYwA6oqiGMfFkLVwCcwykunzV
默认为空，走知识库的根节点开始。

NO

Usage ​

导出文档 ​

当你撰写完成文档以后，可以通过 yarn feishu-pages 命令来实现导出，这个命令作用是通过飞书 API 访问你 FEISHU_SPACE_ID 对应的知识库，并依次将所有文档导出，并转换为 Markdown 文件。

bash
cd your-project/
yarn feishu-pages

按上面默认的配置，最终会在 ./dist 目录下生成 Markdown 文件以及导出的图片文件，如果你期望调整目录，可以自己设置 OUTPUT_DIR 环境变量。

💡

文档内 Page Mata 标识为 hide: true 的文档将会被排除掉，你可以用来隐藏一些不想公开的文档。

所有的 Markdown 导出的文件名将遵循知识库的目录树，并按照 Page Meta 里面的 slug 来整理文件夹和文件名。

Cache ​

在 ${OUTPUT_DIR}/.cache 文件夹内，存放了导出的缓存，由于优化 feishu-pages 的导出过程。

默认情况下，你不需要在意这个，仅需在 CI 流程里面将此文件夹配置好 CI Cache 即可。详见：GitHub Actions

如果发现导出异常，Cache 不符合预期，请提交 Issue，并删除此文件夹即可。

常见问题 ​

Rate Limit 相关错误 ​

Error: request trigger frequency limit

飞书 API 有总每分钟 100 次请求的总频率限制，这个项目实现的时候为每个请求之前做了 300ms 的延迟，以避免超过这个频率。如有遇到此类问题，请提交 Issue。

画板图片导出会有空白区域 ​

这个是由于飞书画板导出图片本身的问题，如果你使用 feishu-pages 提供的 GitHub Actions，这个里面会用 ImageMagick 来修复这些图片。

如果你是手工导出的，可以用下面的命令来修复（请先安装 ImageMagick）：

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

License ​

MIT