Antora Lunr 扩展

朗尔 为读者提供了巨大的搜索体验,而不必依赖外部搜索服务. 使用此扩展名,您可以添加 离线Lunr为您的 Antora 文件网站提供全文搜索.

页:1
Antora Lunr 扩展设计与兼容 Antora 3.0和较新的。 。 。 . 如果你使用早期的Antora, 你必须使用 蚂蚁-放任器 换句话说.

要将 Lunr 驱动的搜索功能添加到您的 Antora 文档站点, 您需要安装此扩展包, 在您的 Antora 游戏本文件中注册扩展名, 并在您的站点的页面中添加搜索界面 . 让我们开始吧.

先决条件

为了使用此扩展名,您必须至少使用Node.js 16和Antora 3. 我们假设你已经建立了 Antora 游戏本文件(即, 蚂蚁游戏本. yml建造你的网站.

安装

从将扩展包安装到您的 游戏本项目数字 :

$ npm i @antora/lunr-extension

您还可以选择通过添加 -g 标记为 npm i 命令 :

$ npm i -g @antora/lunr-extension

我们强烈建议在您的游戏本项目中安装依赖性. 这项战略使得更容易管理依赖性,明确记录这些依赖性,并确保建筑是可携带的并与其他场地相隔离的.

前两个指令都从npm注册处下载并安装了最新发布的此软件. 如果要使用开发版本,请参考 贡献部分。 。 。 .

虽然git寄存器中的软件定期进行严格的测试,但开发版本的行为可能并不总是与文档相匹配.

使用量

本节解释如何激活Lunr集成,以及如何使用其提供的搜索界面.

注册扩展名

既然您已经安装了 Lunr 扩展名, 您需要 注册扩展名 与安多拉. 为注册扩展名,您将在 antora.extensions 键 Antora 游戏本文件。 。 。 .

打开 Antora 游戏本文件并添加扩展名如下:

蚂蚁游戏本. yml

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

如果您不需要指定任何配置密钥, 则输入 antora.extensions 可以是软件包的名称. 在此情况下,需要围绕软件包名称引用引文,因为 @ 是YAML中的特殊字符.

人口贩运
也可以在运行时注册扩展名 antora 使用 --extension 选项.

要为扩展指定配置密钥,您必须将条目更改为映射语法. 在使用地图语法时,软件包名称必须先于 require 键,如此处所示:

蚂蚁游戏本. yml

antora:
  extensions:
  - require: '@antora/lunr-extension'

您可能想要从此语法开始, 这样您就不用记得在稍后要指定配置时切换到它 .

生成索引文件

下次构建文档站点时,扩展会自动生成一个搜索索引并写入一个命名的文件 搜索索引.js 在网站的根部. 此文件的位置取决于 output.dir 键在您的游戏本中. 使用时 默认输出目录,该位置是 构建/网站/搜索-index.js。 。 。 .

设置( 或者不设置) 站点 URL

搜索不与网站URL的值相配合. 这意味着你可以将游戏本中的站点URL设置为任何允许的值,无论怎样搜索都会成功. (关于 site.url 密钥 允许值清单). 事实上,你根本不用设置网站URL. 这样做是因为搜索结果中的 URL 总是被计算 相对于当前页面。 。 。 . 它们不是绝对的URL.

人口贩运
如果你在使用这个 http-服务器 模块可以提供 HTTP 服务器以在本地查看您的网站, 您可以设置 site.url 键到 http://localhost:8080 以模仿生产环境的条件.

由于在搜索结果中使用了相对的URL,浏览器可以在结果中解析URL,而不管该站点是在哪里部署的,或者搜索使用的是哪一页. 在通过一个文件URI查看网站离线时甚至可以使用搜索.

创建网站

如果您在游戏本文件中注册了扩展名, 您可以使用 antora 命令,无需通过任何额外的选项或环境变量.

$ antora antora-playbook.yml

如果您没有在游戏本文件中注册扩展名, 您可以使用 --extension CLI 选项 antora 命令 :

$ antora --extension @antora/lunr-extension antora-playbook.yml

使用 --extension 选项还允许您启用在播放簿文件中注册的扩展名,但不能使用 enabled 键. 见 启用扩展 细节如何运作.

搜索中

一旦您将基于 Lunr 的搜索纳入您的网站,下一步就是进行搜索.

要搜索,请在页面上方的搜索框中输入一个查询(即一个词或短语). 例如:

install

搜索结果会在输入时实时显示在搜索框下.

搜索客户端将首先尝试找到精确的匹配. 如果该查询不返回任何结果,则搜索客户端将尝试从搜索开始(例如, install*) (中文(简体) ). 如果查询不返回任何结果,搜索客户端将尝试包含的搜索(例如, \*install*) (中文(简体) ). 如果没有找到结果,则搜索结果将报告“没有结果可供查询”.

页:1
搜索引擎适用于出自名词,因此它也可能为具有相同含义的不同形式的名词(即根词)找到匹配.

Lunr 支持搜索多个术语 . 然而,默认行为可能与您使用其他搜索引擎的经验不符. 默认情况下,多个搜索名词与一个OR运算符(即任一名词)合并. 考虑以下查询:

install antora

如果文档匹配 至少一个 中,文档将出现在结果中. 包含这两个术语的文件将获得更高的分数,从而首先出现.

如果您想要搜索已输入所有术语(即需要的术语存在)的文档,则必须在术语中添加一个修改符. 要表示在匹配文档中必须包含一个名词,请在名词前加上 + (例如, +install) (中文(简体) ). 例如,为了找到一个既包含“安装”又包含“antora”的文档,使用下列查询:

+install +antora

事实
与其他搜索引擎不同,Lunr不支持引文中包含的查询. 在未来,这个扩展可能自动将一个带有该语法的查询翻译为使用需要名词存在的查询.

如果您只想在页面标题和章节标题中查找一个名词,则该名词的前缀为 title:。 。 。 . 例如:

title:install

查找标题时,结果中只显示标题. 您不会看到页面中其它区域的文本片断 .

您可以合并 title: 前缀 + 修饰相. 例如:

+title:install +title:antora

这个扩展可能在未来支持更高级的搜索,因此注意这个空间以了解新的搜索能力.

要了解更多 Lunr 如何搜索,看 与 Lunr 搜索。 。 。 .

正在装入搜索索引

根据索引大小的不同,下载并加载预建索引需要几秒钟. 装入预建索引时, 搜索输入将被禁用 . 索引被加载后,搜索输入就会被激活,用户就能进行搜索.

此外,将在搜索输入元素上发布一个活动. 如果您想要在索引加载时被通知, 您可以添加事件倾听器 :

const searchInput = document.getElementById('search-input')
searchInput.addEventListener('loadedindex', (event) => {
  console.log(`Index loaded in: ${event.detail.took}ms`) // ①
})

1. 事件包含用毫秒加载索引的时间

配置

本节解释如何使用配置密钥和其他设置来控制这种集成的行为.

为了指定配置密钥,请在 antora.extensions 键必须使用地图语法. 当使用此表单时,您会使用 require 键. 配置密钥应为 require 键. 只有 require 键应该与条目标记前缀, -。 。 。 .

页:1
单位 蚂蚁-放任器 (此扩展的前身),配置使用环境变量进行. 在这个扩展名中,现在使用游戏本中的配置密钥进行配置.

仅索引最新版本

只索引最新版本(即已发布),设置 index_latest_only 配置密钥 :

蚂蚁游戏本. yml

antora:
  extensions:
  - require: '@antora/lunr-extension'
    index_latest_only: true

默认情况下,扩展索引会显示文档组件的所有版本.

按标题开列的索引

默认情况下,扩展索引页作为整个文档. 要通过最近的标题作为单独的可搜索块进行索引,请设置 index_by_heading 配置密钥到 true。 。 。 . 这个索引策略在点击非标题搜索结果时将用户引导到关联标题而不是页面上方. 在封面下,每个标题(h1-h6)会用自己的URL片段成为搜索结果中的一个单独条目.

蚂蚁游戏本. yml

antora:
  extensions:
  - require: '@antora/lunr-extension'
    index_by_heading: true

排除页面

您可以通过定义 noindex asciiDoc 标题中的文档属性 :

= Do Not Index Me
:noindex:

This content will not show up in the search results.

通过定义 noindex 该版本组件描述符中的 AsciiDoc 属性 :

蚂蚁.yml

asciidoc:
  attributes:
    noindex: '@'

索引员也会寻找 robots hTML 文档中的元标记, 如果内容属性的值为 noindex。 。 。 . 这使得您可以排除没有从 AsciiDoc 创建的页面, 或包含一个元机器人标记的页面, 由 UI 模板根据另一个条件添加 .

片段长度

默认情况下,搜索结果中片段的最大长度为100个字符. 要更改长度,请设置 snippet_length 配置密钥 :

蚂蚁游戏本. yml

antora:
  extensions:
  - require: '@antora/lunr-extension'
    snippet_length: 250

此选项的值是一个上限 . 片段的长度不会超过匹配文本的长度.

对其他语言的支持

默认情况下,Lunr只支持英语作为索引语言. 您可以添加对以下其它语言的支持:

• 阿拉伯语( ar)
• 中文(日文)(见下文注)
• 丹麦语( da)
• 荷兰语( 无)
• 芬兰语( fi)
• 法语( fr)
• 德语( 德)
• 印地语( hi)
• 匈牙利语( hu)
• 意大利语( It)
• 日语( ja)
• 挪威语( 无)
• 葡萄牙语( pt)
• 罗马尼亚语( ro)
• 俄语( ru)
• 西班牙语( es)
• 瑞典语( sv)
• 泰语 (th)
• 土耳其语( tr)
• 越南语( 六)

页:1
要使用中文作为语言,必须安装 @node-rs/jieba 依赖性(即:, npm i @node-rs/jieba) (中文(简体) ).

要使用一种或多种语言,请设置 languages 配置密钥, 将所有想要的语言代码作为列表 :

蚂蚁游戏本. yml

antora:
  extensions:
  - require: '@antora/lunr-extension'
    languages: [en, fr]

额外的句子

默认情况下,Lunr提供了英文的停止词列表,这些是常见的单词,被排除在搜索索引之外. Lunr Languages为其他被支持语言提供相类似的句式列表过滤.

您可以使用 extra_stop_words 配置键. 您可以在全球范围定义扩展名上的密钥, 这样它适用于所有语言 :

蚂蚁游戏本. yml

antora:
  extensions:
  - require: '@antora/lunr-extension'
    extra_stop_words: ['basically', 'actually']

您也可以定义 extra_stop_words 按语文分类,按 languages 配置密钥 :

蚂蚁游戏本. yml

antora:
  extensions:
  - require: '@antora/lunr-extension'
    languages:
    - en:
      extra_stop_words: ['basically', 'actually']
    - fr:
      extra_stop_words: ['empêche', 'fonctionnalité']

您不必定义 extra_stop_words 键,如果您不想为它指定句子. 例如,将西班牙语作为附加索引语言添加到上面的例子中没有额外的句号,您将把语言代码留作字符串:

蚂蚁游戏本. yml

antora:
  extensions:
  - require: '@antora/lunr-extension'
    languages:
    - en:
      extra_stop_words: ['basically', 'actually']
    - fr:
      extra_stop_words: ['empêche', 'fonctionnalité']
    - es

调试无效的查询

默认情况下, 如果查询无效, 搜索客户端会关闭 Lunr 所抛出的错误 . 客户端假设如果查询无效,则没有结果可以显示.

如果您想要调试一个查询, 您想要看到 Lunr 丢出错误的消息, 您可以将搜索客户端放入调试模式 . 为此,增加 ?lunr-debug=1 到当前页面的 URL 结尾并重新装入页面.

人口贩运
如果页面 URL 已有查询字符串, 则附加 &lunr-debug=1 换句话说.

当调试模式被启用后,关于无效查询的信息会出现在Debug级别的浏览器控制台上. 例如:

Invalid search query: invalid:term (unrecognised field 'invalid', possible fields: 'title', 'name', 'text', 'component')

目前没有通知用户一个无效的查询,尽管将来可能会有变化.

UI 假设

本节针对任何设计和创建自定义UI的人. 此扩展依赖于与UI的合同,以将用户必须完成的配置最小化才能使扩展生效. Antora的违约UI履行这一合同. 对于自定义的UI,本合同的假设在这里有记载.

lunr.js 脚本

扩展提供了 lunr.js 脚本. 你的UI不应该包括它. 如果有的话, 您将会遇到重复的文件错误 .

环境变量

启用此扩展时, 它设置 SITE_SEARCH_PROVIDER 环境变量到值 lunr。 。 。 . 此变量可用 UI 模板作为 env.SITE_SEARCH_PROVIDER。 。 。 . 此变量的存在通知了搜索集成活动的UI模板(在这种情况下是Lunr). 当设定此变量时, UI 预计将添加某些元素来支持扩展.

页:1
如果您使用的UI没有履行合同, 您需要使用补充UI来完成合同.

搜索输入

此扩展假设UI会在页面的某处添加一个输入字段进行搜索. 目前,所提供的样式假设它位于导航站. 模板片段应该看起来像这样:

{{#if env.SITE_SEARCH_PROVIDER}}
<input id="search-input" type="text" placeholder="Search the docs">
{{/if}}

UI可以将输入内容附入其他元素,以便正确定位. 在Antora默认的UI中,看起来是这样的:

{{#if env.SITE_SEARCH_PROVIDER}}
<div class="navbar-item search hide-for-print">
  <div id="search-field" class="field">
    <input id="search-input" type="text" placeholder="Search the docs"{{#if page.home}} autofocus{{/if}}>
  </div>
</div>
{{/if}}

唯一的要求是输入必须是类型 text 有身份证 search-input。 。 。 .

限制搜索到当前组件

如果您想要添加一个复选框, 可以使用以下片段来限制当前组件的搜索 :

{{#if env.SITE_SEARCH_PROVIDER}}
<div class="navbar-item search hide-for-print">
  <div id="search-field" class="field has-filter">
    <input id="search-input" type="text" placeholder="Search the docs"{{#if page.home}} autofocus{{/if}}>
    <label class="filter checkbox">
      <input type="checkbox" data-facet-filter="component:{{page.component.name}}"> In this project
    </label>
  </div>
</div>
{{/if}}

如果您想要默认过滤当前组件, 您可以添加 checked 复选框中的属性 :

<input type="checkbox" data-facet-filter="component:{{page.component.name}}" checked> In this project

如果您总是想要过滤当前组件( 不给出选项), 您可以使用内线样式隐藏复选框 :

<label class="filter checkbox" style="display: none">
  <input type="checkbox" data-facet-filter="component:{{page.component.name}}" checked> In this project
</label>

搜索脚本

这一延期假设,伊拉克情报机构将包括 搜索脚本 部分在脚上某处. 此部分加载了 lunr 脚本, 搜索 UI 脚本, 并搜索索引到页面 . 包含这个部分的模板片段应该看起来像这样:

{{#if env.SITE_SEARCH_PROVIDER}}
{{> search-scripts}}
{{/if}}

此扩展将自动添加部分 搜索脚本 转到未存在的 UI 目录.

搜索样式

此软件包提供了额外的 CSS 以样式化搜索结果( S)数据/cs/search.cs) (中文(简体) ). 此样式表由此软件包也提供的搜索 UI 脚本所加载. 此扩展将自动添加样式表 搜索( c) 转到未存在的 UI 目录.

如果自定义的 UI 依赖于额外的样式, UI 的创建者可以或者将这些样式捆绑起来,或者要求用户在补充的 UI 中放置一个替代样式表.

捐款

如果您有兴趣为该项目捐款,请参见: 贡献指南。 。 。 . 在这个指南中,你会学会如何:

• 设置您的开发工作空间
• 构建项目
• 运行开发版本
• 提交合并请求

提前感谢您帮助该项目取得成功!

谁在用?

以下是使用Antora Lunr扩展的项目列表.

• SUSE 管理器文档
• Uyuni 文档
• 击败链接触发器
• NTT 应用程序安全
• 准将组件枢纽(VSHN)
• DHW - DataHandwerk工具包 mssql
• Apache Solr 参考指南

要将您的项目添加到此列表中, 请 编辑此文件来啊!

商标

AsciiDoc(R)是Eclipse基金会股份有限公司的商标.