快速开始
slug: gettting-started
导出飞书知识库,并按相同目录结构生成 Static Page Generator 支持 Markdown 文件组织方式,用于发布为静态网站。
借用飞书文档较好的撰写能力,让不懂 Markdown 和 Git 的非技术人员可以轻松撰写文档,并也最终以静态页面生成的方式来部署文档。这样我们依然可以继续保持 CI 流程和 GitHub PR 的方式来 Review 文档变更。
可以访问此文档的 原始飞书知识库 对比看一下。
[!TIP] GitHub 项目地址:https://github.com/longbridge/feishu-pages
整体流程
Features
- feishu-docx - 支持将飞书新版文档 Docx 转换为 Markdown 或其他格式(目前只支持 Markdown)
- 支持绝大部分常用的文档格式,以及完整的目录结构导出,详见:支持的内容格式
- URL 路径自定义
- 图片、附件下载
- 国际化支持
- 与 GitHub Actions 结合
- 生成支持 Docusaurus 支持的 MDX 格式的 Meta 信息,以实现目录结构组织(基于
sidebar_position
) - 飞书画板图片导出(since v0.7.0)
Prepare
[!TIP] 在开始使用之前,必须先完成飞书开放平台的配置工作,获得一些必要的信息,和配置必要的权限,请认真阅读完此页再继续。
创建飞书应用并开通权限
-
请访问 https://open.feishu.cn/app 创建一个新应用,并获得:
-
App ID
- 飞书应用编号 App Secret
- 请注意保管 App Secret,不要泄露到互联网。- 为应用开启
机器人
应用能力。 - 为应用开启
docx:document:readonly
和wiki:wiki:readonly
权限。 - 将应用发布正式版本,并确保审批通过。
-
在飞书 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 的静态页面网站项目。
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 文件。
cd your-project/
yarn feishu-pages
按上面默认的配置,最终会在 ./dist
目录下生成 Markdown 文件以及导出的图片文件,如果你期望调整目录,可以自己设置 OUTPUT_DIR
环境变量。
[!TIP] 文档内 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):
find ./dist -name "*-board.png" -exec mogrify -trim {} +
License
MIT