Antora Atlas 扩展

Antora Atlas扩展系统(此处,Atlas系统)通过使用一个站点清单,管理整个Antora各行各业的参考文献.

警告声
此扩展目前为ALPHA软件! 这意味着这个扩展实验,并有可能不经通知而改变. 欢迎您测试并反馈.

页:1
如果您正在寻找前体释放线, 即这个扩展前一个用户的稳定释放线, 请参考 (单位:千美元) 树枝.

概览

扩建的目的是支持站点组成(即打磨)和部分建设.

启用此扩展后, 它会创建并发布一个站点, 显示在站点的根上 . 站点清单是一个名为JSON的文件 网站地图。 。 。 . 此文件包含网站中所有页面和别名的参考信息,按组件后版本分组. 这些信息旨在从一个离散的站点(如存档站点)或部分构建(仅选择组件和/或版本)解决这些页面的引用.

当启用此扩展并指定主站点显示 URL 或主站点 URL 时,它将读取站点显示,并将所有组件版本和页面导入当前站点的内容目录. 站点站名表的位置可以是本地路径. 如果站点清单的位置是一个URL,则扩展会下载并缓存.

扩展所创建的虚拟文件仅仅是活字节,足以让Antora通过资源ID解决引用. 这些文件的目标URL是外部的,指的是在已公布的站点中的位置,而不是相对于当前站点. 在内部,Antora能够通过存在提供的资源和进口资源加以区分 site 属性.

先决条件

要使用此扩展名, 您必须至少使用节点20和 Antora 3.2.0 (英语) 或更新. 以下指令假设您已经设置了 Antora 游戏本文件(即 , 蚂蚁游戏本. yml建造你的网站.

为了了解与Antora的扩展,请参见 Antora 扩展文档。 。 。 .

安装

使用以下命令将扩展安装到您的 Antora 游戏本项目 :

$ npm i @antora/atlas-extension

登记册

打开您的 Antora 播放本文件,并将扩展名注册为 antora.extensions 键. 如果此密钥尚未存在于您的游戏本中, 请先创建它 .

蚂蚁游戏本. yml

antora:
  extensions:
  - '@antora/atlas-extension'

配置导出

不需要配置来导出站点清单. 启用扩展时, 这种行为会自动生效 .

您可以使用 site-manifest-path 属性(虽然在刚开始时不建议). 这个值被假定为来自网站Antora出版的根的相对路径.

asciidoc:
  attributes:
    site-manifest-path: _site-manifest.json

如果 site.url 键在游戏本中设置,其值包含在站点清单中.

页:1
当该站点清单以被磨损的方式被导入时,该站点清单的出口只是真正用于信息和报告目的. 这并非一个完整的站点清单.

配置导入

启用

要导入站点清单,您必须指定 primary-site-manifest-url 属性(或更简洁地说 primary-site-url 属性),在Antora游戏本中.

asciidoc:
  attributes:
    primary-site-manifest-url: https://docs.example.org/site-manifest.json

如果使用默认配置启用了此扩展的站点, 您只需要指定主站点的 URL . 扩展将自动发现站点显示 .

asciidoc:
  attributes:
    primary-site-url: https://docs.example.org

在此情况下,扩展将寻找位于 https://docs.example.org/site-manifest.json并缓存它. 阿特拉斯公司只会试图重新下载 --fetch 选项 runtime.fetch=true 在游戏本.

作为替代,您可以指定要导入的站点的任意路径或URL . 如果值是 URL,则扩展会下载. 否则,它将从指定地点读取.

asciidoc:
  attributes:
    primary-site-manifest-url: ./primary-site-manifest.json

如果找不到站点显示文件,扩展名会默默地忽略导入请求. 如果显示的 URL 以 .gz阿特拉斯会把文件打乱的.

页:1
当扩展输出该清单时,它将不会包含任何以前以已磨损模式导入的资源.

合并

通常,阿特拉斯只从未知的组件版本(指不从一个内容来源创建)导入文件. 想法是阿特拉斯正在从清单中填入网站的缺失部分.

如果您使用的是本地内容源, 仅提供部分文件用于组件版本, 您需要请求 Atlas 将未知的站点列表中的任何文件合并 . 您可以通过设置 merge 子密钥 import 键. (这通常用于类似轻量级家庭组件).

antora:
  extensions:
  - require: '@antora/atlas-extension'
    import:
      merge: true

在这种模式下,Atlas将不会替换构建中提供的任何相同组件版本的文件. 它只会附加文件 . 它还会忽略任何针对所提供页面的别名,因为假设是所提供的页面定义了别名.

Atlas试图在导入缺失文件时避免创建任何文件冲突. 然而,你必须明白,这种功能造成了一种独特的情况,即Atlas假设任何导入的文件仍将由下一个完整的建筑提供. Atlas 无法检测在此情况下将要删除的文件 .

导入模式

在导入文件时, Atlas 以两种模式之一运行: 软化 或者说 同一地点。 。 。 . 被磨损模式用于预览构建,而同站点模式则用于部分构建(由构建脚本提供一些帮助).

如果 primary-site-url (除此之外,网站清单中的url)与网站URL相匹配. 否则,会使用被硬化的模式.

软化

在硬化模式下,阿特拉斯导入文件,目的是在仅构建部分站点(即内容来源的子集)时解决引用问题. 如果一个资源(例如一页)不是由建筑提供,并且出现在站点清单中,那么该资源的引用将解决主站点的URL.

此模式的用意是生成一个网站中某一子集内容的预览,但仍有它看起来像一个完整的站点.

在这个模式下,站点地图,站点明细表,再定向将只包含由所建站提供的资源. 这意味着由此产生的网站清单实际上只是为了提供信息和报告.

同一个站点

在同一站点模式下,Atlas导入文件是为了制作一个完整的站点,即使只建了站点的一部分(即内容来源的子集). 如果某一资源(例如一页)不由大楼提供,并在站点清单中找到,那么,如果该资源包括在大楼内,则该资源的提法将与该资源完全相同. 换句话说,它将成为同一网址的参考.

此模式的用意是能够构建一个网站内容的子集,然后将输出内容覆盖到整个站点的文件上,以此来更新.

在这种模式下,站点映射,站点明细表,并重定向会完整,就像所有内容来源都包含在了构建中一样. 任何导入的资源都反映了它们与上一个完整构建时的状态,并且可能仍然与实际内容源中的内容不同.

导入模式选择

下表确定如何根据配置确定导入模式.

启用同一站点模式的最典型方式是设置站点URL和 primary-site-url 属性到同一值.

版权和许可证

版权(C)2022年-由OpenDevise Inc.和该项目的个人贡献者介绍.

该软件的使用按照下列规定进行: Mozilla 公共许可版本 2.0 (MPL-2.0) (中文(简体) ).