Avgeek OSS 混合文件
共享Mintlify主页布局,文档原始,以及Avgeek OSS项目的站点工具. 产品储存库拥有其内容、品牌、导航目的地、截图、API计划、分析和法律网页.
Mintlify自定义组件不能导入外部 npm 包 。 这个工具包作为开发工具安装,并生成本地JSX片段,CSS,JavaScript,以及 docs.json 让Mintlify直接服役。 提交生成的文件 。 CI对照精确安装的套件来检查,所以编辑不能无声地漂移.
安装和使用
使用节点.js 26和pnpm 11. 该软件包在npmjs.org上公开,不需要注册证书.
pnpm add -Dw @avgeek-oss/[email protected]
移民时 @avgeek-oss/docs添加 @avgeek-oss/mintlify-docs,并更新脚本以使用 mintlify-docs CLI(英语:CLI). 更改任何 @avgeek-oss 登记映射到 https://registry.npmjs.org 并刷新锁文件。 生成的文件名和片段导入路径保持不变 。 运行 docs:sync 以更新他们的软件包元数据.
创建产品自有 docs/site.json它需要 name, (中文(简体) ), colors (单位:千美元)primary, (中文(简体) ), light 财务报告和审定财务报表 dark, (中文(简体) ), navigation页:1 navbar.primary CTA 和 footer.links· ; 导航和站点配置 描述每个。 所有额外的本地密特利尼选项都保留了下来.
{
"scripts": {
"docs:sync": "mintlify-docs sync --config docs/site.json --dir docs",
"docs:check": "mintlify-docs check --config docs/site.json --dir docs --content",
"docs:validate": "mintlify-docs validate --dir docs"
}
}
运行 pnpm docs:sync,输入其输出并运行 pnpm docs:check 财务报告和审定财务报表 pnpm docs:validate 在中央情报局。 升级后重复被绑的套件. 只同步其声明生成的文件和 assets 所列副本 site.json;它留下了产品页和本地风格未受影响. --content 还检查导航页,MDX,前题,路由,定向,内部链接,锚和截图大小. validate 运行Mintlify的验证,断开链接和与CLI版本的可访问性检查套接字. 见 站点工具 对于资产,导航包括:, {version} 和内容检查.
脚本可以导入 syncSite, (中文(简体) ), checkSite, (中文(简体) ), checkContent, (中文(简体) ), loadSite 财务报告和审定财务报表 validateSite 从 @avgeek-oss/mintlify-docs; 软件包中不需要路径 .
将片段直接导入到主 MDX 页面 :
import { Home, Hero, Actions, ActionLink } from "/snippets/oss/homepage.jsx";
<Home>
<Hero id="hero-heading">
<h1 id="hero-heading">Your project</h1>
<p>Explain what it helps people do.</p>
<Actions>
<ActionLink href="/docs/getting-started">Get started →</ActionLink>
</Actions>
</Hero>
</Home>
设定 mode: "custom" 在主页头条。 导入页面中的所有片段依赖; Mintlify 不支持交叉片段导入 .
指南
- 主页和截图:导出组件,插槽,标题结构,响应图像,以及主题.
- 导航和站点配置: 分类,分组的页面列表,页眉/页脚链接,以及生成的文件所有权.
- 站点工具:同步、漂移和内容检查、粘住的Mintlife验证、资产、导航包括:,
{version},以及软件包 API. - 写入文档:任务指南,参考页,原生的Mintlify组件,示例,截图和校验.
发展
这些是维护者的开发笔记. 我们不接受来自公共来源的捐款,以遏制自动拉动请求,并且因为没有专门的资源来审查和签署这些请求。 这一储存库欢迎反馈和问题;我们对这些反馈和问题进行分类并努力尽早予以纠正。 如本报告所述,私下报告安全方面的弱点 警卫。 。 。 .
使用节点.js 26和pnpm 11. 发展规则在 一般事务人员(其他职等)。 。 。 .
pnpm install --frozen-lockfile
pnpm verify
pnpm validate:fixture
pnpm dev
pnpm verify 检查格式化,运行克林特和斯泰林特以及测试,并将被包装的柏油球安装到本次检查之外的新的临时项目中,在其中运行生成和漂移检查. 测试同步固定站点 test/fixtures/site.mjs 输入临时目录;没有生成任何内容。 当更改添加了特性或导出时,在固定中锻炼.
pnpm validate:fixture 运行 Mintlify 的被绑定验证,断开链接和对固定器生成的输出的可访问性检查;它需要网络访问,CI运行它也. 要移动到更新的 Mintlify CLI, 更改 mintVersion 内 src/validate.mjs 编辑 dev 剧本一起. pnpm dev 将固定写入 .preview/ 以物配主 http://localhost:4176。在桌面和移动宽度上以浅暗的主题审查主页和指南,并检查搜索、分类导航、巢组、主题控制、键盘焦点、CTA目的地和页脚链接是否仍然有效.
发布笔记在 变动情况来源和第三方归属 NOTICE 财务报告和审定财务报表 LICENSE。 。 。 .
出版
调取请求并推向 main 运行 verify 检查。 更新版本并添加其 ## X.Y.Z (YYYY-MM-DD) 通过正常审查进程,将区域移至更改日志。 一旦合并 main 绿色,运行 剪切释放 工作流程来源 main (动作,剪接发布,运行工作流程). 它检查版本、更改日志、标记和npm状态,并检查已核实 main 运行承诺仍然有它的包件,然后创建注释 v<version> 标记并开始运行。 用手推同一标记也一样.
发布运行不会再次验证或重建 。 它下载了焦油丸 main 运行被标记的承诺,检查其完整性,公布准确的字节,而不运行软件包生命周期脚本,检查登记册是否服务于同样的完整性,并将其安装在一个新鲜的消费者身上。 重试只有在其完整性符合经核实的候选人的情况下,才会接受现有版本。 成功发布后,一个单独的工作创建或更新了该版本的标签的GitHub发布 CHANGELOG.md 节.
出版工作使用 npm 信任的出版与 GitHub Actions OIDC 。 配置 avgeek-oss/oss-docs 和工作流程 ci.yml 在软件包的 npm 信任-publisher 设置中。 这份工作是 id-token: write; GitHub 机密中不存储任何出版令牌 。 现有的 GitHub 包版本仍然可供旧的取出.
在Apache -2.0的许可。 初始布局从 拖动栏。 。 。 .