由 Maven 构建

配置站点描述符

当您想要覆盖站点的导航树时，您可以为您的项目创建自己的站点描述符。例如，除了生成的报告之外，您还想向您的站点添加其他内容。为了在生成的站点中可以访问它，您必须配置站点描述符。您在名为site.xml的文件中创建站点描述符，该文件应位于您的src/site目录中。

站点描述符的参考文档随其 XML Schema 提供。

查看Maven 站点插件的站点描述符以获取真实示例。

标题

每个生成页面的标题将是站点标题和当前页面标题的组合。默认情况下，站点插件将使用pom.xml文件中<name>元素的值作为站点标题。此页面的完整标题是“Maven 站点插件 - 配置站点描述符”。

如果您想使用不同的站点标题，但不想更改pom.xml中的<name>元素，您可以在site.xml中进行配置，如下所示：

<project name="My Site Title">
  ...
</project>

横幅

您可以使用以下语法在您的网站顶部包含一些徽标：

<project>
  ...
  <bannerLeft>
    <name>Project Name</name>
    <src>https://maven.apache.org/images/apache-maven-project-2.png</src>
    <href>https://maven.apache.org/</href>
  </bannerLeft>

  <bannerRight>
    <src>https://maven.apache.org/images/maven-logo-2.gif</src>
  </bannerRight>
  ...
</project>

有关完整的标记说明，请参阅站点描述符参考。

发布日期

使用开箱即用的 Velocity 模板，“上次发布”日期的位置是可配置的。默认情况下，位置在左侧，但您可以更改它。为此，您可以将<publishDate>元素添加到您的site.xml，如下所示：

<project>
  ...
  <publishDate position="right"/>
  ...
</project>

position属性可以具有以下值之一：left 、 right 、 navigation -top、navigation-bottom、bottom。

如果你想隐藏发布日期，你可以在你的site.xml中使用它：

<project>
  ...
  <publishDate position="none"/>
  ...
</project>

“上次发布”日期的格式是W3C 推荐的 ISO 扩展日期格式。由于网络拥有国际化、跨文化的受众，因此建议不要更改日期格式。但是，如果您确实需要不同的日期格式，则可以使用<publishDate>元素的格式属性。

版本

您可以在站点上显示项目的“版本”，方法是向site.xml添加<version>元素，如下所示：

<project>
  ...
  <version position="right"/>
  ...
</project>

position属性可以具有与publishDate属性相同的值，见上文。如果省略position属性，则默认值为left。

如果你想隐藏版本，你可以在你的site.xml中使用它：

<project>
  ...
  <version position="none"/>
  ...
</project>

“供电”标志

您可以将自己的“Powered by”徽标添加到您的网站。为此，您可以在site.xml中添加一个<poweredBy>元素，如下所示：

<project>
  ...
  <poweredBy>
    <logo name="Maven" href="https://maven.apache.org/"
          img="https://maven.apache.org/images/logos/maven-feather.png"/>
  </poweredBy>
  ...
</project>

遗产

请参阅构建多模块站点。

包括生成的内容

基于格式的目录结构中的文件可以通过其目标 HTML 文件名链接到，例如${basedir}/src/site/apt/foo.apt和${basedir}/src/site/fml/faq.fml可以通过以下方式链接：

<project>
  ...
  <body>
    ...
    <menu name="Overview">
      <item name="Foo" href="foo.html" />
      <item name="FAQ" href="faq.html" />
    </menu>
    ...
  </body>
  ...
</project>

还有几个预设菜单可用于站点描述符，以包含项目生成的内容。这些通过ref属性链接，如下所示：

<project>
  ...
  <body>
    ...
    <menu ref="modules" />
    ...
  </body>
  ...
</project>

注意：使用${reports}、${parent}和${modules}的旧语法已被弃用，建议您改用新语法。对旧语法的支持将在站点插件的未来版本中删除。

当前可用的预设菜单有：

  • 报告- 一个菜单，其中包含指向您项目的所有生成报告的链接
  • parent - 带有指向父项目站点的链接的菜单
  • modules - 一个菜单，包含指向该项目子模块站点的链接

将 xhtml 注入 <head>

您可以通过将 head 元素添加到项目站点描述符的 body 元素中，将一些 HTML 代码注入到生成的每个页面的<head>元素中。以下示例添加了一些 javascript：

<project>
  ...
  <body>
    ...
    <head>
      <![CDATA[<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>]]>
    </head>
    ...
  </body>
  ...
</project>

注意：从 Maven 站点插件版本 3.5 开始，如果使用 XHTML 内容，则必须对其进行转义，例如通过 CDATA XML 表示法。以前，XML 内容不需要这种转义。

链接

要在站点徽标下方添加链接，只需将链接元素添加到站点描述符的<body>元素即可。链接元素中的每个项目都将呈现为项目徽标正下方栏中的链接。

<project>
  ...
  <body>
    ...
    <links>
        <item name="Apache" href="http://www.apache.org"/>
        <item name="Maven" href="https://maven.apache.org"/>
    </links>
    ...
  </body>
  ...
</project>

面包屑

如果您的站点模块中存在逻辑层次结构，您可能希望生成一系列面包屑以提供一种轻松导航项目树的方法。

要配置面包屑，请将<breadcrumbs>元素添加到站点描述符中的<body>元素。每个item元素都会渲染一个链接，<breadcrumbs>元素中的item会按顺序渲染。面包屑项目应从最高级别到最低级别列出。

<project>
  ...
  <body>
    ...
    <breadcrumbs>
      <item name="Doxia" href="https://maven.apache.org/doxia/index.html"/>
      <item name="Trunk" href="https://maven.apache.org/doxia/doxia/index.html"/>
    </breadcrumbs>
    ...
  </body>
  ...
</project>

请注意，在多模块构建中，如果父级包含面包屑而继承的站点描述符不包含，则会自动添加具有当前站点描述符名称的面包屑。有关更多详细信息，请参阅有关构建多模块站点的说明。

自定义页脚

您可以通过指定自定义<footer>元素来替换自动生成的页脚内容：

<project>
  ...
  <body>
    ...
    <footer><![CDATA[All rights reserved.]]></footer>
    ...
  </body>
  ...
</project>

注意：从 Maven 站点插件版本 3.5 开始，如果使用 XHTML 内容，则必须对其进行转义，例如通过 CDATA XML 表示法。以前，XML 内容不需要这种转义。

自定义内容

还有一个虚拟<custom>元素可用于指定一些任意内容。请注意，您需要编写自己的速度模板来使用此元素，站点插件使用的默认速度模板会忽略它。

<project>
  ...
  <custom>Custom content</custom>
  ...
</project>

剥皮

可以创建皮肤以一致的方式自定义网站的外观和感觉。有关创建皮肤的更多信息，请参阅创建皮肤。要在项目中使用特定皮肤，请使用站点描述符的<skin>元素。这是一个常规的工件或类似依赖的元素。例如，要使用Maven Fluido Skin，您将包括：

<project>
  ...
  <skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-fluido-skin</artifactId>
    <version>1.8</version>
  </skin>
  ...
</project>

注意： < version>元素是可选的，并且像插件一样，如果省略，将使用可用的最新版本。建议您始终指定一个版本，以便您的站点可以随着时间的推移而重现。

此皮肤将复制必要的资源，包括 CSS，并在必要时使用包含的备用 Velocity 模板来呈现站点。

如果您不指定皮肤，站点插件将使用Maven 默认皮肤。

自定义属性

皮肤的作者可以选择使用他们皮肤独有的自定义属性。然后，皮肤的用户可以使用<custom>元素在他们的site.xml中为这些属性指定他们自己的值。

使用它的一种皮肤是 Maven Fluido 皮肤。在他们的网站上有很多例子展示了自定义属性可以做什么。这是一个例子：

<project>
  ...
  <custom>
    <fluidoSkin>
      <topBarEnabled>true</topBarEnabled>
      <sideBarEnabled>false</sideBarEnabled>
    </fluidoSkin>
  </custom>
  ...
</project>

表达式

site.xml可以包含一些表达式，例如$ {project.name}。呈现站点时将评估每个表达式。

表达式可以是：

  • ${project.*}，例如<project><organization><name>中引用的${project.organization.name}
  • ${project.properties}，例如<project><properties><myProperty>中引用的${myProperty}
  • ${environmentVariable}，例如${JAVA_HOME}

注意：此插件的 2.0-beta-5 版本中支持某些表达式，例如${project.name}。从 2.0-beta-6 版本开始提供全面支持。此外，在内容页面中使用虚线项目属性还有其他限制。有关将属性注入内容页面的详细信息，请参阅过滤。