Wintersmith入门：基于Node.js的静态站点生成器

I’ve spoken and written on the topic of static site generators a lot lately. Generally speaking, I tend to recommend going with Jekyll as the most stable and feature-rich option for building static sites available today. However, the fact that Jekyll is Ruby-based can be a deal-breaker for some developers, especially those not familiar with Ruby. The single most frequent question I get is: “Is there a good option based upon JavaScript and available via npm?”

最近，我已经谈到静态站点生成器这个话题。 一般来说，我倾向于建议使用Jekyll作为当今构建静态站点最稳定，功能最丰富的选项。 但是，Jekyll是基于Ruby的事实对于某些开发人员，特别是不熟悉Ruby的开发人员，可能是一个大问题。 我得到的最常见的单个问题是：“是否有一个基于JavaScript且可以通过npm获得的好选择？”

In this article, first of a two-part series, we’ll cover one such option, Wintersmith. Wintersmith is a robust static site generator with one biggest impediment being (in my opinion): a lack of detailed documentation. Hopefully this article will help anyone interested in a JavaScript-based option available via npm to get started building static sites with Wintersmith.

在本文中，这是一个分为两部分的系列文章的第一篇，我们将介绍一个这样的选项Wintersmith 。 温特史密斯(Wintersmith)是一个强大的静态网站生成器，最大的障碍是(我认为)：缺乏详细的文档。 希望本文对所有可以通过npm获得基于JavaScript的选项感兴趣的人，帮助他们开始使用Wintersmith构建静态网站。

样本网站 (The Sample Site)

For this article, we’ll use the sample site I built and that you can find here. The sample is an Adventure Time! fan site that looks like the image below.

对于本文，我们将使用我构建的示例站点，您可以在此处找到。 该示例是一个冒险时间！ 如下图所示的粉丝网站。

The goal of the project was to rebuild this site using a number of static site generators to compare them. While the site is intentionally simple, it contains a number of key features that we’ll look at in Wintersmith:

该项目的目标是使用许多静态站点生成器来比较此站点，以重建此站点。 虽然该站点特意简单，但它包含许多关键功能，我们将在Wintersmith中进行介绍 ：

• Custom global metadata – the ability to set custom metadata global to the site that can be accessed and used in templates;
  自定义全局元数据–可以在网站上全局设置可在模板中访问和使用的自定义元数据的功能；
• Custom post metadata – the ability to set custom metadata on a per post basis that can be accessed when listing the post or in the display of the post itself;
  自定义帖子元数据–可以基于帖子设置自定义元数据的功能，可以在列出帖子时或在帖子本身的显示中进行访问；
• Data sets – the ability to add content that is not a post or page, but rather a custom data type (in the case of this sample that is the character data).
  数据集–添加不是帖子或页面而是自定义数据类型(在此示例中为字符数据)的内容的功能。

All of the character data, content and images used in the sample are from the Adventure Time! wiki. The design was based upon a free template from HTML5UP.

示例中使用的所有角色数据，内容和图像均来自Adventure Time！ 维基 该设计基于HTML5UP的免费模板。

如何设置温特史密斯 (How to Set up Wintersmith)

One of the benefits of Wintersmith being based on Node.js and npm is that the installation process is super simple. You have to execute the command below to install it (note: the sudo isn’t necessary on Windows):

Wintersmith基于Node.js和npm的好处之一是安装过程非常简单。 您必须执行以下命令来安装它(注意：在Windows上不需要sudo )：

$ sudo npm install -g wintersmith

That’s it – you’re good to go! Now let’s create a new project.

就是这样–你很好！ 现在让我们创建一个新项目。

创建一个网站 (Creating a Site)

To create a new site using Wintersmith, enter the following command:

要使用Wintersmith创建新站点，请输入以下命令：

$ wintersmith new [project name]

For the example site, we’ll give the project a name of “wintersmithsite”. So the command to execute is:

对于示例站点，我们将项目命名为“ wintersmithsite”。 因此要执行的命令是：

$ wintersmith new wintersmithsite

It will generate a folder with the given project name that includes a bunch of files that we can modify to start building our website.

它将使用给定的项目名称生成一个文件夹，其中包含一堆文件，我们可以对其进行修改以开始构建网站。

If we take a look at the generated files, we’ll see that Wintersmith places the configuration, the templates, and the plugins at the root level while the site files are placed within a folder named “contents”.

如果我们查看生成的文件，我们将看到Wintersmith将配置，模板和插件放在根级别，而将站点文件放在名为“ contents”的文件夹中。

测试网站 (Testing the Site)

To run the project on a local server, change directory and start a preview:

要在本地服务器上运行项目，请更改目录并开始预览：

$ cd wintersmithsite
$ wintersmith preview

By default, the local server runs on port 8080, so we can open the site by browsing to http://localhost:8080. We can specify a different port using the -p option. Besides, by default, the server is verbose and will output detailed error messages and loaded resources to the console. There are a number of other options to the server which we can learn by entering the command:

默认情况下，本地服务器在端口8080上运行，因此我们可以通过浏览到http://localhost:8080来打开站点。 我们可以使用-p选项指定其他端口。 此外，默认情况下，服务器是冗长的，并且将向控制台输出详细的错误消息和已加载的资源。 通过输入以下命令，我们可以了解服务器的许多其他选项：

$ wintersmith preview -help

The options can also be set within the site configuration file that is named config.json, but for now, the defaults should work fine.

也可以在名为config.json的站点配置文件中设置这些选项，但是现在，默认设置应该可以正常工作。

模板基础 (Templating Basics)

Wintersmith uses Jade as its templating language by default. This tutorial will use it, but Wintersmith has a good number of plugins available if you prefer a different templating language.

默认情况下，Wintersmith使用Jade作为其模板语言。 本教程将使用它，但是如果您喜欢其他模板语言，Wintersmith提供了许多插件 。

Templates go in the “templates” folder in the root directory of the site. Jade is a very terse templating language – there are no brackets, no closing tags and indentation matters. Let’s look at some of the basics of how you can create templates using Jade.

模板位于站点根目录中的“ templates”文件夹中。 Jade是一种非常简洁的模板语言-没有括号，没有结束标记和缩进问题 。 让我们看一下如何使用Jade创建模板的一些基础知识。

输出数据 (Output Data)

Jade provides multiple ways of outputting data from variables. The most common when building a site template is to set a tag equal to the value of a variable. For instance, the following example from templates/article.jade will place the title of an article within a opening and closing <h2> tags.

Jade提供了多种从变量输出数据的方式。 构建网站模板时，最常见的方法是将标记设置为等于变量的值。 例如，以下来自templates/article.jade示例将文章标题放置在开始和结束<h2>标签内。

h2= page.title

By default the contents of the variable are escaped before outputting. This means that if it contains HTML, the tags will not be rendered in the output but, rather, displayed as plain text. When we need them unescaped, we have to add an exclamation point, as in this example from templates/article.jade:

默认情况下，变量的内容在输出前会转义。 这意味着，如果它包含HTML，则标记将不会在输出中呈现，而是显示为纯文本。 当我们需要对它们进行转义时，我们必须添加一个感叹号，如本示例中的templates/article.jade ：

section.content!= typogr(page.html).typogrify()

We can do the same with attributes. The following example from templates/partials/homepagemiddle.jade creates an <a> tag with the href attribute equal to the article’s URL.

我们可以对属性做同样的事情。 以下来自templates/partials/homepagemiddle.jade示例创建一个<a>标记，其href属性等于该文章的URL。

a(href= article.url, class="image featured")

If you’re curious what variables are made available on a page object by default, the documentation lists them. I should note that the article variable above is not a default but is the result of a loop, which we’ll discuss later on.

如果您想知道默认情况下页面对象上提供了哪些变量， 文档会列出它们。 我应该注意，上面的article变量不是默认值，而是循环的结果，我们将在后面讨论。

Another way to output variables using Jade is to use #{ variableName }. When we do this, the content of the variable is escaped. There are no examples of this method within our sample.

使用Jade输出变量的另一种方法是使用#{ variableName } 。 当我们这样做时，变量的内容将被转义。 我们的示例中没有此方法的示例。

If you want to output the contents of a variable unescaped, the syntax to use is !{ variableName }. For example, when we are outputting the content of the body of a post, we’ll want any tags within it to be rendered. One example is taken from templates/partials/homepagemiddle.jade:

如果要输出未转义的变量的内容，则使用的语法为!{ variableName } 。 例如，当我们输出帖子正文的内容时，我们将希望呈现其中的任何标签。 一个示例来自templates/partials/homepagemiddle.jade ：

| !{ typogr(article.intro).typogrify() }

The pipe preceding the previous line of code means that the content will be showed as plain text.

上一行代码之前的管道表示内容将以纯文本形式显示。

npm模块 (npm Modules)

You may be wondering what the typogrify() calls are all about. Well, one of the benefits of Wintersmith is that it supports the use of npm modules. The generated site includes three: typogr (which is what you see used above); Moment.js (to learn more about moment, you can read the article Managing Dates and Times Using Moment.js); and Underscore.

您可能想知道typogrify()调用的全部typogrify() 。 好吧，温特史密斯的好处之一是它支持使用npm模块。 生成的站点包括三个： typogr (这是您在上面看到的)； Moment.js (要了解有关时刻的更多信息，您可以阅读文章使用Moment.js管理日期和时间 )； 和下划线 。

Let’s look at using Moment.js for formatting a date within a template, as in this example from templates/partials/homepagemiddle.jade:

让我们看一下如何使用Moment.js在模板中格式化日期，如本示例中的templates/partials/homepagemiddle.jade ：

p= "Posted " + moment.utc(article.date).format('MMM DD, YYYY')

Moment.js offers a lot more functionality than just formatting, and all of that is available from within our templates. But, we aren’t limited to only Moment.js, as we can just add any npm module to the require section of the config.json for our site, npm install it and use the module in our templates.

Moment.js提供的功能不仅仅是格式化，而且所有功能都可以从我们的模板中获得。 但是，我们不仅限于Moment.js，因为我们可以将任何npm模块添加到我们网站的config.json的require部分中， npm install它并在我们的模板中使用该模块。

包括 (Includes)

We’ll want to split up templates in order to make them more maintainable and reusable. We can do this using includes. This code from templates/index.jade includes the templates/partials/header.jade file (notice you do not need the .jade file extension):

我们将希望拆分模板，以使其更具可维护性和可重用性。 我们可以使用include来做到这一点。 这从代码templates/index.jade包括templates/partials/header.jade文件(通知你不需要.jade文件扩展名)：

include ./partials/header

Jade also supports inheritance, which can be used for creating similar, separate, and reusable blocks of template code. If you want more details on inheritance, check the documentation.

Jade还支持继承，该继承可用于创建相似，独立且可重用的模板代码块。 如果您需要有关继承的更多详细信息， 请查阅文档 。

有条件的 (Conditionals)

There are cases where you might want to display different aspects of a template based upon certain conditions. This can be done using conditionals in Jade. Jade supports if, else if, else and unless, which is effectively a negated version of if.

在某些情况下，您可能希望根据某些条件显示模板的不同方面。 这可以使用Jade中的条件语句来完成。 Jade支持if ， else if ， else和unless ，这实际上是if的否定版本。

This example from templates/partials/header.jade only displays the banner if we are not on a page (every post in our site is a page, so this means only display it on the home page, index.html):

如果没有在页面上，此来自templates/partials/header.jade示例仅显示横幅(我们网站上的每个帖子都是页面，因此这意味着仅将其显示在主页index.html )：

if !page
    section(id="banner")
        header
            h2 Explore the Land of Ooo...
            p ...and its many kingdoms!

This conditional could also have been written as unless page.

该条件也可以写成unless page 。

Jade also supports case statement blocks. In case you want to learn more, please refer to the official documentation.

Jade还支持case语句块。 如果您想了解更多信息， 请参阅官方文档 。

循环播放 (Looping)

Looping is something we’ll do a lot of in our templates, whether we are looping through posts or data. For such needs, Jade supports both each and while loops.

循环是我们在模板中要做的很多事情，无论我们是循环浏览帖子还是数据。 为此，Jade支持each和while循环 。

The following example from templates/partials/homepagemiddle.jade outputs all of our character data using an each loop. In the middle of the home page, we display each character with its image, name, and description. The each loop iterates over every object in the array and assigns it to the variable character where we can access its properties.

以下来自templates/partials/homepagemiddle.jade示例使用each循环输出我们所有的字符数据。 在主页中间，我们显示每个字符及其图像，名称和描述。 each循环都会遍历数组中的每个对象，并将其分配给变量character ，以便我们可以访问其属性。

each character in contents.characters
    div(class="4u")
        section(class="box")
            span(class="image featured")
                img(src= character.metadata.image)
            header
                h3= character.metadata.name
            p= character.metadata.description

Unfortunately, there is no support for adding a limit or an offset to a loop. Instead, we can do this by combining variables and conditionals. In the following example, we are only showing the first two posts (similar to limit). Keep in mind that the lines setting variables (i and articles) have a preceding - to indicate that they will run on the server during compile time. This means that there is no corresponding code generated in the output of the template.

不幸的是，不支持在循环中添加限制或偏移量。 相反，我们可以通过组合变量和条件来做到这一点。 在下面的示例中，我们仅显示前两个帖子(类似于limit)。 请记住，设置变量的行( i和articles )前面有一个-表示它们将在编译时在服务器上运行。 这意味着在模板的输出中没有生成相应的代码。

- var i=0
 - var articles = env.helpers.getArticles(contents);
 each article in articles
     - i++
     if i<3
         div(class="6u")
             section(class="box")
                 a(href= article.url, class="image featured")
                     img(src= article.metadata.banner)
                 header
                     h3= article.title
                     p= "Posted " + moment.utc(article.date).format('MMM DD, YYYY')
                 | !{ typogr(article.intro).typogrify() }
                 footer
                     ul(class="actions")
                         li
                             a(href= article.url, class="button icon fa-file-text") Continue Reading

You will notice that we use env.helpers.getArticles(contents); to get an array of articles in the contents/articles folder. This isn’t well documented from what I could tell, but this method comes from the paginator plugin, which can be configured in config.json.

您会注意到我们使用env.helpers.getArticles(contents); 在content / articles文件夹中获取一系列文章。 据我所知，这还没有得到很好的证明，但是此方法来自paginator插件 ，可以在config.json进行配置。

The next example and last example of this article replicates using both an offset and a limit to show the next five articles after the first two:

本文的下一个示例和最后一个示例都使用偏移量和限制进行复制，以显示前两个之后的下五个文章：

- var i=0
- var articles = env.helpers.getArticles(contents);
each article in articles
    -i++
    if (i>2) && (i<8)
        li
            span(class="date")
                !=moment.utc(article.date).format('MMM')
                strong= moment.utc(article.date).format('DD')
            h3
                a(href=article.url)= article.title
            p= article.metadata.shortdesc

结论 (Conclusion)

In this article I’ve introduced you to Wintersmith, which is a solid option if you’re looking for a Node.js-based static site generator. I covered how to install and get started with Wintersmith and also discussed some features of Jade, its default templating system. In the second installment, I’ll teach you how to create posts using the Markdown format, how to set custom Metadata, and also how to generate and deploy your static website.

在本文中，我向您介绍了温特史密斯(Wintersmith)，如果您正在寻找基于Node.js的静态站点生成器，那么这是一个不错的选择。 我介绍了如何安装和开始使用Wintersmith，还讨论了默认模板系统Jade的一些功能。 在第二部分中 ，我将教您如何使用Markdown格式创建帖子，如何设置自定义元数据以及如何生成和部署静态网站。

As you’ve seen, one of the interesting aspects of Wintersmith is its ability to leverage npm modules. This offers developers a lot of choices when customizing their site or add additional functionality that they may need.

如您所见，Wintersmith有趣的方面之一是其利用npm模块的能力。 在自定义站点或添加他们可能需要的其他功能时，这为开发人员提供了很多选择。

翻译自: https://www.sitepoint.com/getting-started-wintersmith-nodejs-static-site-generator/