HTML扩展样式

Antora允许您自定义在HTML页面的URL中使用的文件扩展名。默认情况下，URL将以.html结尾，与发布文件的名称相同。如果您想要通过隐藏扩展名来“美化”URL以进行SEO或其他原因，您可以配置Antora来实现。您可以选择直接删除扩展名或将扩展名替换为斜杠（一种称为indexify的技术）。当使用这些选项之一时，如果源页面命名为index.adoc，Antora还将删除最后的URL段。本页面解释了如何控制此设置。

html_extension_style键

html_extension_style键是可选的。它在playbook中的urls键下进行配置。

示例1. antora-playbook.yml 
urls:
  html_extension_style: indexify

它接受以下内置值：

default

发布页面的URL显示为.html扩展名，即https://base-url.com/component/version/module/my-file.html。如果在playbook或通过CLI中未设置html_extension_style，Antora将自动应用此样式。

indexify

删除.html扩展名，并在发布页面的URL末尾附加斜杠（/），即https://base-url.com/component/version/module/my-file/。如果您不希望在URL中出现.html扩展名，则这是首选样式。

drop

从发布页面的URL末尾删除.html扩展名，即https://base-url.com/component/version/module/my-file。此样式需要Web服务器的支持，只有在您熟悉应用必要的Web服务器配置时才应使用。

使用默认样式

如果在playbook或通过--html-url-extension-style选项的CLI中未设置html_extension_style，Antora将在运行时自动将值default分配给它。默认样式会在每个发布页面的URL末尾附加.html扩展名。例如，页面my-file.adoc的URL将在浏览器中显示为附加.html的形式，即https://base-url.com/component/version/module/my-file.html。

应用indexify样式

让我们将indexify分配给html_extension_style键。

示例2. antora-playbook.yml 
site:
  title: 网站标题
  url: https://example.org
urls:
  html_extension_style: indexify

应用indexify后，站点的发布URL不以.html扩展名结尾。相反，直接在页面主干的末尾附加斜杠（/）。这导致页面my-file.adoc的URL在浏览器中显示为https://example.com/component/version/module/my-file/。

当将html_extension_style分配为indexify时，要本地预览站点的所有功能，如重定向和404页面，您需要运行本地服务器。

应用drop样式

让我们将drop分配给html_extension_style键。

示例3. antora-playbook.yml 
site:
  title: 网站标题
  url: https://example.org
urls:
  html_extension_style: drop

应用drop后，站点的发布URL不以.html扩展名结尾。这导致页面my-file.adoc的URL在浏览器中显示为https://example.com/component/version/module/my-file。使用此样式时，为了使站点正常工作，您必须通过Web服务器查看站点。您还需要配置Web服务器以查找带有.html扩展名的文件。

并非所有Web服务器都能支持无扩展名的HTML URL。

如果您使用nginx，您需要在主机配置中的location /段中添加以下指令：

location / {
  # ...
  try_files $uri $uri.html $uri/index.html = 404;
}

此指令告诉nginx首先查找请求的文件，然后查找带有添加.html扩展名的相同文件，然后查找与请求文件匹配的目录中名为index.html的文件。这些尝试与发布文件的布局相匹配。