由 Maven 构建

创建内容

现在是时候为您的网站创建一些内容了。在 Maven 2 中，站点内容由格式构成，因为支持多种格式。

文档格式

以下是网站目录结构的示例：

+- src/
   +- site/
      +- apt/
      |  +- index.apt
      |
      +- fml/
      |  +- general.fml
      |  +- faq.fml
      |
      +- markdown/
      |  +- markup.md
      |
      +- xdoc/
      |  +- other.xml
      |
      +- xhtml/
      |  +- xhtml-too.xhtml
      |
      +- xhtml5/
      |  +- xhtml5-content.xhtml5
      |
      +- site.xml

${basedir}/src/site目录，其中包含站点描述符以及与支持的文档格式对应的各种目录。让我们看一下各种文档格式的示例。

  • APT：APT 格式（“几乎纯文本”）是一种类似于 wiki 的格式，可让您非常快速地编写简单的结构化文档（如本文档）。APT 格式的完整参考是可用的。
  • FML：FML 格式是FAQ 格式。这与 Maven 1.x 中使用的相同。有关FML 格式的更多信息，请查看Doxia网站。
  • XDoc：XDoc 格式与Maven 1.x 中使用的相同。XDoc 格式的参考可用。
  • Markdown（从 maven-site-plugin 3.3 开始）：Markdown是一种广泛使用的标记语言。

其他格式也可以，但以上四种格式默认是网站插件识别的。也可以使用存在 Doxia 解析器的任何其他文档格式（请参阅Doxia 标记语言列表），但在这种情况下，您需要将相应的 Doxia 依赖项添加到您的站点插件配置中，如上一段所述。请注意，Doxia 还支持多种输出格式，站点插件仅创建 XHTML5。

请注意，以上所有内容都是可选的 - 在其中一棵输入树中只需要一个索引文件。每种格式下的路径都会合并在一起，形成站点的根目录。在上面的示例中运行“ mvn site:site ”后，您将在目标目录中得到这个：

+- target/
   +- site/
      +- css/
      |
      +- images/
      |
      +- index.html
      +- general.html
      +- faq.html
      +- other.html
      +- xhtml-too.html
      +- xhtml5-content.html

这意味着/src/site/apt/index.apt将在站点中以/index.html的形式出现。因此，在您的站点描述符中，您可能会链接到/index.html和/other.html，这两个文件的来源将是/src/site/apt/index.apt和/src/site/xdoc/other.xdoc .

css和images目录包含来自正在使用的皮肤的样式表和图像。您可以在站点描述符文档中阅读有关皮肤的更多信息。

添加额外资源

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

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

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

文件pic1.jpg将通过对站点中任何页面的图像目录的相对引用获得。

过滤

要将属性过滤为任何受支持的文档格式，请在文件名中添加.vm扩展名。

例如，Maven 网站的模块包含一个content/xdoc/download.xml.vm文件，该文件使用表达式${currentStableVersion}过滤POM中的属性集。

注意： Apache Velocity用于应用过滤。

一些属性是默认定义的：查看Doxia Site Renderer's Velocity processing reference了解更多信息。有关完整的使用概述，请参阅 Velocity 的用户指南。

从 3.5 版开始，您可以通过将saveProcessedContent设置为true来保存已处理的标记：有关更多详细信息，请参阅相应的文档。

常见问题和解决方法

  • 虚线属性：

    由于 Velocity 使用点符号来遍历 bean，因此您不能直接使用<properties>中定义的点属性。

    通常建议使用$context工具访问属性：例如，使用$context.get("my.property")。

  • Markdown 与 ## 语法上的 Velocity 冲突：

    由于##表示 Velocity 中的单行注释，因此使用此语法的 Markdown 标头会从生成的内容中抑制。

    您可以使用未解析的内容语法 #[[##]]#或转义工具，如${esc.h}${esc.h}。

国际化

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

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

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.11.0</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)

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