Maven – 创建站点的指南

创建站点

创建内容

创建网站的第一步是创建一些内容。在 Maven 中，站点内容是按格式分隔的，因为有几个可用的。

+- src/
   +- site/
      +- apt/
      |  +- index.apt
      !
      +- markdown/
      |  +- content.md
      |
      +- fml/
      |  +- general.fml
      |  +- faq.fml
      |
      +- xdoc/
      |  +- other.xml
      |
      +- site.xml

您会注意到现在有一个${basedir}/src/site目录，其中包含site.xml站点描述符以及与支持的文档类型相对应的各种目录。

让我们看一下各种文档类型的示例：

apt：APT 格式，“几乎是纯文本”，是一种类似于 wiki 的格式，可让您非常快速地编写简单的结构化文档（如本文）。APT 格式的完整参考可用，
markdown：众所周知的Markdown格式，
fml: FML 格式是FAQ 格式，
xdoc：符合一组小而简单的标记的 XML 文档，请参阅完整参考。

其他格式可用，但目前这 4 种是经过最佳测试的。

还有几种可能的输出格式，但对于 Maven Site Plugin，只有 XHTML 可用。

请注意，以上所有内容都是可选的 - 在其中一棵输入树中只需要一个索引文件。每个路径将合并在一起以形成站点的根目录。

自定义外观

如果您想调整网站的外观，您可以使用自定义外观来提供您自己的 CSS 样式。如果这还不够，您甚至可以调整 Maven 用来生成站点文档的输出模板。

您可以访问皮肤索引以查看一些可用于更改站点外观的皮肤。

生成站点

生成网站非常简单，而且速度很快！

mvn site

默认情况下，生成的站点将位于target/site/...

有关 Maven 站点插件的更多信息，请参阅maven-site-plugin 参考。

部署站点

经典网站部署

为了能够使用经典网络协议（ftp、scp、webdav）部署站点，您必须首先在您的中声明要分发到的位置pom.xml，类似于部署的存储库：

<project>
  ...
  <distributionManagement>
    <site>
      <id>website</id>
      <url>scp://www.mycompany.com/www/docs/project/</url>
    </site>
  </distributionManagement>
  ...
</project>

该<id>元素标识存储库，以便您可以使用该元素settings.xml将凭据附加到文件中，就像对任何其他存储库一样， <servers>
<url>给出了要部署到的位置。目前默认只支持SSH，如上复制到www.mycompany.com路径中的主机/www/docs/project/，但您可以根据需要添加更多协议。如果子项目从父 POM 继承站点 URL，它们将自动<artifactId>附加它们以形成其有效的部署位置。

配置分发位置后，使用site-deploy站点生命周期的阶段完成站点的部署。

mvn site-deploy

GitHub 页面，Apache svnpubsub/gitpubsub 部署

当使用 SCM 提交完成站点发布时，例如使用GitHub Pages或Apache svnpubsub/gitpubsub，部署站点将使用Maven SCM Publish Plugin完成。

例如，托管在 GitHub 上的项目并使用 GitHub Pages 进行站点发布：

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-scm-publish-plugin</artifactId>
      <version>3.1.0</version>
      <configuration>
        <pubScmUrl>${project.scm.developerConnection}</pubScmUrl>
        <scmBranch>gh-pages</scmBranch>
      </configuration>
    </plugin>

部署站点分两步完成：

site使用站点生命周期的阶段来暂存内容，然后site:stage：mvn site site:stage
将暂存站点发布到 SCM：mvn scm-publish:publish-scm

创建站点描述符

该site.xml文件用于描述站点的结构。下面给出一个示例：

<?xml version="1.0" encoding="ISO-8859-1"?>
<project xmlns="http://maven.apache.org/DECORATION/1.8.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 https://maven.apache.org/xsd/decoration-1.8.0.xsd"
  name="Maven">
  <bannerLeft>
    <name>Maven</name>
    <src>https://maven.apache.org/images/apache-maven-project.png</src>
    <href>https://maven.apache.org/</href>
  </bannerLeft>
  <bannerRight>
    <src>https://maven.apache.org/images/maven-small.gif</src>
  </bannerRight>

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

    <menu name="Maven 2.0">
      <item name="Introduction" href="index.html"/>
      <item name="Download" href="download.html"/>
      <item name="Release Notes" href="release-notes.html" />
      <item name="General Information" href="about.html"/>
      <item name="For Maven 1.x Users" href="maven1.html"/>
      <item name="Road Map" href="roadmap.html" />
    </menu>

    <menu ref="reports"/>

    ...
  </body>
</project>

注意：上面的<menu ref="reports"/>元素。在构建站点时，它会被一个包含指向您已配置的所有报告的链接的菜单所取代。

有关站点描述符的更多信息，请访问Maven 站点插件的专用页面。

添加额外资源

您可以将任意资源添加到您的站点，方法是将它们包含在resources如下所示的目录中。css额外的 CSS 文件将在它们被放置在目录中的目录中时被拾取resources。

+- src/
   +- site/
      +- resources/
         +- css/
         |  +- site.css
         |
         +- images/
            +- pic1.jpg

该文件site.css将被添加到默认的 XHTML 输出中，因此可以根据需要使用它来调整默认的 Maven 样式表。

该文件pic1.jpg将通过对images您站点中任何页面的目录的相对引用提供。

配置报告

Maven 有几个报告，您可以将它们添加到您的网站以显示项目的当前状态。这些报告采用插件的形式，就像用于构建项目的那些一样。

通过从 POM 收集信息可以获得许多标准报告。目前默认提供的是：

依赖性报告
邮件列表
持续集成
源存储库
问题跟踪
项目团队
执照

要了解更多信息，请参阅项目信息报告插件。

要将这些报告添加到您的站点，您必须将项目信息报告插件添加到<reporting>POM 中的特殊部分。以下示例显示如何配置标准项目信息报告，以友好的格式显示来自 POM 的信息：

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-project-info-reports-plugin</artifactId>
        <version>2.8</version><!-- define version here if not already defined in build/plugins or build/pluginManagement -->
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

如果您在描述符中包含了适当的<menu ref="reports"/>标签site.xml，那么当您重新生成站点时，这些项目将出现在菜单中。

许多其他插件提供报告目标：在插件列表的“类型”列中查找“R”（报告）值。当插件同时是 Build 和 Reporting 插件时，通常不需要在报告部分明确定义版本，因为报告将使用来自build/plugins或的版本build/pluginManagement。从 Maven Site Plugin 3.4 开始，报告插件也从build/pluginManagement.

注意：许多报告插件提供了一个名为outputDirectory或类似的参数来指定其报告输出的目的地。此参数仅在报告插件独立运行时才相关，即直接从命令行调用。相反，当报告作为站点的一部分生成时，Maven 站点插件的配置将确定有效的输出目录，以确保所有报告最终都位于中心位置。

国际化

Maven 中的国际化非常简单，只要您使用的报告定义了特定的语言环境。有关支持的语言的概述以及如何添加更多语言的说明，请参阅来自 Maven 站点插件的相关文章国际化。

要启用多个语言环境，请将类似于以下内容的配置添加到您的 POM：

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.4</version>
        <configuration>
          <locales>en,fr</locales>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

这将生成网站的英文和法文版本。如果en是您当前的语言环境，那么它将在站点的根目录中生成，并在fr/子目录中包含该站点的法语翻译副本。

要为该翻译添加您自己的内容而不是使用默认内容，请在您的站点目录中放置一个具有该语言环境名称的子目录，并使用文件名中的语言环境创建一个新的站点描述符。例如：

+- src/
   +- site/
      +- apt/
      |  +- index.apt     (Default version)
      |
      +- fr/
      |  +- apt/
      |     +- index.apt  (French version)
      |
      +- site.xml         (Default site descriptor)
      +- site_fr.xml      (French site descriptor)

每种语言都有一个站点描述符，翻译的站点可以独立发展。