Apache Maven 站点插件

经常问的问题

一般的

mvn site和mvn site:site有什么区别？
如何将静态 (X)HTML 页面集成到我的 Maven 站点中？
如何包含自定义 Doxia 模块，例如 Twiki？
如何验证我的 xdoc/fml 源文件？
站点插件如何使用 POM 中的 <url> 元素？

具体问题

为什么我的绝对链接会被翻译成相对链接？
为什么我运行“ mvn site ”时父模块和子模块之间的链接不起作用？
我可以在 xdoc/fml 源文件中使用实体吗？

一般的

mvn site和mvn site:site有什么区别？

mvn网站: 调用站点生命周期的站点阶段。完整的站点生命周期包括以下生命周期阶段：pre-site、site、post-site和site-deploy。请参阅生命周期参考。然后它调用与预站点和站点阶段相关的插件目标。
mvn 站点：站点: 调用站点插件的站点目标。请参阅站点：站点。

[最佳]

如何将静态 (X)HTML 页面集成到我的 Maven 站点中？

您可以按照以下步骤集成静态页面：

将静态页面放在资源目录${basedir}/src/site/resources
创建您的site.xml并将其放入${basedir}/src/site
通过修改菜单部分链接到静态页面，创建项目并将它们映射到静态页面的文件名

[最佳]

如何包含自定义 Doxia 模块，例如 Twiki？

该站点插件处理开箱即用的 apt、xdoc 和 fml 格式。如果您想使用自定义格式，如 Twiki、Simple DocBook 或 XHTML（或任何其他存在 doxia 解析器的文档格式，请参阅 Doxia 标记语言列表），您需要指定相应的 Doxia 模块依赖项，例如维基：

<project>
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.apache.maven.doxia</groupId>
            <artifactId>doxia-module-twiki</artifactId>
            <version><!-- doxia version appropriate to the site plugin version --></version>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>
  ...
</project>

请注意，必须将 doxia 版本调整为您正在使用的站点插件版本，请参阅迁移指南。特别是，对于站点插件版本>=2.1 ，您需要使用 doxia >=1.1。

[最佳]

如何验证我的 xdoc/fml 源文件？

从站点插件的 2.1.1 版本开始，有一个validate 配置参数可以打开 xml 验证（默认为关闭）。请注意，在 Doxia 使用的解析器的当前实现中，验证需要独立的解析运行，因此在打开验证时每个源文件实际上都会被解析两次。

如果启用验证，所有xml 源文件都需要正确的模式和/或 DTD 定义。请参阅有关验证 xdocs的 Doxia 文档，以及 xdoc 和 fml的模式定义。

[最佳]

站点插件如何使用 POM 中的 <url> 元素？

站点插件不使用 POM 中的 <url> 元素。项目 URL 只是让您的用户知道项目所在位置的一条信息。其他一些插件（例如 project-info-report-plugin）可以用来呈现这些信息。如果您的项目有一个用于部署生成站点的 URL，则将该 URL 放入 <url> 元素中。如果项目的站点未部署在任何地方，则从 POM 中删除 <url> 元素。

另一方面，<distributionManagement.url> 在多模块构建中用于构建生成的子模块站点之间的相对链接。在多模块构建中，父模块和子模块具有不同的URL 很重要。如果它们具有相同的 URL，则组合站点中的链接将不起作用。请注意，正确的 URL也应该以斜杠 ("/") 结尾。

[最佳]

具体问题

为什么我的绝对链接会被翻译成相对链接？

发生这种情况是因为站点插件会在可能的情况下尝试使所有 URL 相对。如果您在 pom.xml中定义了类似的内容：

<url>http://www.your.site.com/</url>

并在您的site.xml 中创建链接（只是一个示例），如下所示：

<links>
  <item name="Your Site" href="http://www.your.site.com/"/>
  <item name="Maven 2" href="http://maven.apache.org/maven2/"/>
</links>

您将看到“您的站点”的链接将是一个相对链接，但“Maven 2”的链接将是一个绝对链接。

JIRA 中有一个问题，您可以在其中阅读更多相关信息。

[最佳]

为什么我运行“ mvn site ”时父模块和子模块之间的链接不起作用？

在多项目构建中， “ mvn site ”将为您做的就是为父级及其所有模块单独运行“ mvn site ” 。父子之间的链接在这里不起作用。但是，当您部署站点时，它们将起作用。

如果您想对此进行测试，在部署之前，您可以按照使用文档中的说明运行 site:stage目标。

[最佳]

我可以在 xdoc/fml 源文件中使用实体吗？

是的。Doxia 1.1 版中添加了实体解析，可在站点插件 2.1 及更高版本中使用。

但是有一个问题。在当前实现中（从 maven-site-plugin-2.1.1 开始），实体仅由独立的验证运行解决。因此，如果您想使用实体，您必须为您的 xml 源文件打开验证。见MSITE-483。

[最佳]