在 Orbit 中查看您的项目 README

Docs 标签页在 KPanel 内渲染您的仓库 README，使项目的文档距离其部署只有一次点击，而不是在某个需要去查找的浏览器标签页中。

Docs 标签页的位置

打开 Orbit，点击项目，然后在项目标签页条的 Overview 组下选择 Docs。

无需配置任何内容。如果项目有连接的仓库且其根目录下有 README，该标签页会渲染它。

显示哪个文件

Orbit 从连接仓库的默认分支获取 README。

在 GitHub 上，它依次尝试多个常规名称：README.md、readme.md、README.MD、README 和 readme.txt，使用首个存在的文件。在 GitLab 和 Bitbucket 上，它查找 README.md。

仅检查仓库根目录。子目录内的 README（包括 monorepo 应用的根目录）不会被识别。

渲染内容

README 作为 markdown 渲染：标题、列表、表格、链接、行内代码和代码块都会按预期显示。

README 内的相对图像路径指向仓库，不是指向 KPanel，因此在您供应商自有网站上有效的图像可能在此处无法解析。如果图像很重要，请使用绝对 URL。

空状态

当没有内容显示时，两种状态会替换内容：

• 未连接仓库，带有 Connect repository 按钮。先连接一个：参见连接 GitHub 仓库、连接 GitLab 仓库或连接 Bitbucket 仓库。
• 未找到 README，提示您向仓库根目录添加 README.md，并提供在您供应商上创建该文件的链接。

两者都会链接到供应商，便于您立即采取行动，而已填充的视图则提供一个 View on 链接指向该文件本身，供您需要编辑时使用。

编写值得渲染的 README

由于此标签页与部署历史相邻，Orbit 项目最有用的 README 是操作性的。有人打开它是因为他们刚接手该项目，需要安全地更改某些内容。

可行的结构：

这是什么。 一个段落。项目的功能以及它服务的对象。

在本地运行。 确切的命令，包括包管理器。pnpm install && pnpm dev 优于描述相同内容的段落。

环境变量。 存在哪些变量及各自的用途。绝不是这些值：这些值属于项目的环境变量，不属于仓库中的文件。参见 Orbit 中的环境变量。

它如何部署。 生产分支是哪一个、是否部署标签，以及有哪些限制条件。指向 Orbit 部署管道标签页而不是复制它，因为该标签页不会过时而您的 README 会。

如何回滚。 两句话和指向回滚部署的链接。这是人们在最困难时刻需要的东西，应该放在他们会查找的地方。

谁拥有它。 一个团队或一个人。项目的生命周期比建立它的人更长。

添加实时状态徽章

由于 README 在此处和您的供应商上渲染，添加部署状态徽章值得考虑。Orbit 为每个项目发布一个。

打开 Settings，找到 Status badge 卡片。它显示实时预览和三个复制按钮：徽章 URL、markdown 片段和 HTML 片段。将 markdown 粘贴到您的 README 顶部。

徽章是一个小 SVG，报告项目生产环境的当前状态：deployed、building、failed、queued 或 no deployments。无需身份验证，因此任何读取仓库的人都能看到它，并且它链接回 KPanel 中的项目。

这使您拥有一份 README，可以一目了然地显示生产环境当前是否健康。这是您可以添加到它的单行中最高价值的内容。

保持诚实

描述项目不再具有的设置的 README 比没有 README 更差，因为人们相信它。两个习惯能保持其准确性：

• 链接而不是复制。 KPanel 中可见的任何内容，例如构建设置、限制条件和环境配置，都应该被链接到，而不是重述。
• 在同一个拉取请求中更新它。 如果更改改变了项目的运行方式，README 更改应该在该拉取请求中，而不是在之后的整理中。

故障排除

标签页显示旧版本。 五分钟缓存。等待并重新加载。

未找到 README，但有一个。 检查它是否在仓库根目录，名称是否为 README.md。在 GitLab 和 Bitbucket 上，名称必须完全匹配。

仓库已连接，但标签页说未连接。 连接可能已失去访问权限，例如如果集成在供应商端被移除。从项目设置重新连接它。

图像无法加载。 相对路径在此处不会解析。使用绝对 URL。

徽章显示无部署。 生产环境从未有过成功的部署。部署一次，它就会更新。

后续步骤

• Orbit 部署管道，README 通常尝试描述的实时版本。
• Orbit 项目设置用于状态徽章和其余配置。
• Orbit 中的环境变量用于 README 必不可少的值。