创建站点
创建内容
创建网站的第一步是创建一些内容。在 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)
每种语言都有一个站点描述符,翻译的站点可以独立发展。