# @antora/atlas-extension 中文文档 规范地址：https://npmcn.com/package/%40antora/atlas-extension/ 版本：1\.0\.0-alpha\.6 npm 元数据更新时间：2026-09-30T19:31:10.887Z 中文译文更新时间：2026-11-06T07:13:04.469Z 软件包许可：MPL-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40antora/atlas-extension 原文对照：https://npmcn.com/package/%40antora/atlas-extension/?lang=original 项目主页：https://antora.org/ 源码仓库：https://gitlab.com/antora/antora-atlas-extension ## 关键信息（来自 npm 元数据） - 包体积（解压后）：55.7 kB，11 个文件 - 模块格式：CommonJS - TypeScript 类型：未声明 - Node.js 要求：\>=20\.0\.0 - 运行依赖：4 个 - 首次发布：2022-10-11T02:49:54.030Z - 最新版本发布：2026-09-30T19:31:10.678Z - 近 30 天下载量：12431（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：8（近 12 个月 1 个） ## 中文简介 Antora扩展,通过使用一个站点清单,管理Antora各行各业的参考文献. ## 安装 ```sh npm install @antora/atlas-extension ``` 也可以使用：`pnpm add @antora/atlas-extension`、`yarn add @antora/atlas-extension`、`bun add @antora/atlas-extension` ## README # Antora Atlas 扩展 Antora Atlas扩展系统(此处,Atlas系统)通过使用一个站点清单,管理整个Antora各行各业的参考文献. **警告声** 此扩展目前为ALPHA软件! 这意味着这个扩展实验,并有可能不经通知而改变. 欢迎您测试并反馈. **页:1** 如果您正在寻找前体释放线, 即这个扩展前一个用户的稳定释放线, 请参考 [(单位:千美元)](https://gitlab.com/antora/antora-atlas-extension/-/tree/v0.0.x) 树枝. ## 概览 扩建的目的是支持站点组成(即打磨)和部分建设. 启用此扩展后, 它会创建并发布一个站点, 显示在站点的根上 . 站点清单是一个名为JSON的文件 _网站地图_。 。 。 . 此文件包含网站中所有页面和别名的参考信息,按组件后版本分组. 这些信息旨在从一个离散的站点(如存档站点)或部分构建(仅选择组件和/或版本)解决这些页面的引用. 当启用此扩展并指定主站点显示 URL 或主站点 URL 时,它将读取站点显示,并将所有组件版本和页面导入当前站点的内容目录. 站点站名表的位置可以是本地路径. 如果站点清单的位置是一个URL,则扩展会下载并缓存. 扩展所创建的虚拟文件仅仅是活字节,足以让Antora通过资源ID解决引用. 这些文件的目标URL是外部的,指的是在已公布的站点中的位置,而不是相对于当前站点. 在内部,Antora能够通过存在提供的资源和进口资源加以区分 `site` 属性. ## 先决条件 要使用此扩展名, 您必须至少使用节点20和 [Antora 3.2.0 (英语)](https://docs.antora.org/) 或更新. 以下指令假设您已经设置了 Antora 游戏本文件(即 , _蚂蚁游戏本. yml_建造你的网站. 为了了解与Antora的扩展,请参见 [Antora 扩展文档](https://docs.antora.org/antora/latest/extend/extensions/)。 。 。 . ## 安装 使用以下命令将扩展安装到您的 Antora 游戏本项目 : ```console $ npm i @antora/atlas-extension ``` ## 登记册 打开您的 Antora 播放本文件,并将扩展名注册为 `antora.extensions` 键. 如果此密钥尚未存在于您的游戏本中, 请先创建它 . **蚂蚁游戏本. yml** ```yaml antora: extensions: - '@antora/atlas-extension' ``` ## 配置导出 不需要配置来导出站点清单. 启用扩展时, 这种行为会自动生效 . 您可以使用 `site-manifest-path` 属性(虽然在刚开始时不建议). **这个值被假定为来自网站Antora出版的根的相对路径.** ```yaml asciidoc: attributes: site-manifest-path: _site-manifest.json ``` 如果 `site.url` 键在游戏本中设置,其值包含在站点清单中. **页:1** 当该站点清单以被磨损的方式被导入时,该站点清单的出口只是真正用于信息和报告目的. 这并非一个完整的站点清单. ## 配置导入 ### 启用 要导入站点清单,您必须指定 `primary-site-manifest-url` 属性(或更简洁地说 `primary-site-url` 属性),在Antora游戏本中. ```yaml asciidoc: attributes: primary-site-manifest-url: https://docs.example.org/site-manifest.json ``` 如果使用默认配置启用了此扩展的站点, 您只需要指定主站点的 URL . 扩展将自动发现站点显示 . ```yaml asciidoc: attributes: primary-site-url: https://docs.example.org ``` 在此情况下,扩展将寻找位于 `https://docs.example.org/site-manifest.json`并缓存它. 阿特拉斯公司只会试图重新下载 `--fetch` 选项 `runtime.fetch=true` 在游戏本. 作为替代,您可以指定要导入的站点的任意路径或URL . 如果值是 URL,则扩展会下载. 否则,它将从指定地点读取. ```yaml asciidoc: attributes: primary-site-manifest-url: ./primary-site-manifest.json ``` 如果找不到站点显示文件,扩展名会默默地忽略导入请求. 如果显示的 URL 以 `.gz`阿特拉斯会把文件打乱的. **页:1** 当扩展输出该清单时,它将不会包含任何以前以已磨损模式导入的资源. ### 合并 通常,阿特拉斯只从未知的组件版本(指不从一个内容来源创建)导入文件. 想法是阿特拉斯正在从清单中填入网站的缺失部分. 如果您使用的是本地内容源, 仅提供部分文件用于组件版本, 您需要请求 Atlas 将未知的站点列表中的任何文件合并 . 您可以通过设置 `merge` 子密钥 `import` 键. (这通常用于类似轻量级家庭组件). ```yaml antora: extensions: - require: '@antora/atlas-extension' import: merge: true ``` 在这种模式下,Atlas将不会替换构建中提供的任何相同组件版本的文件. 它只会附加文件 . 它还会忽略任何针对所提供页面的别名,因为假设是所提供的页面定义了别名. Atlas试图在导入缺失文件时避免创建任何文件冲突. 然而,你必须明白,这种功能造成了一种独特的情况,即Atlas假设任何导入的文件仍将由下一个完整的建筑提供. Atlas 无法检测在此情况下将要删除的文件 . ### 导入模式 在导入文件时, Atlas 以两种模式之一运行: **软化** 或者说 **同一地点**。 。 。 . 被磨损模式用于预览构建,而同站点模式则用于部分构建(由构建脚本提供一些帮助). 如果 `primary-site-url` (除此之外,网站清单中的url)与网站URL相匹配. 否则,会使用被硬化的模式. #### 软化 在硬化模式下,阿特拉斯导入文件,目的是在仅构建部分站点(即内容来源的子集)时解决引用问题. 如果一个资源(例如一页)不是由建筑提供,并且出现在站点清单中,那么该资源的引用将解决主站点的URL. 此模式的用意是生成一个网站中某一子集内容的预览,但仍有它看起来像一个完整的站点. 在这个模式下,站点地图,站点明细表,再定向将只包含由所建站提供的资源. 这意味着由此产生的网站清单实际上只是为了提供信息和报告. #### 同一个站点 在同一站点模式下,Atlas导入文件是为了制作一个完整的站点,即使只建了站点的一部分(即内容来源的子集). 如果某一资源(例如一页)不由大楼提供,并在站点清单中找到,那么,如果该资源包括在大楼内,则该资源的提法将与该资源完全相同. 换句话说,它将成为同一网址的参考. 此模式的用意是能够构建一个网站内容的子集,然后将输出内容覆盖到整个站点的文件上,以此来更新. 在这种模式下,站点映射,站点明细表,并重定向会完整,就像所有内容来源都包含在了构建中一样. 任何导入的资源都反映了它们与上一个完整构建时的状态,并且可能仍然与实际内容源中的内容不同. #### 导入模式选择 下表确定如何根据配置确定导入模式. | 游戏本. site.url | 初级现场-url | 在站点清单中url | 导入模式 | | --- | --- | --- | --- | | _未定义_ | _未定义_ | _未定义_ | 同一地点 | | _未定义_ | _未定义_ | https:// (中文(简体) )页:1 | 软化 | | https:// (中文(简体) )页:1 | _未定义_ | https:// (中文(简体) )页:1 | 同一地点 | | 联合国本地主机: 8080 | _未定义_ | https:// (中文(简体) )页:1 | 软化 | | https:// (中文(简体) )页:1 | _未定义_ | _未定义_ | 软化 | | _未定义_ | 。 。 。 . | _未定义_ | 同一地点 | | _未定义_ | 。 。 。 . | https:// (中文(简体) )页:1 | 同一地点 | | https:// (中文(简体) )页:1 | 。 。 。 . | https:// (中文(简体) )页:1 | 同一地点 | | 联合国本地主机: 8080 | 。 。 。 . | https:// (中文(简体) )页:1 | 同一地点 | | https:// (中文(简体) )页:1 | 。 。 。 . | _未定义_ | 同一地点 | | _未定义_ | https:// (中文(简体) )页:1 | _未定义_ | 软化 | | _未定义_ | https:// (中文(简体) )页:1 | https:// (中文(简体) )页:1 | 软化 | | 联合国本地主机: 8080 | https:// (中文(简体) )页:1 | https:// (中文(简体) )页:1 | 软化 | | _未定义_ | 联合国本地主机: 8080 | https:// (中文(简体) )页:1 | 软化 | | https:// (中文(简体) )页:1 | https:// (中文(简体) )页:1 | https:// (中文(简体) )页:1 | 同一地点 | | https:// (中文(简体) )页:1 | https:// (中文(简体) )页:1 | _未定义_ | 同一地点 | | https:// (中文(简体) )页:1 | https:// (中文(简体) )dev.docs.example.org 页面存档备份,存于互联网档案馆 | https:// (中文(简体) )页:1 | 软化 | 启用同一站点模式的最典型方式是设置站点URL和 `primary-site-url` 属性到同一值. ## 版权和许可证 版权(C)2022年-由OpenDevise Inc.和该项目的个人贡献者介绍. 该软件的使用按照下列规定进行: [Mozilla 公共许可版本 2.0](https://www.mozilla.org/en-US/MPL/2.0/) (MPL-2.0) (中文(简体) ). ## 常见问题 ### @antora/atlas-extension 是什么？ Antora扩展,通过使用一个站点清单,管理Antora各行各业的参考文献\. ### 如何安装 @antora/atlas-extension？ 在项目目录运行 npm install @antora/atlas-extension，或使用 pnpm add / yarn add / bun add。 ### @antora/atlas-extension 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/antora\_\_atlas-extension 是否存在。 ### @antora/atlas-extension 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @antora/atlas-extension 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @antora/atlas-extension 可以商用吗？ @antora/atlas-extension 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。 ### @antora/atlas-extension 的下载量有多少？ 根据 npm 官方下载统计，@antora/atlas-extension 在 2026/10/06 – 2026/11/04 这 30 天内被下载 12,431 次，日均约 414 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @antora/atlas-extension 还在维护吗？ 最新版本 1\.0\.0-alpha\.6 发布于 2026/10/01（1 个月前）；至今共发布 8 个版本，其中过去 12 个月发布了 1 个；首次发布于 2022/10/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。