使用StaGen来生成静态网站

Published: 14 Apr 2014 Category: Others

译注：StaGen是一个功能极其简单的静态站点生成器，因此它非常容易上手，同时它还是用Java 8写的，有兴趣的话可以看下它的源代码。当然我个人还是比较喜欢Jekyll。

在没有StaGen之前，我一直都在用RapidWeaver来管理我的网站 WizTools.org。RapidWeaver生成的文本格式真的让人很抓狂,这个软件浪费了我太多时间。StaGen的诞生解决了这些问题。我连夜完成了第一个版本。第二天就把我的网站WizTools.org给迁移到StatGen上面了。StaGen的设计目标就是希望能让只有少数几个页面的简单站点的开发和管理变得更容易一些。出于这个的考虑，我选择了markdown作为文档格式，StringTemplate作为内容模板，并使用JSON来存储配置信息。

目录结构

StaGen管理的网站项目需要遵循如下的目录结构：

.
`-- content
|   |-- index.md
|   |-- other.md
`-- config
|   |-- other.json
|-- master.json
`-- static
|   |-- my.css
`-- template
|   |-- index.st
|   |-- other.st

各个文件夹的作用如下：

+content: 这个文件夹用来存储markdown格式的文档。生成的网站中会为每篇文章都单独生成一个HTML文件。content下面的子目录会被StaGen忽略。 +config: 每个页面都可以有一些单独的配置信息。配置信息是用JSON格式来存储的。文件名必须和content中的文件名匹配。 +master.json：这是主配置文件。里面存储了网站全局的配置信息。 +static: 网站中用到的静态资源文件，比如.js，.css以及图片等。 +template: StringTemplate 4模板会放在这个目录下。

StaGen是如何工作的

StaGen引擎处理的顺序是这样的：

  1. 加载主配置文件master.json
  2. 将静态资源文件拷贝到目标文件夹（网站生成的时候会自动创建一个叫target的文件夹）
  3. 对于content目录下的每一个markdown文件： 加载对应的配置信息（下节中会有介绍） 将配置信息应用到对应的模板上，并把结果的HTML文件输出到目标文件夹

加载配置

配置信息是一个JSON类型的map:

{
"title": "My Site Title",
"activities": ["Dance", "Jump", "Shout"]
}

注意，key必须是字符串，值可以是任意类型的。

前面已经提到过，站点的全局配置是master.json。StaGen在一开始的时候便会加载这个配置文件。当处理到每一篇文章时（比如index.md），StaGen会尝试从config/index.json中加载对应的配置信息。它会覆盖掉主配置文件中的配置信息。也就是说，如果你已经在master.json和config/index.json中都定义了标题，当渲染index.md时，使用的是config/index.json里面的配置。如果config/index.json文件不存在，也无所谓——那就用master.json里面的配置好了。

模板渲染

StaGen使用的是StringTemplate作为模板。下面是一个简单的模板，它用到了前面提到的JSON配置信息：

<html>
...
<title>$titleprebuffer_2lt;/title>
...
<ol>
$activities: {activity|
<li>$activityprebuffer_2lt;/li>
}$
</ol>
...
$_content$
...
</html>

$_content$就是markdown文件渲染出来的HTML。

模板渲染遵循如下的规则：

  1. 尝试按文章的名字加载模板，比如content.md，StaGen引擎会加载other.st。
  2. 如果没有指定专门的模板，则使用默认的index.st模板。因此你要确保你的项目中确实有一个index.st模板。

模板内嵌套模板

你可以在.st文件里再包含一个别的模板，比如你有一个ga.st(ga->Google Analytics)文件，要引入到主模板文件index.st中。在index.st里面你可以这么写：

$ga()$

index.st里面会包含ga.st渲染后的内容。需要注意的是，index.st中的所有变量对引入的模板都是可见的。

StaGen的使用

StaGen是以一个jar包的形式发布的。想获取这个工具的帮助信息的话：

java -jar ~/stagen-VER-full.jar -h

从项目里生成站点：

java -jar ~/stagen-VER-full.jar gen

上述命令将会在target目录中生成一个静态网站。

想清除target目录的话：

java -jar ~/stagen-VER-full.jar clean

如果你刚开始用StaGen，想创建一个新的项目结构：

java -jar ~/stagen-VER-full.jar init

总结

StaGen故意设计得非常简单。我自己不会用它来管理太复杂的站点。它不像别的静态网站生成器那样能支持博客或者主题。我相信，StaGen不支持这些特性，这也正是它的过人之处。

原创文章转载请注明出处：使用StaGen来生成静态网站

英文原文链接