Harp中文文档

原创 yBmZlQzJ 2023-09-05

706

前言

Harp 是一个支持预处理的静态 Web 服务器，支持 Jade, Markdown, EJS, CoffeeScript,Sass,LESS 和 Stylus asHTML,CSS& JavaScript 的预处理，无需额外配置。特点是快速而且轻量级。

Harp 在构建移动 web 应用，博客，文档，游戏，营销网站，简报，可以让前端构建出很多很棒的东西。

主观但公正的来说在"应用服务器"标准下，Harp 是非常快速的，如果和 Nginx 或 Apache 这样的服务器相比，尤其涉及到静态功耗上，Harp 可能略显不足。

本课程是官方文档的中文版。

适用人群

本教程主要适用于希望了解并学习 Harp 静态服务器的开发及运维人员。

学习前提

在学习本课程之前，我们假设你之前了解过其他如 Apache 或 Nginx 服务器并对服务器配置有一定了解。

原文: http://harpjs.com/docs/

1

Harp 文档

安装 Harp

通过一个视频和教程快速开始。

理解基本规则，5 个基本规则，在你创建自己的 Harp 应用时可以帮上忙。

第 1 章环境

学习如何在任何你需要的地方运行 Harp：
- 本地，当你设计和开发静态站点或者客户端应用时。
- 作为中间件，让 Harp 作为 Express 和 node.js 创建的更大型的应用的 asset pipeline。
- 生产环境，Harp 可以作为网页服务器，缓存以及服务静态内容。

第 1 章开发

阅读规则，一个立即获取 Harp 大部分内容的单页教程。

如果你正在使用预处理器来写 HTML，CSS，或者 JavaScript，Harp 将会使你的项目出奇的简单。Harp 支持 Markdown， EJS， Jade， LESS， Sass， Stylus，以及 CoffeeScript。

第 1 章部署

学习如何在生产模式下部署 Harp，让它服务你的应用。或者，将你的项目编译成 HTML，CSS，以及 JavaScript，这样就可以部署在任何地方。

通过 Harp 平台，在线获取一个 Harp 应用最简单的方式，你可以整个跳过。

第 1 章贡献

贡献 Harp

Harp 很幸运地有一个回馈它的社区。无论你是对修复一个 bug 还是添加新功能感兴趣，这个手册都有所覆盖。

第 1 章获取帮助

开启你在 Harp 平台上的自由旅行，发布 Harp 应用的最省力方式。所有的计划都包含对 Harp 的支持。

订阅 Harp 每周新闻

每周，我们都会写一些关于客户端应用，静态站点，以及 Harp 专栏教程的新东西。

在 #harp IRC channel 寻求帮助

在 IRC 频道有一个活跃的社区，他们非常乐于回答你可能会遇到的问题。

在 Github 上提交一个 issue

发现问题？有所建议？提交 issue 吧

在推特上给 @HarpWebServer 发消息
Stack Overflow，通过标签 "harp"，在 Stack Overflow 上提问和回答问题

2

快速开始

这份指南将会指导你安装 Harp。你将会创建并维护一个简单的项目，开发模式下能够自动进行预处理，而在生产模式下会缓存预处理的数据以获取更好的性能。

#

安装 Harp web server

Youtube 视频

首先，安装 Node.js。虽然 Harp 使用了 Node.js，但即便不了解 Node.js, 或者没有接触过 JavaScript ，也是可以上手 Harp 的。在 Node.js 安装完成后，就可以使用 Node.js 的包管理器 mighty npm 来安装 Harp 了。这是个基于命令行的工具。

#

在 OS X 和 Linux 环境下

使用任意的终端工具打开命令行。OS X 上，它位于应用->实用程序->终端。Ubuntu 上，位于应用->终端。然后，运行下面的命令：

sudo npm install -g harp

#

在 Windows 环境下

如果你在使用 Windows, Node.js 的安装包已经包含了一个 Node.js 的命令行程序。直接输入如下命令即可安装：

npm install -g harp

#

创建一个应用

Harp 可以非常容易的提供服务，简单到像一个 index.html
一样。因为 Harp 有一个内嵌的预处理器，所以你可以很方便的用模板语言来创建 HTML。比如，用下面的命令行来创建一个 index.jade
文件：

mkdir hello-world
cd hello-world
echo h1 Hello World >> index.jade

以上命令将会创建一个 hello-world 目录用于 Harp 应用。然后，在目录里面，一个 index.jade 被创建出来，然后被处理成 <h1>Hello world</h1>
。

#

启动 web server

用默认的 9000 端口启动 Harp web server。

harp server --port 9000

打开浏览器访问 localhost:9000 即可看到以下内容：

图片 2.1 image

#

编译项目

你可以把 Harp 编译后当作一个 web server 来使用。然而 Harp 是为了造出优秀的静态站点而生的。

harp compile

#

将 Harp 投入生产环境

为了将 Harp 投入生产，你只需要做如下这几点：在生产环境，Harp 将缓存经过预处理的输出以获得尽可能快的性能。在当前这个 case 里面，缓存 index.jade 的预处理结果。别忘了在生产环境里使用 production 标志位 (flag)。

NODE_ENV=production sudo harp server --port 80

你无需在生产环境中手工跑 Harp 来上线新版本。事实上，最简单的办法是使用 Harp Platform，你可以使用 Dropbox 来创建 Harp App，不仅如此，还能多人协作。

你还可以在 Heroku, 上面运行生产环境的 Harp，将 Harp 部署到 GitHub Pages，针对 Apache Cordova/PhoneGap 编译 Harp 应用。

#

接下来要做的事

上面只是一次尝试。举个例子，默认 Harp 应用还包括一个 .less
文件，被当成 .css
文件来处理。通过修改 LESS 文件就能调整 CSS，不需要额外配置就可以从默认 App 开始做整个项目。更多信息请阅读 initializing the default Harp app.

3

安装 Harp

安装 Harp，需要 Node.js 环境，可以安装在 OS X，Windows，Linux，以及 SmartOS 上。从 Node.js 网站上下载

视频

首先，安装 Node.js. 虽然 Harp 使用了 Node.js ，但即便不懂 Node.js, 甚至哪怕连 JavaScript 都没学过，也是可以上手 Harp 的。等 Node.js 安装完成后，就可以使用 Node.js 的包管理器 mighty npm 来安装 Harp 了，这是个基于命令行的工具。

#

在 OS X 和 Linux 环境下

使用任意的终端工具打开命令行。OS X 上，它位于应用->实用程序->终端。Ubuntu 上，位于应用->终端。然后，运行下面的命令：

sudo npm install -g harp

如果拥有合适的权限，可以不使用 sudo。

#

在 Windows 环境下

如果你在使用 Windows, Node.js 的安装包已经包含了一个 Node.js 的命令行程序。直接输入如下命令即可安装：

npm install -g harp

搞定！现在你可以启动 harp web server 了。

#

升级 Harp

升级到最新版本的 Harp 非常简单。只需在终端运行下面的命令：

sudo npm update -g harp

如果拥有合适的权限，可以不使用 sudo。

需要卸载 Harp？

4

初始化 Harp 应用

Harp 使用一个命令行界面来从头创建新项目。这是尝试 Harp 最快捷的方式了。

#

为什么呢？

通常，创建一个项目需要没完没了的样板代码。如果你不想创建一个复杂的反人类的空项目，那么这些命令就很有用了。

#

属性

path - (string) Optional, 你希望项目被创建在哪里？必须留空，否则不会创建任何文件。默认值是当前目录。

#

示例

下面这个例子在 myproject
目录创建一个默认应用

harp init myproject

#

默认项目结构

myproject/
|- _layout.jade
|- 404.jade
|- index.jade
+- main.less

注意：默认项目使用 Jade 来生成 HTML。不过你一样可以使用 EJS。

#

使用样板

使用 --boilerplate 或 -b 标志可以用 GitHub 上的样板初始化一个新 Harp 应用。下面这个命令会在 myproject
目录创建一个使用 github.com/kennethormandy/hb-remedy 样板的新项目

harp init myproject --boilerplate kennethormandy/hb-remedy

你甚至可以不用指定一个 GitHub 用户，默认使用 default Harp boilerplates

harp init myproject --boilerplate docs

#

将某一项目当成样板

即便一个不是用作 Harp 样板的 GitHub 仓库也可以用来初始化一个项目。因为 Harp 是伺候 HTML， CSS 和 JavaScript 的，所以任何基于 web 技术的项目应该都可以。例如，你可以轻易的在本地运行一个 Apache Cordova/PhoneGap 应用。

harp init -b phonegap/phonegap-start
harp server www
# Your project is now being served at http://localhost:9000

5

Harp 服务器

Harp 的主要设计目的是当作 server 或者 multihost 来运行的。下面这个命令运行后可以运行一个本地单应用。

#

用法

harp server [options] [path]

#

选项

port - (Number) 可选参数，服务器监听的端口号。默认端口号是 9000
。
help - 显示帮助信息。

#

属性

－ path - (String) 可选，你希望服务器监听的路径。

#

示例

harp server ~/apps/example.com --port 3000

#

访问运行中的 Harp 应用

我们提供了一个特殊的 URL 用来访问你的应用。在之前一个命令里，我们指定了 3000 端口，所以 Harp 应用将运行在

http://harpdev.io:3000

但是，你随时可以回到默认的 URI
http://127.0.0.1:3000
http://localhost:3000

如果没有指定端口，应用将会运行在默认端口 9000
。

http://harpdev.io:9000
http://127.0.0.1:9000
http://localhost:9000

#

使用 80 端口

有时候会觉得每次访问本地运行的站点都要输入端口号是很痛苦的。如果用浏览器的默认端口 80 那就没有这烦恼了。不过在 80 端口运行需要提权到 Admin 账户。在 OS X 上，这意味着你需要用到 sudo 命令

sudo harp server --port 80

如果 Harp 和已经在 80 端口上跑的某些业务冲突，你可以这样解决 with the port conflicts guide。

#

投入生产

Harp 是时刻准备着投入生产环境的。只要指定一个环境变量，额外的 LRU 缓存就会加入进来，加速你的站点。

NODE_ENV = production harp server --port 3000

6

Multihost

harp
的 multihost
功能就好像 harp 服务加上了类固醇。如果要在同一个目录中运行多个站点，这是最佳方案，而且只需要一个命令。

#

为什么呢？

当工作在多个项目的时候，保持组织有序很重要。在不同端口上来回切换不同的服务是菜鸟的方法。Multihost提供同样的便利，甚至更多。

#

用法

harp multihost [options] [path]

#

选项

port - (Number) 可选, 服务监听的端口。默认是 9000。
help - 显示额外的 harp multihost 的帮助信息。

#

属性

path - (String) 可选，服务的监听路径。

#

示例

运行下面的命令来伺服整个位于 ~/Sites
的目录

harp multihost ~/Sites --port 3000

multihost在如下地址提供所有应用的一个列表

http://127.0.0.1:3000/

图片 6.1 image

Harp 还把 http://127.0.0.1 映射到 http://harp.nu ，所以你可以在本地访问多应用服务。每一个应用也可以用 harp.nu的子域名访问

例如你在下面的目录运行 harp multihost

myapps/
|- mysite/
|- myproject.com/
+- myotherproject.harp.io/

然后，就可以在浏览器访问如下URL了:

[http://mysite.harp.nu:9000](http://mysite.harp.nu:9000)
[http://myproject.harp.nu:9000](http://myproject.harp.nu:9000/)
[http://myotherproject.harp.nu:9000](http://myotherproject.harp.nu:9000/)

如果你希望这个本地URL与你的部署 URL 有关系，可以是使用 Harp Platform，并且你所部署的应用也可以通过子域名 harp.io进行访问。

注意，如果你的机器离线了，这个域名将不能正常使用，因为你不能再访问到 http://harp.nu。

#

生产模式

至于 harp 服务器，通过指定一个环境变量，你可以进行生产模式而非开发模式的 multihost。在生产模式中，Harp 拥有额外的 LRU 缓存，让你的应用运行的更快。

NODE_ENV=production sudo harp multihost --port 80

#

或者在 80 端口上运行 multihost。

在 80 端口上运行 harp multihost 是可行的，让你同时伺服一个目录下的多个应用变得简单。
用这个多应用的目录作为例子

myapps/
|- mysite/
|- myproject.com/
+- myotherproject.harp.io/

通过在 myapps/
目录中运行下面的命令：

sudo harp multihost -p 80 &

符号 & 让你可以持续使用这个命令行的实例。如果你使用的是 Windows 操作系统，那么可以不加 sudo，但是需要是管理员权限。

现在，你的应用可以通过下面地址访问：

[http://mysite.harp.nu](http://mysite.harp.nu/)
[http://myproject.harp.nu](http://myproject.harp.nu/)
[http://myotherproject.harp.nu](http://myotherproject.harp.nu/)

#

终止“不明确的” multihost

如果你需要终止 80 端口上的 multihost （或者因为这个原因的任何其他事情），查阅如何解决端口冲突。

编译 harp

将你的 harp 站点导出为普通的静态文件 – HTML / CSS / JavaScript。

#

为什么呢？使用 Harp ，不需要总是编译或者监视你的项目——编译出来的文件不需要和源代码文件放在一起，随便放就好了。然而有些时候你还是希望将你的预处理文件编译成 HTML ，CSS 和 JavaScript：

#

Apache Cordova

创建一个手机应用变得相当简单。编译 Harp 直接导出一个 Apache Cordova/PhoneGap 友好的 www 文件夹。

#

没有锁定

假如不管出于什么样的原因，你不再喜欢 Harp，只需要将你的项目导出到任何一个伺服静态文件的 stack 或者云服务器上就好了。

#

用法

harp compile [options] [projectPath] [outputPath]

#

手机示例

通过运行 harp init mobileapp，尝试创建一个叫做 mobileapp 的项目，然后编译它：

harp init mobileapp harp compile mobileapp

运行编译命令将会生成如下的文件：

mobileapp/ +- www/ |- index.html +- main.css

#

备份示例

假如我们在 apps 目录下有一个叫做 example 的项目。我们可以通过下面的命令将它导出成静态文件，放到目录 Desktop/backup
中。

harp compile ~/apps/example ~/Desktop/backup

注意，备份文件夹会自动创建，并且被假定为空的。

更新 Harp

通过 npm 更新 Harp 相当简单，只需要在你的终端运行下面的命令：

#

OS X 和 Linux 上

npm update -g harp

你可能需要在这句命令前面加上 sudo，如果你没有合适的权限的话。

#

Windows 上

npm update -g harp

Express 嵌入式中间件

有时候，你已经拥有了一个服务，但是想将 Harp 作为 asset pipeline，来获取 Harp 预处理的优点。

本示例在一个项目中，结合了 Express 的长处和所有 Harp 的优点。没有外部的预处理，没有复杂的配置，并且没有客户端的解析器；只有编码的幸福。最好的是，设置极其简单。

#

添加 Harp 作为依赖

在你的 Express 应用的 package.json 文件中包含 Harp 作为依赖。

{ "name":
"myapp",
"version": "0.1.0",
"dependencies": {
"express": "3.x",
"harp": "*"
}
}

#

使用 harp.mount

接下来，使用 harp.mount，就像使用静态中间件一样。

var express = require("express");
var harp = require("harp");
var app = express();

app.use(express.static(__dirname + "/public"));
app.use(harp.mount(__dirname + "/public"));

app.listen(9000);

// routes as normal

#

添加 Harp 应用

全部搞定！现在将你的 Harp 应用的静态文件放到 public 目录下。下面是你的 public 目录有可能看起来像的示例：

/public
/_data.json
/_harp.json
/index.ejs

你可以用一个正常 Harp 应用同样的方式给模板传递数据。例如，使用 _data.json：

{
"index": {
"title": "Hello World"
}
}

至于全局变量，使用 _harp.json 文件，就像这样：

"globals": {
"foo": "bar"
}

然后你可以像这样在你的 index.ejs 模板中使用 title 和 foo变量：

应该输出：

<h1>Hello World</h1>
<p>bar</p>

规则

开发 Harp 应用模板需要遵循的五个简单规则。

Harp 没有复杂的功能集，只有一些遵循工作的简单规则。Harp 是相对简单的武士刀，而非功能复杂的瑞士军刀。通过理解规则，你将学会如何有效使用 Harp。

#

多约定，少配置

Harp 少到只需要一个 public/index.html
文件就可以工作，并不需要任何的配置。添加额外的路由只需添加额外的文件。通过学习这些剩余的规则你将会发现，所有的 Harp 的功能都是基于约定的。 Harp 致力于提供一个合理的开发框架，遵循成型的最佳实践。Harp 并非设计用于给很多人做很多事情，而是专注于自己擅长的事情。

#

设计原理

通过秉行多约定，少配置，Harp易于上手，让你更好地开发产品。

#

一个典型 Harp 应用的目录结构

myapp.harp.io/ <-- root of your application
|- harp.json <-- configuration, globals goes here.
+- public/ <-- your application assets belong in the public dir
|- _layout.jade <-- optional layout file
|- index.jade <-- must have an index.html or index.jade file
|- _shared/ <-- arbitrary directory for shared partials
| +- nav.jade <-- a partial for navigation
+- articles/ <-- pages in here will have "/articles/" in URL
|- _data.json <-- articles metadata goes here
+- hello-world.jade <-- should have at least one .html, .jade, .md or .ejs file.

#

根目录是 public

Harp 是一个网页服务器，所以它可以伺服任何目录，无论是包含一个大的 Harp 应用，还是只有单个 index.html
文件。

myapp.harp.io/
|- index.html <-- will be served

#

框架风格

Harp 应用可以选择性地以框架风格运行。当一个项目包含一个 harp.json
文件和一个 public 目录，public 目录会取代根目录做为伺服目录。框架风格中，公共文件放在 public 目录中。public 目录之外的文件不会被伺服。

myapp.harp.io/
|- harp.json <-- required harp.json file
|- README.md <-- won't be served
|- secrets.txt <-- won't be served
+- public/ <-- explicit public directory
+- index.html <-- will be served

#

忽略下划线开头的文件

任何以下划线开头的文件都会被服务器忽略。这是布局和局部视图文件的推荐命名约定。Harp 将会对文件和目录都遵循这个规则。

#

设计原理

通过一个简单的约定，指定和鉴别哪些文件不对终端用户服务变得相当简单。

#

例子

myapp.harp.io/
+- public/
|- index.html <-- will be served
|- _some-partial.jade <-- won't be served
+- _shared-partials/ <-- won't be served
+- nav.jade

#

静态简单 asset pipeline

Harp 伺服 jade, ejs, stylus, less 以及 coffee script。只需添加 .jade
, .ejs
, .styl
, .less
或者 .coffee
后缀，Harp asset pipeline 会负责剩余的事情。只需添加文件扩展名，引用类库，Harp 便会自动预编译。

myfile.md -> myfile.html
myfile.jade -> myfile.html
myfile.ejs -> myfile.html
myfile.less -> myfile.css
myfile.styl -> myfile.css
myfile.scss -> myfile.css
myfile.sass -> myfile.css
myfile.coffee -> myfile.js

如果你高兴的话，通过在扩展名前加上想要的扩展，可以特别指定伺服这种类型的文件。

myfile.jade -> myfile.html
myfile.xml.jade -> myfile.xml

然而，这是可选的，就像每一个扩展名都已经有了一个默认的扩展类型。下面的两个文件都会被当作 myfile,css
进行伺服，例如：

myfile.less -> myfile.css
myfile.css.less -> myfile.css

#

可变元数据

_data.json
文件比较特殊，里面的数据对模板文件可用。

myapp.harp.io/
+- public/
|- index.jade
+- articles/
|- _data.json <-- articles metadata goes here
|- hello-world.jade <-- hello world article
+- hello-brazil.jade <-- hello brazil article

_data.json
文件可能包含这样的内容：

{
"hello-world": {
"title": "Hello World.",
"date": "Feb 28, 2013"
},
"hello-brazil": {
"title": "Hello Brazil.",
"date": "March 4, 2013"
}
}

在模板文件中可以这样使用：

public.articles._data

此外，由于 hello-world 匹配文件名 hello-world.jade
，这些变量可以在 hello-world.jade
模板文件中使用。这个对象也可以作为 public.articles._data.hello-world
在所有的模板文件中使用。

在模板文件中，可以通过下面方式，在Jade文件中迭代 articles 变量：

for article, slug in public.articles._data
a(href="/articles/#{ slug }")
h2= article.title

11

公有和私有文件

一个正常运作的 Harp 应用需要公有的目录。它决定了哪些会被公共伺服，以及应用会暴露哪些 URL。公共文件放在 public 目录中，public 目录之外的文件不会被解析。

myapp/
|- harp.json
|- README.md <--- won’t be served
|- secrets.txt <--- won’t be served
+- public/ <--- public directory
+- index.html <--- will be served

#

忽略下划线开头的文件

任何以下划线开头的文件都会被服务器忽略。这是 layout
和 partial
文件的推荐命名约定。Harp 将会对文件和目录都遵循这个规则。

#

根目录风格应用

还可以有一种根目录风格的应用，public 目录事实上就是根目录。这种情况下，你仍然可以通过在文件名前加下划线，来避免它们对外伺服。

myapp/ <--- public directory
|- _harp.json
|- _secrets.txt <--- won't be served
+- index.html <--- will be served

#

设计原理

通过一个简单的约定，指定和鉴别哪些文件不对终端用户服务变得相当简单。

#

示例

myapp/
|- harp.json <--- won’t be served
+- public/ <--- public directory
|- index.html <--- will be served
|- _some-partial.jade <--- won’t be served
+- _shared-partials/ <--- won’t be served
+- nav.jade

myapp/ <--- public directory
|- _harp.json
|- index.html <--- will be served
|- _some-partial.jade <--- won’t be served
+- _shared-partials/ <--- won’t be served
+- nav.jade

12

布局

一个布局文件是一个通用模板，除了一个主要内容区域，包含所有的内容。你可以把一个布局当作局部视图相反的存在。

#

为什么呢？

通常网站和应用会有公共的头部和尾部，需要变化的只有主体部分。这是适合使用布局文件的绝佳使用案例。

#

用法

一个布局需要一个 EJS 或者 Jade 格式的布局文件，以及 a yield property 告诉 Harp 在哪里插入内容。

#

使用 EJS 模板的示例

举一个相当简单的例子，app/project 是这样的结构：

myapp.harp.io/
|- _layout.ejs
+- index.ejs

___layout.ejs __

<html>
<head>
<title>My Site</title>
<script src="/javascripts/jquery.js">
</script><script src="/javascripts/app.js"></script>
</head>
<body>
<%- yield %>
<div id="footer">
<p>Copyright © foobar</p>
</div>
</body>
</html>

index.ejs

<h1>My Site</h1>
<p>Welcome to my very first site.</p>

最终的结果：

<html>
<head>
<title>My Site</title>
<script src="/javascripts/jquery.js">
</script><script src="/javascripts/app.js"></script>
</head>
<body>
<h1>My Site</h1>
<p>Welcome to my very first site.</p>
<div id="footer">
<p>Copyright (c) foobar</p>
</div>
</body>
</html>

#

使用 Jade 模板的示例

Harp 也可以使用 .jade
后缀的文件作为布局文件。混合匹配模板也是可行的，例如在下面的例子中，我们有一个 _layout.jade
文件和一个 index.ejs
文件。

举一个相当简单的例子，app/project 目录结构如下：

myapp.harp.io/
|- _layout.jade
+- index.jade

_layout.jade

doctype
head
title My Site
script(src="/javascripts/jquery.js")
script(src="/javascripts/app.js")
body
!= yield
#footer
p Copyright (c) foobar

index.jade

h1 My Site
p Welcome to my very first site.

最终的结果：

#

多重布局

在你的应用中，可以充分发挥多重布局的优势。在下面的例子中，你可能希望 articles 目录和站点主页面有不一样的布局。

这里，在应用的根目录里 index.ejs
和 about.md
文件将会使用 _layout.ejs
布局。articles 目录中的文件——这个例子中，article-one.md
以及 article-two.md
—— 将会使用同目录中的 _layout.ejs
布局。

#

明确布局

除了 _layout
之外的布局可以在 _data.json
文件中指定。这在你需要更好地布局控制时，是非常有用的，或者你想将你的布局文件命名成 _layout 之外的名称。

这里，通过在 _data.json 文件中指定具体的布局文件，article-one.md 就可以使用 _an-example-layout.ejs 布局文件了：

{
"article-one": {
"layout": "_an-example-layout",
"title": "Example Title"
},
"article-two": {
"layout": "_another-one",
"title": "Another Example Title"
}
}

现在，每一篇文章都会使用指定的布局文件。

#

选择布局文件

通过使用 layout : false 可以让文件不使用布局。举下面的应用作为例子：

myapp.harp.io/
|- _data.json
|- _layout.ejs
|- index.ejs
+- about.md

在 _data.json
文件中添加下面的内容将会让 about.md
渲染普通的 HTML，而不会经过一个布局文件。

{
"about": {
"layout": false
}
}

因为只是指定了 About 页面，index.ejs
将会继续使用 _layout.ejs
文件作为布局文件。

#

嵌套布局

如果你想利用 Harp 对 Jade 内建支持的优势，可以使用 Jade’s Block and Extends features 来创建嵌套布局。

Harp 没有一个内建的方式来创建嵌套布局，就像 [partial()
] 已经提供了这种方式。例如，你的 _layout.ejs
得长得像这样：

<% if(current.path[0] == "blog" && current.source !== 'index') { %>

<%- partial(current.path[0] + "/_nest") %>
<% } else { %>

<%- yield %>
<% } %>

这允许你将一个 _nest.ejs
局部视图放到 blog/
目录中，让你可以创建嵌套布局。通过在 _nest.ejs
局部视图中包含 [yield]，你视图渲染的内容页面将会在 _nest.ejs
局部视图中可用。例如，blog/_nest.ejs
可能是这样的：

这样， blog/index
页面将会正常渲染，而其他的页面例如 blog/hello-world
将会如你在局部视图文件里指定的被 <article>
标签包裹。在 the hb-simurai Harp 样板上有一个关于这个的完整样例，可以通过运行下面的命令来尝试：

harp init -b kennethormandy/hb-simurai my-nested-example

注意，_nest.js
文件可以命名成任何你想要的，它只是一个中规中矩的局部视图。

13

Yield

yield
是一个包含特别路径内容的变量。例如，当访问 /blog
的时候，blog/index.jade
的整个内容可以通过 yield 变量访问

#

为什么？

当使用布局和局部视图的时候，你会想访问布局文件和局部视图文件正在包裹的内容。这个内容被包含在 yield 变量中，并且无论是在局部视图文件还是布局文件中，都可以被替换。

#

用法

在任何的 _layout.jade
或者 _layout.ejs
文件中都可以访问 yield
变量。在 _data.json
文件中指定的任何一个明确布局文件也都可以访问，这在布局文档也有覆盖。还可以在任何一个局部视图中使用 yield 变量。

#

Jade 示例

使用下面的目录结构：

myproject/
|- _layout.jade
|- index.jade
|- about.md

访问 /about
时，会显示 about.md
文件的内容。同样的，访问 /index
会显示 index.jade
的内容。这些文件的内容都会先被 _layout.jade
包裹。因此，在 _layout.jade
文件中，你需要指明输出，或者 "yield" 是放在哪里的：

doctype
html
head
title Example
body
!= yield

这样，无论你访问的哪个页面的内容都会被包含在 <body>
元素中。注意，在 Jade 中，!=
（而不是单个 =
）表明 HTML 标签不会被过滤。如果你想改变这个模板文件中的输出内容的位置，只需要移动一下 yield 变量的位置就好了：

doctype
html
head
title Example
body
article
h1 Hello, world
section
!= yield

#

EJS 示例

使用下面的目录结构：

myproject/
|- _layout.ejs
|- index.ejs
|- about.md

访问 /about
时，about.md
文件的内容会被显示出来。同样的，访问 /index
时，会显示 index.ejs
中的内容。这些文件都会先被包含在 _layout.ejs
中。因此，在 _layout.ejs 中，你需要指明输出内容或者 "yield" 的位置：

<!DOCTYPE html>
<html>
<head>
<title>Example</title>
</head>
<body>
<%- yield %>
</body>
</html>

这样，你访问的无论什么页面都会被包含在 <body>
元素中。注意在 EJS 中，开合标签 <%-
（而不是 <%=
）表明 HTML 标签不会被过滤。

如果你想移动这个模板文件中的输出的位置，只需要移动一下 yield 变量就好了：

<!DOCTYPE html>
<html>
<head>
<title>Example</title>
</head>
<body>
<article>
<h1>Hello, world</h1>
<section>
<%- yield %>
</section>
</article>
</body>
</html>

还可参见

14

局部视图

局部视图是 Harp 中的最重要地部分，并且在所有的模板语言中都以同样的方式工作。一个局部视图可以被放在 EJS 或 Jade 文件的任何地方，并且文件的内容会被混合起来。

#

为什么？

为了保持你的应用或者站点 “不要自我重复（DRY）”，你需要一个复用内容的方式。局部视图提供了一个简单的接口，在复用项目代码块方面有很大的灵活性，效率很高。

#

属性

局部视图路径 - (String) 你想包含的文件的相对路径。
data [对象] - (String) 你希望传入局部视图的数据，可选。

#

使用局部视图

如果说你正在创建一个简单的网站，并且希望包含一个会出现在每个页面上的头部。项目有一个 index.ejs
文件和一个 about.ejs
文件，想在两个文件中都包含存储在 _header.ejs
文件中的内容。

由于 _header.ejs
文件以下划线开头，所以不会被直接对外服务。然而，你可以使用局部视图函数将它包含到另一个文件中。

_header.ejs
文件的内容可以随你意地简单或者复杂，例如：

<h1>This is my site</h1>
<p>This content is in a Partial.</p>

#

在 EJS 文件中使用局部视图

index.ejs
文件中，调用 partial("_header")
将 _header.ejs
文件中的内容包含进来：

<%- partial("_header") %>

这样，Harp 会在 index.ejs
文件中渲染 _header.ejs
文件的内容。你可以对 about.ejs
文件重复这一过程，但是如果你想在两者之间做一些改变的话，该如何呢？

在 _header.ejs
文件中，<h1>
标签中的标题时硬编码的，但是如果你想根据它是哪个文件的部分来改变的话，该怎么做呢？使用局部视图函数，这也是可以做到的。当一个文件通过局部视图被引用，数据也可以传进来，代替局部视图中的指定变量。

更新 _header.ejs
文件使得 <h1>
标签包含变量标题：

<h1><%- title %></h1>
<p>This content is in a Partial.</p>

这样，调用这个局部视图时，把 title 变量传进来：

<%- partial("_header", { title: "About me" }) %>

这里 title 是一个任意的变量名，取决于上下文，它可以被叫做任何你想要的。如果你更新文件，让 <p>
标签包含一个叫做 description 的变量，那么局部视图函数应该是这样的：

<%- partial("_header", { title: "About me", description: "This is my about page" }) %>

#

在 Jade 文件中使用局部视图

在 Jade 中使用局部视图与在 EJS 中使用非常相似。Jade 中的函数以 !=
开头，而不是像 EJS 包裹在 <%- %>
中。在两种语言中，这都表明内容应该被渲染，这样无论局部视图中的是什么代码，都会被渲染，而不会被过滤。

h1
!= title
p This content i

Jade 中可以引入 EJS 局部视图，反之亦然。例如，创建一个 contact.jade
文件，然后在 Jade 中包含同样的头部局部视图：

!= partial("_header")

数据可以用同样的方式传进来。要改变局部视图中的标题，只需要像在 EJS 文件中一样，传进来一个：

!= partial("_header", { title: "Contact me" })

也可以传多个数据进来：

!= partial("_header", { title: "Contact me", description: "This is my Jade contact page with an EJS header" }) %>

如果你想为你的变量设置默认值——当前的例子中，title
和 description
变量的默认值，以防你不给局部视图传任何数据——你可以通过设置全局变量来完成。

#

Markdown 和局部视图

在 Markdown 文件中不太可能直接使用局部视图函数，因为 Markdown 不是一个模板语言。然而，仍然可以使用局部视图函数将 Markdown 文件包含到 EJS 或者 Jade 文件中。在下面的例子中，_shared
目录中有一个叫做 an-example.md
的 Markdown 文件。如果将 an-example.md
的内容引入到一个 Jade 文件的 article 标签中，你可以使用下面的代码：

article!= partial("_shared/an-example")

还可以在 Jade 中直接写 Markdown，像这样：

doctype
head
title An example
body
.main
:markdown
# now I can write Markdown here

This is my Markdown post.
1. Chocolate
2. Strawberry
3. Vanilla

使用一个或者多个这些方法，你应该可以得到想要的输出结果。

15

全局变量

全局变量是存储在 harp.json
文件中的 JSON 数据，对所有的页面、模板、局部视图以及布局文件可用。

#

为什么呢？

Harp 不仅仅只是静态文件，页面也可以通过动态内容创建。像全局属性中添加内容是天生可取的。

harp.json

{
"globals": {
"title": "Acme Site",
"name" : "John Doe",
"uri": "http://example.com"
}
}

#

Jade 示例

index.jade

html
head
title #{ title }
body
h1 Hello #{ name }!

#

EJS 示例

index.ejs

<html>
<head>
<title><%= title %></title>
</head>
<body>
<h1>Hello <%= name %>!</h1>
</body>
</html>

16

元数据

元数据是具有作用域的数据，从 _data.json
文件传到指定的页面中。

#

为什么？

有时你可能希望将变量分离开来，或者说将所有的全局数据放在一个文件中并非有利。文件元数据来做这件事情是完美的。

_data.json
文件比较特别，让数据在模板中可用。

#

示例

myproject/
├ _harp.json <-- Global metadata goes here
├ index.jade
└ articles/
├ _data.json <-- Article metadata goes here
├ hello-world.jade <-- hello world article
└ hello-brazil.jade <-- hello brazil article

你的应用可以有多个 _data.json
文件，每一个放在他们自己的文件夹中。你也可以在根目录中包含一个 _data.json
文件来为你根目录中的页面设置元数据。

你的 _data.json
文件可能包含下面的内容：

{
"hello-world": { <-- available everywhere as public.articles._data
"title": "Hello World.",
"date": "2013-02-28"
},
"hello-brazil": {
"title": "Hello Brazil.",
"date": "2013-03-04"
}
}

因为 hello-world 匹配文件名，在服务启动时，这些变量会在 hello-world.jade
模板文件中可用。这个对象也可以作为 public.articles._data.hello-world
在所有的模板文件中使用。

_harp.json
或者 harp.json
文件中的任何元数据都会被 _data.json
文件中的本地元数据所覆盖。这个特性允许你，例如，为整站指定一个标题，然后在具体的页面上覆盖它。（这里有一个样例）。

没有必要在 _data.json
中包含文件扩展名。例如，"hello-world.jade":{...}，将会抛出一个错误。

在 index 模板中，我们可能会遍历所有的文章来创建一个文章列表。

for article, slug in public.articles._data
a(href="/articles/#{ slug }")
h2= article.title

还可参见

17

内容

使用 Harp，你可以获取到你的编译文件的信息，除了源代码文件的元数据。

#

为什么？

你有可能想要在你的应用中遍历编译好的数据以及媒体数据，他们有可能含也有可能不含元数据。_contents 对象提供了一个做这件事情的方法。

#

示例

也许你有一个全部是图片的目录，并且希望展示它们全部，你不需要为每一张图片维持一个特别的元数据。

myproject/
├ index.jade
└ images/
├ hello-world.jpg <-- hello world image
├ hello-saturn.jpg <-- hello saturn image
└ hello-jupiter.jpg <-- hello jupiter image

#

使用 EJS

现在，在 index.ejs
文件中，你可以遍历 _contents
变量，引用每一个文件。

<% for(var i in public.images._contents){ %>
<% var image = public.images._contents[i] %>
<% if ( image.match(/\b.(jpg|bmp|jpeg|gif|png|tif)\b/gi) ) { %>
<div>
<img src="images/<%= image %>" />
</div>
<% } %>
<% } %>

结果是如下的 HTML：

#

使用 Jade

现在，在 index.jade
文件中，你可以遍历 _contents 变量，引用每个文件。

for image in public.images._contents
img(src="images/#{ image }")

结果是下面的 HTML：

18

当前对象

当前对象是在你的应用导航中应用激活状态的最好方式。它对每个模板可用，并且包含当前被渲染页面的状态。

#

为什么？

当复用像导航这样的模板时，当前对象对于给导航应用一个激活状态是非常有用的，还有可能以非传统的方式渲染布局或者局部视图。这让我们的应用代码保持“尽量不要重复自己（DRY）”，而又不会让应用的可用性打折扣。

#

属性

path - (Array) 当前被渲染的页面的文件路径。
source - (String) 路径数组中最后一个元素的缩写。

note - 当前对象中被忽略的文件扩展名。

Harp 提供了一个当前页面路径的数组，通过一个叫做 current source 的列表中的最后一个元素。这个信息通过当前对象是可用的，在你访问的每个页面上都是动态更新的。

例如，访问 /articles/hello-world
时，下面的信息是可用的：

{
path: ["articles", "hello-world"],
source: "hello-world"
}

然而访问 /articles/
时，当前对象是下面这样的：

{
path: ["articles", "index"],
source: "index"
}

现在，你可以在模板文件中使用这个了。

#

用法示例

这个应用有一个 index.jade
和 about.jade
页面。这些页面都有一个简单的导航，包含在 _nav.jade 局部视图中。

通过在 _nav.jade 模板中使用当前对象，你可以告诉 nav 模板正在被渲染的上下文（即，当前访问的是哪一个页面）。

给定下面一个项目：

myproject/
|- index.jade
|- about.jade
+- _nav.jade

#

Jade 示例

_nav.jade
文件，使用 current.source
：

ul
li(class="#{ current.source == 'index' ? 'active' : '' }")
a(href="/") Home
li(class="#{ current.source == 'about' ? 'active' : '' }")
a(href="/about") About

#

EJS 示例

同样的模板，_nav.ejs
而不是 nav.jade
：

<ul>
<li class="<%- current.source == 'index' ? 'active' : '' %>">
<a href="/">Home</a>
</li>
<li class="<%- current.source == 'about' ? 'active' : '' %>">
<a href="/about">About</a>
</li>
</ul>

有了 current.source
，你现在可以在导航上拥有依赖上下文的 classes。这些然后可以通过 CSS 样式化，或者你的预处理器选择：Sass， LESS，或者 Stylus。

19

环境

Harp 网页服务器既可以运行在本地，也可以运行于生产模式。环境变量返回 "production"
或者 "development"
字符串，依赖于具体的上下文。

#

为什么

Harp 网页服务器可以运行在本地用来开发，或者生产模式用来做线上网页服务器。通过环境变量，你的 Harp 应用可以随机应变，无论是否运行在本地。这对于在一个静态博客中创建一个草稿贴是绝佳的，还有一个例子是只在一个客户端应用地开发模式中下载开发资源。

#

用法

环境变量提供了多种可能性：你的博客可以本地以一种方式运行，或者发布到 Harp平台上以生产模式运行。另外，harp compile, which flattens your blog into static HTML, CSS, and JavaScript 被当作是另外一种生产环境。这意味着任何为产品模式准备的，当你只是提供静态页面服务时，依然会有。

#

EJS 示例

这是一个非常简单的例子，展示了如何使用一个条件语句来检验当前的 Harp 是在哪个环境，EJS 示例。

<h1>Harp is in <%- environment %> mode.</h1>
<% if(environment == "production") { %>
<p>See? Harp is in production mode.</p>
<% } else { %>
<p>Okay, Harp is in development mode right now.</p>
<% } %>

#

Jade 示例

这是一个非常简单的例子，展示了如何使用一个条件语句来检验当前的 Harp 是在哪个环境，Jade 示例。

h1 Harp is in #{ environment }
if environment == "production"
p See? Harp is in production mode.
else
p Okay, Harp is in development mode right now.

还可以参见 - harp 服务器, 将 Harp 应用从开发模式变到产品模式 - 使用 Harp 创建静态博客草稿贴，介绍了如何使用环境变量.

20

基本认证

给你的站点添加密码来限制访问者

#

为什么？

你可能需要一个有效的方式，来给一个完全静态站点或者客户端应用添加密码保护，无论是为了内部使用，还是你在开发一个带客户端项目的暂时考虑。

#

示例

图片 20.1 image

如果你的应用根目录中还没有 _harp.json
文件的话，先创建一个，或者 harp.json
文件，如果你有一个指明的公共目录。添加下面的代码，会使用用户名 Ali Baba 和密码 Open, Sesame! 来保护你的应用：

{
"basicAuth": "Ali Baba:Open, Sesame!"
}

#

多个账号

你也可以指明多个基本账号来进行认证：

{
"basicAuth": ["user1:pass1", "user2:pass2", "user3:pass3"]
}

#

完整的 harp.json
文件

basicAuth
数组或者字符串，harp.json 文件中的全部属性。一个更长一点的 harp.json
文件可能是这样的：

{
"basicAuth": "Ali Baba:Open, Sesame!",
"globals": {
"title": "Ali Baba’s blog",
"author": "Ali Baba",
"description": "A secret blog"
}
}

#

不加认证

如果你想把 basicAuth
属性加在 harp.json
文件中，但是当前又不需要 basicAuth
，一个空的数组不会添加任何限制：

{
"basicAuth": []
}

#

基本认证以及 harp 编译

因为 Harp 是一个可以生成静态站点的网页服务器，但又不是一个静态站点生成器，所以它具有编译成普通 HTML、CSS、以及JavaScript的额外功能，例如 basicAuth。

如果你使用 Harp 进行编译，而又使用其他的网页服务器运行项目，例如 Apache，或者部署到 GitHub Pages 上，这些特征将不会被那些平台支持。

然而，你可以将你的应用部署到 Harp 平台，它支持这个功能。手动部署 Harp 到生产模式的话，也许 Heroku 和 Github Pages 是不错的选择。

21

“404 不存在”状态码

使用 Harp 显示一个自定义的 404 页面。

#

为什么

无论你在做什么项目，都有必要做一个自定义的 404 页面，给访问者提供有用的信息，并且设计地像站点的其余部分风格。

#

用法

非常简单，只需要在你应用的根目录下添加一个 404.jade
、404.ejs
、404.md
或者 404.html
文件就好了。

#

示例

如果你初始化一个新的 Harp 应用，会自动生产一个 404.jade 文件。给现有项目添加一个自定义的 404 页面，只需要在根目录中添加一个 404 文件。

mmyproject/
|- 404.html
|- index.html
+- main.less

如果你的项目想要使用相同的布局，即使是 404 页面，那么你可以将应用的目录结构设置成这样：

myproject/
|- _layout.ejs
|- index.ejs
|- 404.md
+- main.scss

这样，_layout 文件将会同时包裹 index.ejs
和 404.md
。

22

“200 OK” 状态码

使用 Harp 的 200 文件来路由一个客户端应用

#

为什么

如果你在用一个像 Backbone，Angular，或者 Ember 的框架来开发一个客户端应用，你会想用 HTML5 的 PushState 来做你的客户端路由。200 文件给你提供一个 200 OK
状态码。

#

用法

用一个 200.jade
、200.ejs
或者 200.md
文件替代你的 404 文件。这个文件必须是在你应用的根目录。

#

示例

给定下面的目录结构：

myproject/
|- 200.ejs
|- app.js
|- framework.js
+- main.scss

200.ejs
文件会在所有的静态路由之后运行，并且在 404 之前，让你可以做客户端的任何路由。

这与静态页面又很好的协作。例如，如果你有一个客户端应用，但是希望你的博客是静态的，并且不使用路由，你的应用有可能是这样的：

现在，如果你在浏览器中访问 /blog
，200
文件将会被先运行。如果你的客户端路由不对这个请求做任何事情，你的静态博客将会被运行。有大量的客户端路由和框架可以使用：

23

Markdown

Markdown 易写易读，语法在网页写作上很有用，并且很流行。

#

为什么

Harp 默认包含普遍有用的预处理器。这意味着你没必要浪费时间在将你的 Markdown 转化成 HTML——每件事都会正常工作。另外，Jade 和 EJS 文件可以把 Markdown 当作局部视图导入，让你可以有效地复用代码。

#

用法

Harp 的 asset pipeline 很容易使用。所有的处理过程都会自动发生，并不需要进行设置。只需要把你的文件加一个 .md
后缀，Harp 网页服务器会把它当作一个 .html
文件来解析。有些其他的 Markdown 解析器可能还支持 .markdown
、.mdown
、.txt
或者其他的扩展名。Harp 只会处理 .md
文件。

#

示例

这个项目在根目录中包含 index.md
和 about.md
文件。

myproject/
|- index.md
+- about.md

index.md
以及 about.md
都会被当作 .html
文件进行解析。因此，对一下路径的访问都会工作：

/
/index
/index.html
/about
/about.html

运行 Harp 的 compile step 也会把文件当作 index.html
和 about.html
导入进来。

#

GitHub 最爱的 Markdown

Harp 还支持 GitHub Flavoured Markdown 补充语法。（这不包括 Github 专用功能，例如任务列表和 @mentions
等等。）这可以让你写一个围起来的代码块：

```
function test() {
console.log("Hello, world");
}
```

你可能还想要指明代码语言：

```javascript
function test() {
console.log("Hello, world");
}
```

function test() {
console.log("Hello, world");
}

Harp 将会把代码块当作 HTML 运行：

<pre><code class="language-javascript">function test() {
console.log("Hello, world");
}</code></pre>

语言类名称遵循 W3C 以及 WHATWG 标准来指定代码类型。这还可以让你用一个高亮类库的客户端语法来样式化，例如 Prism 。

#

管理文件扩展名

你可能会想要使用 Markdown 创建另外一个基于 markup 的文件，而不是 .html
。没问题：只需要把你想要的扩展名加到 .md
前面就行了。例如，feed.xml.md
会被 Harp 当作 feed.xml
进行解析。

使用 EJS 和 Jade 也是可以的，并且非常有用。

#

还可以参见

24

EJS

EJS 是 "Embedded JavaScript" 的缩写，描述的很好：通过嵌入具有 JavaScript 特色的功能来进行 HTML 模板渲染。这让你在你的元数据上进行遍历，包含局部视图，还有其他的。

#

为什么呢？

EJS 比较通俗，因为主要是 HTML，但又具有额外的功能让你有效地复用你的项目代码块。如果你有一个现有的 HTML 项目，你所需做的全部工作就是用 .ejs
扩展名重命名文件，然后你就可以使用 EJS 的特色功能了。

Jade，另外一个 HTML 预处理器，也是与 Harp 工作的相当好，你可以尝试一下。

#

用法

Harp 的 Asset Pipeline 用起来相当简单。所有的处理过程都是静默完成的，不需要进行任何设置。只需要将你的文件用 .ejs
扩展名来命名，而不是 .html
，Harp 会将它看做是 .html
文件。

#

示例

这个项目在根目录中包含一个 index.ejs
和一个 about.ejs
文件。

myproject/
|- index.ejs
+- about.ejs

index.ejs
和 about.ejs
都会被当作 .html
文件。因此，如下路径的请求都会成功：

/
/index
/index.html
/about
/about.html

Harp 的编译步骤也会将文件导出为 index.html
和 about.html

#

管理文件扩展名

你有可能会想使用 EJS 创建另外一个基于 markup 文件，而不是 .html。没问题：只需要将你想要的扩展名放在 .ejs 前面。例如，feed.xml.ejs 会被 Harp 当作 feed.xml 进行解析。

#

还可以参见 - EJS文档 - Jade模板 - Markdown

25

Jade

Jade 是一种标记语言，通过创建基于 XML 的文件（例如 .html
或者 .xml
文件）。Harp 对 Jade 的支持非常好。

#

为什么呢？

Jade 相当简洁并且强大。如果你正创建基于 XML 的输出内容（例如 HTML），强烈建议你尝试一下 Jade。如果不是基于 XML 的内容，比如 .json
和 .txt
文件，那就没有必要了。在后一种情形下，你可能会发现 EJS 是一个更合理的选择。

#

用法

Harp 的 Asset Pipeline 用起来相当简单。所有的预编译都是静默完成，不需要任何设置。只要将你的文件命名成 .jade
后缀，而不是 .html
，Harp 网页服务器会把它当作一个 .html 文件。

#

示例

在我们的项目中，public 目录中有一个 index.jade
文件和一个 about.jade
文件。

myproject/
|- harp.json
+- public
|- index.jade
+- about.jade

index.jade
和 about.jade
都会被当作 .html
文件，所以下面路径的请求都会成功：

/
/index
/index.html
/about
/about.html

Harp 的编译过程也会将文件导出为 index.html
和 about.html
。

#

管理文件扩展名

你可能会想要使用 Jade 创建 html 之外的文件。没问题，只需要将你想要的扩展名放在 .jade
前面。
例如，feed.xml.jade
会被看作 feed.xml
。

#

还可以参见

26

LESS

LESS 是一个 CSS 超集，使得 CSS 的预处理过程相当简单。它被用来创建有名的类库 Bootstrap；Harp 对 LESS 的源代码文件支持的非常好。

#

为什么呢？

Harp 默认包含最好的预处理器。这意味着你不需要浪费时间来配置 LESS，折腾安装依赖，最小化 CSS，你甚至不需要选择文件的输入和输出位置。一切都会工作地很好。

#

用法

Harp 的 asset pipeline 用起来相当简单。所有的处理过程静默完成，不需要进行任何配置。只需要给你的文件加上 .less
后缀，而不是 .css
，Harp 网页服务器将会把它当作 .css
文件进行解析。

#

示例

本项目中，css 目录中有一个 main.less
文件和一个 _variables.less
文件，像这样：

myproject/
|- index.ejs
+- css/
|- main.less
+- _variables.less

这样，你只需要在 index.ejs
中简单地引用 main.css
以及其他任何 CSS 文件：

你的 main.less
可以像这样引用变量：

@import "variables”;

body {
font: 12px Helvetica, Arial, sans-serif;
}

#

还可以参见

27

Sass

Sass 是一个功能丰富，用途很广的 CSS 预处理器。它使用 CSS 的超集 SCSS 语法，或者原生语法。

#

为什么呢？

Harp 默认包含最好的预处理器。这意味着你不需要浪费时间来配置 Sass，折腾安装依赖，最小化 CSS 文件，你甚至不需要选择文件的输入和输出位置。一切都会工作的很好！

#

用法

Harp 的 Asset Pipeline 用起来相当简单。所有的处理过程静默完成，不需要进行任何配置。只要给你的文件加上 .scss
后缀，而不是 .css
，Harp 网页服务器会把它当做 .css
文件进行解析。

#

SCSS 示例

本项目中，css 目录中有一个 main.scss
和一个 _variables.scss
文件，像这样：

myproject/
|- index.html
+- css/
|- main.scss
+- _variables.scss

这样，你只需简单地在 index.ejs
文件中引用 main.css
以及任何其他 CSS 文件：

然后你的 main.scss
可以这样引用变量：

@import "variables";

body {
font: 12px Helvetica, Arial, sans-serif;
}

#

Sass 示例

本项目中，css 目录中有一个 main.sass
和一个 _variables.sass
文件，像这样：

myproject/
|- index.html
+- css/
|- main.sass
+- _variables.sass

这样，你只要在 index.ejs
文件中引用 main.css
文件以及其他 CSS 文件：

main.sass
可以这样引用变量：

@import variables

body
font: 12px Helvetica, Arial, sans-serif

#

注意事项

在 Harp 的 Sass 版本中，Sass 3.2 的主要功能都是可用的，但是不支持 Sass 3.3。

Harp 使用 libsass，Sass 的 C++ 实现，用来预处理。由于不是 Sass 的原生版本，可能不包含最新的 Sass 3.3 的特征。

如果你有疑问，或者不确定在 Libsass 中一个功能是否有所缺失，或者在 Harp 中存在一个 bug，欢迎访问 file a GitHub issue。

#

还可以参见

28

Stylus

Stylus 是一个高效、动态以及丰富的 CSS 预处理器。它同时支持缩进的和通俗的两种风格的 CSS 语法风格。

#

为什么呢？

Harp 自动具备了最好的预编译器。这意味着你不需要考虑下载哪个文件，最小化 CSS 或者未压缩的 stylus 文件。一切都工作的很好。

#

用法

Harp 的 Asset Pipeline 用起来相当简单。所有的预编译静默完成，不需要进行任何配置。只需要用 .styl
后缀命名你的文件，而不是 .css
，Harp 网页服务器会把它当作 .css
文件进行解析。

#

示例

本项目中，在我们的 public/css 目录中，有一个 style.styl
和一个 variables.styl
文件，像这样：

myapp.harp.io/
+- public/
|- index.ejs
+- css/
|- style.styl
+- _variables.styl

你只需按如下设置你的 index.ejs
文件：

你的 style.styl
可以像这样引用变量：

@import "_variables.styl"
body
font 12px Helvetica, Arial, sans-serif

#

管理导入

如果你熟悉 Sass，你会习惯用下划线打头来命名你的局部视图文件。这在 Stylus 中是允许的，但不是必须的。正因为如此，使用 @import 引入局部视图的时候，你必须具体指明引用的开头的下划线。例如，如果你有一个叫做 _example.styl
的局部视图，你必须使用 @import "_example"
来导入它。单单用 @import "example"
在 Stylus 是无效的。

#

使用 Nib

Nib 是 Stylus 的应用的类库。给你的 Harp 应用添加 Nib 的最快方式是克隆 Nib 的 Git 版本库：

git clone https://github.com/visionmedia/nib.git/path/to/myapp.harp.io/public/css/_nib

这样，在之前例子中的 style.styl
，可以引入 Nib。

@import "_variables.styl"
@import "_nib"

body
font: 12px Helvetica, Arial, sans-serif
background: linear-gradient(top, white, black)

#

还可以参见

29

CoffeeScript

CoffeeScript 是一个功能丰富，用途很广，并且很普遍的 JavaScript 预处理器。CoffeeScript 是一个对空格敏感的 JavaScript 变种。

#

为什么呢？

Harp 默认包含最好的预处理器。这意味着你不需要浪费时间配置 CoffeeScript，折腾安装依赖，最小化 JavaScript 文件，你甚至不需要选择文件的输入输出位置。一切运行的很好。

#

用法

Harp 的 Asset Pipeline 相当易用。所有的处理过程静默完成，不需要进行任何配置。只需要用 .coffee
命名你的文件，而不是 .js
，Harp 网页服务器会把它当作 .js
文件。

#

示例

本项目中，js 目录中有一个 app.coffee
文件，像这样：

myproject/ |- index.html +- js/ |- app.coffee

这样，你只需要在 index.ejs
中引用 app.js
，其他 js 文件一样：

并且你的 app.coffee
可以这样使用 CoffeeScript：

mass = 72 height = 1.78 BMI = mass/Math.pow height, 2 alert 'You are healthy!' if 18.5<BMI<25

#

还可以参见

CoffeeScript 文档

30

Harp 平台

一个定位于通过 Dropbox 进行 Harp 应用服务的平台。想知道更多关于 Harp 平台的信息可以查阅 harp.io。

31

部署到 Github Pages

Github Pages，也被称作 gh-pages，是 Github 为公共网页提供的免费主机服务。它通常被用来放个人博客以及网站项目。如果你对在命令行下使用 git 比较熟悉，那么把你的 Harp 应用部署到 Github Pages 应该不是什么难事。

#

示例用法

可以有两种不同的方法使用 GitHub Pages： - 个人以及公司页面 - 项目页面

在 GitHub Pages documentation，你可以阅读更多关于两种页面的区别。

#

部署一个 GitHub 个人或者公司页面

这五个步骤将会迅速带你将一个 Harp 应用部署到个人或者公司 GitHub 页面上。

#

1.创建一个新的版本库

创建一个叫做 your-github-user-name.github.io 的新的版本库，用你自己的个人或者公司名称替代 “your-github-user-name”。假如你的用户名是 octocat，那么创建一个叫做 octocat.github.io 的版本库。

图片 31.1 image

勾选 “带有一个 README 初始化版本库。” 这会让你 clone 你新的版本库。

#

2.克隆版本库

终端中，clone 你刚刚创建的版本库：

git clone https://github.com/your-github-user-name/your-github-user-name.github.io.git

#

3.初始化 Harp 应用

你的版本库准备好了，你只需要再创建一个 Harp 应用。在 _harp
中初始化一个新的 Harp 应用。

harp init _harp

如果你有一个现成的项目，你有可能也想将它移动到你的工作目录中，但是必须确保文件夹名称以一个下划线开始；当你部署到 GitHub Pages 时，你不会想要你的源代码被运行。

#

4.编译你的 Harp 应用

只要你喜欢，Harp 可以将你的应用编译成 HTML、CSS 以及 JavaScript。默认的，Harp 编译器创建一个 www 目录。因为 Github Pages 是从版本库的根目录运行，你会希望在根目录编译你的 Harp 应用。

harp compile _harp ./

#

5.部署到 GitHub Pages

你已经准备好部署你的应用了！添加全部的文件，提交它们，然后将它们 push 到 GitHub上：

git add -A
git commit -a -m "First Harp + Pages commit"
git push origin master

接下来的十分钟内，你的应用将会在 your-github-name.github.io
可以访问。

#

下一步是什么？

你的 Harp 应用已经被成功地部署到 GitHub Pages。现在，你应该会想自定义它。阅读五个简单规则，快速开始修改 Harp 应用的模板。

如果你想通过 GitHub pages 使用一个自定义的域名，遵循 GitHub Pages documentation 的指导。

#

部署一个项目页面

这五步会快速带你部署一个 Harp 应用到一个项目的 GitHub Page。

#

1.克隆项目

git clone https://github.com/your-github-name/repository-name.git

#

2.创建一个新的，干净的分支

下一步，你将需要在应用的现有版本库中创建一个新的 "orphan" 分支。这个分支将会包含你的 Harp 应用，编译完的HTML、CSS 以及JavaScript 将会通过 GitHub Pages 运行。

cd repository
git checkout --orphan gh-pages

现在，从分支中清空现有的文件，这样一个 Harp 应用可以取而代之。

# Always ensure you’re in the right place before deleting files with this command

git rm -rf .

#

3.初始化一个 Harp 应用

你的版本库准备好了，你还需要一个 Harp 应用。在 _harp
中初始化一个新的 Harp 应用。

harp init _harp

如果你已经有了一个项目，你也可以将它移动到你的工作目录中，但是确保在文件名的开头添加一个下划线；当你部署到 GitHub Pages 是，你不会想你的源代码文件被运行。

#

4.编译你的 Harp 应用

无论何时，Harp 都可以将你的应用编译成 HTML、CSS以及 JavaScript。默认地，Harp 编译创建一个 www 目录。因为 GitHub Pages 是从版本库的根目录运行，你会希望在根目录编译。

harp compile _harp ./

#

5.部署到 GitHub Pages

你已经准备好了部署你的应用！添加所有的文件，提交它们，然后 push 到 GitHub：

git add -A
git commit -a -m "First Harp + Pages commit"
git push origin gh-pages

你的应用将会在下面的十分钟内在 your-github-name.github.io/repository-name
可以访问。

#

下一步做什么？你的 Harp 应用已经被成功地部署到GitHub Pages 上。现在，你可能想自定义它。阅读五个简单规则，快速上手开发 Harp 应用的模板。

如果你想使用 GitHub Pages 的自定义页面，遵循 GitHub Pages documentation 上的指导。

32

部署到 Heroku

Heroku 是一个专注于开发者的平台，用来为应用提供主机服务。如果你对命令行中使用 git 非常熟悉，那么把你的 Harp 应用部署到 Heroku 将不存在问题。

#

创建一个 Heroku 账户

如果你还没有，创建一个 Heroku account，安装它们的 toolbelt，然后使用终端，通过用户名和密码进行登录。

heroku login

现在你已经准备好修改你的 Harp 应用来为 Heroku 做准备。如果你没有一个现成的应用，或者想尝试通过默认的应用进行部署，你可以使用 harp 初始化一个新应用。

#

Harp 编译包

部署你的应用到 Heroku 的最简单方式是通过 @zeke’s Harp buildpack

#

1.创建或者使用一个现成的应用

如果你需要一个新的应用，创建一个带有 index 文件的目录。你也可以通过终端来做：

mkdir my-harp-app
cd my-harp-app
echo "hello world" > index.html

#

2.将你的应用初始化为一个 Git 版本库

下一步，你将初始化你的 Harp 应用为一个 Git 版本库（如果不是一个已经存在的）。然后，添加、提交变动：

git init
git add .
git commit -am "hello world"

#

3.使用编译包

在 Heroku 上创建一个新的应用，设置为使用 Harp 编译包。

heroku create my-harp-app
heroku config:set BUILDPACK_URL=https://github.com/zeke/harp-buildpack.git

#

4.将你的应用部署到 Heroku

Push 到 Heroku 上，然后在线看你的应用：

git push heroku master
heroku open

#

5.设置生产模式

为了得到最好的性能，你将需要合理地设置 Harp 的产品模式。Heroku 编译包尚且还不能为你做到。

heroku config:set NODE_ENV="production"

#

手动部署到 Heroku

如果你希望手动部署一个 Harp 应用到 Heroku，使用下面的方式：

#

添加 package.json 和 server.js

有两个文件需要添加到你的 Harp 应用根目录中（不是 public
目录）。第一个是 package.json
：

{
"name": "My Harp App",
"version": "1.0.0",
"description": "A Harp App on Heroku",
"dependencies": {
"harp": "*"
},
"engines": {
"node": "0.10.x",
"npm": "1.2.x"
}
}

然后，使用 Node 包管理器来安装依赖：

npm install

然后，创建 server.js，包含一下内容：

require('harp').server(__dirname, { port: process.env.PORT || 5000 })

#

2.将你的应用初始化为一个 Git 版本库

使用终端，将你的应用初始化为一个 Git 版本库（如果尚且还不是一个 Git 版本库）。然后，添加、提交变动：

git init git add . git commit -m "First Harp + Heroku commit"

#

3.部署到 Heroku

你已经准备好了部署应用到 Heroku。将 Harp 应用设置为一个 Heroku 应用，然后使用 git 将应用 push 到 Heroku。

heroku create my-harp-app git push heroku master

这个例子中，应用会被叫做 my-harp-app
，然后瞬间可以通过 my-harp-app.herokuapp.com
进行访问。

#

下一步如何？

你的 Harp 应用已经被成功部署到 Heroku。现在，你可能希望自定义它。阅读五个简单规则，迅速开始开发 Harp 应用模板。如果你希望在 Heroku 上使用一个自定义域名，遵循 Heroku 开发中心上的指导。

33

Azure

微软 Azure 是一个开放、灵活的云平台，通过微软数据管理中心的全球网络，让你可以快速编译、部署以及管理应用。如果你对在命令行中使用 git 比较熟悉，你可能，将你的 Harp 应用部署到 Azure 可能不存在什么困难。

#

Azure 跨平台命令行

首先，下载 Node 版本的 Azure 跨平台命令行。我们将使用这个工具帮助你通过命令行创建一个 Azure 站点。

npm install -g azure

关于这个工具的更详尽的博客贴在这里

#

1.创建或者使用一个现有应用

如果你需要一个新的应用，创建一个带有 index 文件的目录。你也可以通过终端做到：

harp init my-harp-app
cd my-harp-app

#

2.将你的应用初始化为一个 Git 版本库

下一步，你将会把你的 Harp 应用初始化为一个 Git 版本库（如果尚且不是一个 Git 版本库）。然后，添加、提交变动：

git init
git add .
git commit -am "hello world"

#

3.添加 package.json 和 server.js

你需要添加两个文件到你的 Harp 应用根目录（不是 public
目录）。第一个是 package.json
：

{
"name": "My Harp app",
"version": "1.0.0",
"description": "A Harp App on Azure",
"dependencies": {
"harp": "*"
},
"engines": {
"node": "0.10.x",
"npm": "1.2.x"
}
}

然后，使用 Node 包管理器来安装依赖：

npm install

下一步，创建 server.js
，包含一下内容：

require('harp').server(__dirname, { port: process.env.PORT || 5000 })

#

4.部署你的 Harp 应用到 Azure

你已经准备好了将你的应用部署到 Azure。将 Harp 应用创建为 Azure 项目，"my-harp-app" 是你想要的二级域名：

azure site create --location "West US" my-harp-app --git

这将添加一个新的 azure 远程到你的 git 版本库。azure 远程是站点将会被部署的方式。部署到 azure 与将代码 push 到主干一样简单。

git push azure master

#

5.将环境设置为生产模式

为了得到最好的性能，你将需要合理设置 Harp 的生产模式。

azure config set NODE_ENV production

现在你的站点应该跑在 Azure 上了，通过 http://my-harp-app.azurewebsites.net 可以访问，my-harp-app 是你指定的二级域名。

#

下一步怎么做？

你的 Harp 应用已经被成功地部署到了 Azure 上。现在，你可能想要自定义它。阅读五个简单规则，开始快速开发 Harp 应用模板。

如果你想使用一个 Azure 的自定义域名，遵循微软 Azure 文档上的指导。

34

如何创建一个贴子列表

这篇文章教你如何创建你的博客贴子的一个列表，每一个条目包含标题、链接以及贴子内容。

#

目录结构

给定一个这样的目录结构：

/public
/posts
_data.json
my-first-post.md
my-second-post.md
/index.jade <-- or index.ejs

#

贴子数据

添加一个这样的 /public/posts/_data.json
：

{
"my-second-post": {
"title": "My second post"
},
"my-first-post": {
"title": "My first post"
}
}

#

使用 Jade 进行列表你可以在 Jade 中这样遍历你的贴子：

for post, slug in public.posts._data
h2: a(href="/posts/#{ slug }")= post.title
!= partial("posts/" + slug)

#

使用 EJS 进行列表

或者在 EJS 中：

<% for(var slug in public.posts._data){ %>
<h2><a href="/posts/<%= slug %>"><%= public.posts._data[slug].title %></a></h2>
<%- partial("posts/" + slug) %>
<% }; %>

#

工作原理

我们正在使用 for
迭代器来遍历 /public/posts/_data.json
中的数据。可以通过 public.posts._data
获取到贴子数据对象。

35

如何在每一页上获取到自定义标题和描述

本篇文章将教你如何设置你的应用，让你在每一页设定自定义标题和描述，而且当没有设定时有一个安全的默认值。

默认值将会在 _harp.json
文件中指定，然后我们将使用 _data.json
文件覆盖哪些值。

你可以在文档中找到更多关于模板数据的信息。

#

概览

目录结构：

_harp.json
_data.json
index.jade // or index.ejs
about.jade // or about.ejs

这个例子中，这是我们所希望的：如果一个访问者请求 index 页面，我们展示标题和描述的默认值，当他们请求 about 页面，我们显示自定义的值。

#

设置默认值

首先，我们将指定默认值，如果页面没有指定具体数值时，会用到。在你的 _harp.json
中：

{
"globals": {
"title": "My default title",
"description": "My default description"
}
}

#

设置 about 页面的自定义值

在 _data.json
文件中添加你想要为 about 页面添加的自定义值：

{
"about": {
"title": "Welcome to my about page",
"description": "I’m awesome and so are you"
}
}

#

在模板文件中使用

#

如果你正在使用 Jade

现在我们将在 _layout.jade
中使用我们刚刚添加到 _harp.json
中的标题和描述。

doctype
html(lang="en")
head
title= title
meta(name="description" content="#{ description })
body
!= yield

#

如果你正在使用 EJS

如果你正在使用 EJS，_layout.ejs
应该是这样的：

<!DOCTYPE html>
<html lang="en">
<head>
<title><%= title %></title>
<meta name="description" content="<%= description %>" />
</head>
<body> <%- yield %> </body>
</html>

#

结果

现在当你访问 index 页面时，Harp 将会渲染 _harp.json
中指定的默认值。

当你访问 about 页面时，Harp 将会用 _data.json 中指定的值覆盖默认的标题和描述变量。

如果你希望在 index 页面中显示自定义值，你只需要在 _data.json
文件中添加 index 键值，像这样：

{
"about": {
"title": "Welcome to my about page",
"description": "I’m awesome and so are you"
},
"index": {
"title": "This is my home page",
"description": "Best home page ever"
}
}

记住你并不需要同时覆盖两个变量。如果你只覆盖 title 变量，模板文件将会仍然为 description 变量使用默认值。

#

这是如何做到的？

_harp.js
中指定的全局变量值，是可以作为模板变量使用的，所以它们可以在任何时候以及任何页面使用。

当一个 Harp 应用试图渲染一个页面，它会尝试将 url 路径与 _data.json
中的数据进行匹配。在这种情况中，它将 URL 路径中的 about 部分与 _data.json
文件中的 about 键值匹配起来。

当 Harp 找到一个匹配时，它会使得当前渲染的模板可访问那些变量。并且在这种情况中，它会覆盖我们之前在 _harp.json
中设置的变量。

你可以在文档中找到更多关于模板数据的信息。

36

更多教程

通过 Harp 创建应用的普遍使用教程。

这个页面是一个正在进行的工作，如果你有任何想在这里见到的教程或者有想贡献的，请让我们知道

#

普通教程

#

博客教程

#

计划中的教程

#

热销教程 - 如何创建一个产品/服务加载页面 - 如何做A/B测试 - 如何添加谷歌统计

#

博客教程 - 如何创建未发布（草稿）博客贴子 - 如何通过日期排序博客贴子 - 如何为每个博客贴显示特征图片 - 如何显示博客贴的指定数量

#

模板教程

如何通过一个动态选定的条目创建一个菜单
如何创建一个继承者父布局的布局
如何打印出所有的数据以供调试

#

App 教程

如何添加用户注册和登陆
如何在不同的用户建共享数据
如何创建一个动态生成的缓存清单文件
如何接受用户的付款（Wufoo、Stripe 以及 Kinvey）

#

Harp + X 教程

如何：Harp + AngularJS
如何: Harp + Apache Cordova / PhoneGap
如何：Harp + Grunt
如何：Harp + Bootstrap
如何：Harp + Foundation
如何：Harp + Bourbon & Neat
如何将一个 Jekyll 应用转为 Harp 应用

jade css框架页面布局局部变量静态函数

「喜欢这篇文章，您的关注和赞赏是给作者最好的鼓励」

关注作者