{"id":23040753,"url":"https://github.com/longbridge/feishu-pages","last_synced_at":"2025-05-16T10:05:43.498Z","repository":{"id":191671498,"uuid":"684021855","full_name":"longbridge/feishu-pages","owner":"longbridge","description":"Generate Feishu Wiki into a Markdown for work with Static Page Generators.","archived":false,"fork":false,"pushed_at":"2024-12-10T03:47:34.000Z","size":692,"stargazers_count":190,"open_issues_count":10,"forks_count":23,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-01T14:52:18.189Z","etag":null,"topics":["feishu","feishu-openapi","github-pages","larksuite","markdown","static-page-generator"],"latest_commit_sha":null,"homepage":"https://longbridge.github.io/feishu-pages/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/longbridge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-28T09:35:28.000Z","updated_at":"2025-04-01T05:17:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"a8e45284-b1a2-4443-93d6-1f5023ef9e14","html_url":"https://github.com/longbridge/feishu-pages","commit_stats":{"total_commits":224,"total_committers":5,"mean_commits":44.8,"dds":"0.022321428571428603","last_synced_commit":"e375af1e932b26c70cdbc6afd8b62009fb0503e7"},"previous_names":["longbridgeapp/feishu-pages","longbridge/feishu-pages"],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbridge%2Ffeishu-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbridge%2Ffeishu-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbridge%2Ffeishu-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbridge%2Ffeishu-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/longbridge","download_url":"https://codeload.github.com/longbridge/feishu-pages/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247974715,"owners_count":21026742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["feishu","feishu-openapi","github-pages","larksuite","markdown","static-page-generator"],"created_at":"2024-12-15T19:07:39.039Z","updated_at":"2025-04-09T04:05:11.232Z","avatar_url":"https://github.com/longbridge.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Feishu Pages\n\n导出**飞书知识库**，并按相同目录结构生成 [Static Page Generator](https://www.google.com/search?q=Static+Page+Generator) 支持 Markdown 文件组织方式，用于发布为静态网站。\n\n借用飞书文档较好的撰写能力，让不懂 Markdown 和 Git 的非技术人员可以轻松撰写文档，并也最终以静态页面生成的方式来部署文档。这样我们依然可以继续保持 CI 流程和 GitHub PR 的方式来 Review 文档变更。\n\n\u003e 可以访问此文档的 [原始飞书知识库](https://longbridge.feishu.cn/wiki/space/7273324757679325186) 对比看一下。\n\n## Features\n\n- [feishu-docx](https://github.com/longbridge/feishu-pages/tree/main/feishu-docx) - 支持将飞书新版文档 Docx 转换为 Markdown 或其他格式（_目前只支持 Markdown_）\n- 目录结构组织，与 URL 路径自定义\n- 图片、附件下载\n- 国际化支持\n- 与 GitHub Actions 结合\n- 生成支持 [Docusaurus](https://docusaurus.io/) 支持的 MDX 格式的 Meta 信息，以实现目录结构组织（基于 `sidebar_position`）\n\n## Prepare\n\n\u003e 📌 在开始使用之前，必须先完成飞书开放平台的配置工作，获得一些必要的信息，和配置必要的权限，请认真阅读完此页再继续。\n\n### **创建飞书应用并开通权限**\n\n1. 请访问 [https://open.feishu.cn/app](https://open.feishu.cn/app) 创建一个新应用，并获得：\n\n   - `App ID`\n   - `App Secret` - 请注意保管 App Secret，不要泄露到互联网。\n\n2. 为应用开启 `机器人` 应用能力。\n3. 为应用开启 `docx:document:readonly` 和 `wiki:wiki:readonly` 权限。\n4. 将应用发布正式版本，并确保审批通过。\n5. 在飞书 IM 中创建新群 `Feishu Pages`，将应用添加为该群机器人，知识库管理员在「知识空间设置」-\u003e 「权限设置」-\u003e「添加管理员」中添加，把这个 `Feishu Pages` 群加成 **管理员**。\n   - 否则会遇到 `permission denied: wiki space permission denied` 错误。 [ref](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa)\n\n## **Feishu Permissions**\n\n你的飞书应用需要开通下面几个权限，工具通过飞书 API 访问必须要这几项。\n\n- `docx:document:readonly`\n- `wiki:wiki:readonly`\n- `drive:drive:readonly`\n- `board:whiteboard:node:read`\n\n### **获取飞书知识库 \\*\\***space_id\\*\\*\n\n我们需要配置 `FEISHU_SPACE_ID` 的环境变量，这个为飞书知识库的 `space_id`，你可以访问知识库设置界面，从 URL 中获取。\n\n例如：`https://your-company.feishu.cn/wiki/settings/6992046856314306562` 这里面 `6992046856314306562` 为 `space_id`。\n\n### **环境变量配置**\n\nFeishu Pages 支持 `.env` 文件，如果执行的根目录有个 `.env` 文件，将会自动读取。\n\n\u003e 请参考 `.env.default` 配置环境变量。\n\n如需在 GitHub Actions 的 CI 流程里面使用，建议添加到 Secrets 中，再通过环境变量的方式获取。\n\n## Installation\n\nFeishu Pages 可以以 NPM 的方式引入到 Static Page Generator 的项目中。\n\n例如我们有一个 [Docusaurus](https://docusaurus.io) 的静态页面网站项目。\n\n```bash\ncd your-project/\nyarn add feishu-pages\n```\n\n然后你就可以执行 `yarn feishu-pages` 来生成页面了。\n\n在运行此命令之前，必须先完成飞书开放平台的配置工作，获得一些必要的信息，和配置必要的权限，请继续阅读完此页再继续。\n\n## Configuration\n\n我们可以通过环境变量（ENV）来配置 feishu-pages 需要的必要参数，这样你可以轻易在 GitHub Actions 之类的流程中使用 feishu-pages。\n\n\u003e 如果你想简单一些，也可以用 `.env` 文件来配置环境变量，注意避免 `FEISHU_APP_SECRET` 泄露到互联网。\n\n| Name                | Description                                                                                                                                                      | Required | Default                |\n| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------- |\n| `FEISHU_ENDPOINT`   | 飞书 API 节点，如用 LarkSuite 可以通过这个配置 API 地址                                                                                                          | NO       | https://open.feishu.cn |\n| `FEISHU_APP_ID`     | 飞书应用 ID                                                                                                                                                      | YES      |                        |\n| `FEISHU_APP_SECRET` | 飞书应用 Secret                                                                                                                                                  | YES      |                        |\n| `FEISHU_SPACE_ID`   | 飞书知识库 ID                                                                                                                                                    | YES      |                        |\n| `OUTPUT_DIR`        | 输出目录                                                                                                                                                         | NO       | `./dist`               |\n| `ROOT_NODE_TOKEN`   | 根节点，导出节点以下（不含此节点）的所有内容。                                                                                                                   | NO       |                        |\n| `BASE_URL`          | 自定义文档里面相关文档输出的 URL 前缀，例如：`/docs/`，默认为 `/`，建议采用完整 URL 避免相对路径的各类问题。                                                     | NO       | `/`                    |\n| `ROOT_NODE_TOKEN`   | 从哪个节点 (node_token) 开始导出，例如：`6992046856314306562`，默认为空，走根节点开始。                                                                          | NO       |                        |\n| `URL_STYLE`         | 导出的文档 URL 风格。\u003cbr/\u003e\u003cbr/\u003e- `nested` - 采用层级的 URL 结构，如 `/foo/bar/dar`。\u003cbr/\u003e- `original` - 采用一层的 URL 结构，如 `/X80QwaYvjiMWZrk399YcK4q8nCc`。 | NO       | `relative`             |\n\n## Usage\n\n### 从知识库导出 Markdown 文档\n\n当你撰写完成文档以后，可以通过 `yarn feishu-pages` 命令来实现导出，这个命令作用是通过飞书 API 访问你 `FEISHU_SPACE_ID` 对应的知识库，并依次将所有文档导出，并转换为 Markdown 文件。\n\n```bash\ncd your-project/\nyarn feishu-pages\n```\n\n按上面默认的配置，最终会在 `./dist` 目录下生成 Markdown 文件以及导出的图片文件，如果你期望调整目录，可以自己设置 `OUTPUT_DIR` 环境变量。\n\n\u003e 💡 文档内 [Page Mata](https://longbridge.github.io/feishu-pages/zh-CN/page-meta) 标识为 `hide: true` 的文档将会被排除掉，你可以用来隐藏一些不想公开的文档。\n\u003e\n\u003e 所有的 Markdown 导出的文件名将遵循知识库的目录树，并按照 Page Meta 里面的 `slug` 来整理文件夹和文件名。\n\n## GitHub Actions 集成\n\n创建一个 `.github/workflows/feishu-pages.yml` 文件，内容如下：\n\n\u003e NOTE: 你需要用到 VitePress 或 Docusaurus 之类的文档工具，这里假设他们在项目根目录有 `yarn build` 命令可以将 `docs` 文件夹的 Markdown 文件生成为静态网站。\n\u003e\n\u003e 具体可以参考：https://github.com/longbridge/feishu-pages/tree/main/website\n\n```yml\non:\n  push:\n    branches:\n      - main\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\njobs:\n  feishu-pages:\n    name: Feishu Pages Export\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/cache@v3\n        with:\n          path: dist/.cache\n          key: cache-dist\n      - name: Exporting\n        env:\n          FEISHU_APP_ID: ${{ secrets.FEISHU_APP_ID }}\n          FEISHU_APP_SECRET: ${{ secrets.FEISHU_APP_SECRET }}\n          FEISHU_SPACE_ID: ${{ secrets.FEISHU_SPACE_ID }}\n        uses: longbridge/feishu-pages@main\n      - name: Build Pages\n        run: |\n          cp -r dist/docs ./\n          cp dist/docs.json ./\n          yarn\n          yarn build\n      - name: Setup Pages\n        uses: actions/configure-pages@v3\n      - name: Upload artifact\n        uses: actions/upload-pages-artifact@v2\n        with:\n          path: \"./website/.vitepress/dist\"\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v2\n```\n\n## 常见问题\n\n### Rate Limit 相关错误\n\n\u003e Error: request trigger frequency limit\n\n飞书 API 有总每分钟 100 次请求的[总频率限制](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)，这个项目实现的时候为每个请求之前做了 300ms 的延迟，以避免超过这个频率。如有遇到此类问题，请提交 Issue。\n\n### 画板图片导出会有空白区域\n\n这个是由于飞书画板导出图片本身的问题，如果你使用 feishu-pages 提供的 GitHub Actions，这个里面会用 ImageMagick 来修复这些图片。如果你是手工导出的，可以用下面的命令来修复（请先安装 [ImageMagick](https://www.imagemagick.org)）：\n\n```bash\nfind ./dist -name \"*-board.png\" -exec mogrify -trim {} +\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongbridge%2Ffeishu-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flongbridge%2Ffeishu-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongbridge%2Ffeishu-pages/lists"}