assemble
1.0.0
正在寻找 grunt 插件？请访问 grunt-assemble。
（请注意，当前网站 assemble.io 用于 grunt-assemble。感谢您在我们使用最新汇编文档更新该网站时的耐心等待） 。
（单击以下部分将其展开）
（由动词使用 markdown-toc 生成的 TOC）
Assemble 是一个命令行工具和开发人员框架，用于快速原型设计、静态站点生成等。
Assemble 被 170 多个国家/地区的数千名开发人员和团队使用！以下是使用 assemble 构建的站点的一些示例：
您的网站、博客或项目是用 assemble 构建的吗？请告知我们！
Assemble 可以独立使用，但与以下库一起使用时它会更强大：
以下是 assemble 提供的部分功能：
使用 npm 添加组装项目的devDependencies ：
$ npm install -D assemble您现在应该能够直接运行 assemble（使用node assemblefile.js等）或使用npm脚本。例如，将以下内容添加到 package.json：
{
"scripts" : {
"build" : " assemble "
}
}然后运行
$ npm run build您还可以全局汇编 CLI，这会将assemble命令添加到您的系统路径，从而允许它从任何目录运行。
$ npm install --global assemble请注意，即使 assemble 是全局安装的，最好在每个项目中本地安装它，以确保您的项目免受开发周期之间 assemble 中可能发生的任何潜在破坏性更改的影响。
要使用 assemble 的 CLI，您需要将assemblefile.js添加到您的项目中。最快的方法是运行以下命令：
$ assemble如果当前项目中不存在assemblefile.js ，assemble 会询问您是否要添加一个。如果您回答“是”，assemble 将为您生成一个基本的assembfile.js 。
从命令行运行汇编。
$ assemble < tasks > [options]指定要运行的一项或多项以空格分隔的任务。
示例
运行任务foo
$ assemble foo运行任务foo和bar
$ assemble foo bar非任务选项以--为前缀。
示例
设置--cwd以在不同的目录中运行 assemblefile.js：
$ assemble --cwd=docs在加载视图时发出视图并将其记录到stderr ：
$ assemble --emit=view查看更多[命令行选项](#命令行选项)
可以使用命令行参数中的键或值的点表示法来指定对象路径。
此外，汇编使用扩展对象（和一些自定义解析）来更轻松地通过命令行传递重要的选项和命令。所以以下所有格式都是可能的。
示例
布尔值：
$ assemble --foo
# { foo: true }键值对：
$ assemble --foo=bar
# { foo: 'bar' }嵌套布尔值：
$ assemble --option=foo
# {options: { foo: true }}嵌套键值对：
$ assemble --option=foo:bar
# {options: { foo: 'bar' }}深度嵌套的键值对：
$ assemble --option=foo.bar.baz:qux
# {options: foo: { bar: { baz: 'qux' }}}}或者在=的左侧：
$ assemble --option.foo.bar.baz=qux
# {options: foo: { bar: { baz: 'qux' }}}} 更改要运行的assemblefile.js的cwd ，可以选择指定要运行的任何任务：
$ assemble < tasks > --cwd [directory]例子
要运行examples/目录中的scaffolds示例，您需要输入：
$ assemble --cwd examples/scaffolds如果成功，您应该在命令行中看到如下内容：
指定 assemble 的 CLI 运行的配置文件的名称，默认为assemblefile.js 。
例子
$ assemble --file assemblefile.dev.js创建一个assemble应用程序。这是 assemble 模块导出的主要函数。
参数
options {Object} ：可以选择传递要使用的默认选项。例子
var assemble = require ( 'assemble' ) ;
var app = assemble ( ) ;Assemble 公开了模板库中的整个 API，用于处理模板和模板集合。该 API 比此处记录的内容要广泛得多，请参阅模板以获取更多文档。
模板和视图
在以下文档中，术语“模板”和“视图”均指同一事物的各个方面。他们的意思是这样的：
template ：实际的模板字符串view ：具有包含模板字符串的content属性的对象。由于视图是乙烯基的实例，因此您可以将视图视为“模板的乙烯基文件”。 创建用于缓存视图的模板集合：
app . create ( 'includes' , { viewType : 'partial' } ) ;选项
cwd {String} ：从 glob 将模板加载到集合时使用的基目录
viewType : {String|Array} ：与集合关联的一种或多种视图类型
添加视图
将视图添加到集合中：
app . include ( 'foo.md' , { contents : new Buffer ( 'this is contents' ) } ) ;添加多个视图：
app . includes ( {
path : 'foo.md' , contents : new Buffer ( 'this is contents' ) ,
path : 'bar.md' , contents : new Buffer ( 'this is contents' ) ,
path : 'baz.md' , contents : new Buffer ( 'this is contents' )
} ) ;
// or pass a glob (optionally override `cwd` defined on `.create`)
app . includes ( '*.{md,hbs}' , { cwd : 'templates/includes' } ) ; 视图类型在集合上定义，以确定在整个[渲染周期][]中如何处理集合中的模板。
可用类型
Assemble 支持三种视图类型：
partial ：这种类型的视图可以用作“部分”（或“部分视图”），可以注入到其他视图中。对于组件、文档片段或可重用代码或内容的其他片段很有用。这些视图被传递到渲染引擎以用作局部视图，或者如果不直接支持局部视图，则用作上下文中的变量。layout ：允许视图使用通用代码或内容“包装”其他视图（任何类型，包括其他布局或部分视图）。renderable ：与渲染文件具有一对一关系的视图，最终对网站的用户或访问者可见。例如：页面或博客文章。如果未设置其他视图类型，则会自动设置renderable视图类型。定义视图类型
您可以在创建集合时定义视图类型：
app . create ( 'snippet' , { viewType : 'partial' } ) ;或者直接在集合选项上：
app . create ( 'snippet' ) ;
app . snippets . option ( 'viewType' , [ 'partial' ] ) ; // string or array 注册模板引擎以使用给定的ext渲染视图：
app . engine ( ext , fn ) ;参数
ext {String} ：使用引擎渲染的文件的文件扩展名fn {Function} ：遵循整合引擎约定的异步函数，并采用三个参数： str 、 locals和callback 。例子
// this engine is already registered in assemble
app . engine ( 'hbs' , require ( 'engine-handlebars' ) ) ;
// create a custom engine
app . engine ( 'txt' , function ( str , locals , cb ) {
// render `str` with `locals`
cb ( null , str ) ;
} ) ;您可以通过在options.engine上设置值来告诉 assemble 对所有文件扩展名使用相同的引擎。
例子
// use engine `hbs` for rendering all files
app . option ( 'engine' , 'hbs' ) ;或者，如果您使用 .renderFile，则可以通过传递引擎名称强制使用特定引擎。
例子
使用hbs引擎渲染所有模板：
app . src ( 'templates/*.*' )
. pipe ( app . renderFile ( 'hbs' ) ) 使用给定的locals和callback渲染视图。
app . render ( view , { title : 'Foo' } , function ( err , view ) {
// `view` is an object with a rendered `content` property
} ) ;参数
view {Object|String} ：要渲染的视图locals {Object} ：传递给模板引擎以在view中渲染模板的本地变量callback {函数}Assemble 提供了以下使用文件系统的低级方法：
Assemble 对 Vinyl-fs 具有一流的支持，因此任何 gulp 插件都可以在您的 assemble 管道中使用。
创建黑胶唱片流。采用全局模式或文件路径来读取源文件。
参数
glob {String|Array} ：Glob 模式或源文件的文件路径。options {Object} ：要合并到上下文中和/或传递给src插件的选项或本地变量例子
app . src ( 'src/*.hbs' ) ;
// define `src` options
app . src ( 'src/*.hbs' , { layout : 'default' } ) ; 指定已处理文件的目的地。
参数
dest {String|Function} ：文件路径或重命名函数。options {Object} ：传递给dest插件的选项和本地变量例子
app . dest ( 'dist/' ) ; 将具有给定 glob patterns文件复制到指定的dest 。
参数
patterns {String|Array} ：要复制的文件的全局模式。dest {String|Function} ：目标目录。returns {Stream} ：流，必要时继续处理。例子
app . task ( 'assets' , function ( ) {
// return, to let assemble know when the task has completed
return app . copy ( 'assets/**' , 'dist/' ) ;
} ) ; 当文件通过流推送时渲染文件。
app . src ( '*.hbs' )
. pipe ( app . renderfile ( ) )
. pipe ( app . dest ( 'foo' ) ) ;强制使用特定引擎来渲染文件：
app . engine ( 'txt' , function ( str , locals , cb ) {
cb ( null , str ) ;
} ) ;
app . src ( '*.hbs' )
. pipe ( app . renderfile ( 'txt' ) ) //<= use engine `txt`
. pipe ( app . dest ( 'foo' ) ) ;Assemble 有以下用于运行任务和控制工作流程的方法：
定义调用任务时要运行的任务。
参数
name {String} ：任务名称fn {Function} ：任务运行时调用的函数。例子
app . task ( 'default' , function ( ) {
app . src ( 'templates/*.hbs' )
. pipe ( app . dest ( 'site/' ) ) ;
} ) ; 运行一项或多项任务。
参数
tasks {Array|String} ：任务名称或任务名称数组。cb {Function} ：暴露err的回调函数例子
app . build ( [ 'foo' , 'bar' ] , function ( err ) {
if ( err ) throw err ;
console . log ( 'done!' ) ;
} ) ; 监视文件，当监视的文件发生更改时运行一项或多项任务。
参数
glob {String|Array} ：文件路径或 glob 模式。tasks {Array} ：要观看的任务。例子
app . task ( 'watch' , function ( ) {
app . watch ( 'docs/*.md' , [ 'docs' ] ) ;
} ) ; 任何基于基础构建的应用程序的插件都应该与 Assemble 一起使用，并且可以在您的assemblefile.js中使用：
baseplugin关键字在 npm 上查找基本插件assembleplugin关键字在 npm 上查找 assemble 插件generateplugin关键字在npm上查找生成插件templatesplugin关键字在 npm 上查找模板插件updateplugin关键字在 npm 上查找更新插件verbplugin关键字在 npm 上查找 verb 插件请访问插件文档指南，了解如何使用、创作和发布插件。
联系我们！
有疑问、建议或想讨论组装吗？加入 gitter 上的对话或在 Twitter 上给我们留言。组装团队和社区总是乐意提供帮助！
网站已过时，正在重构！
Assemble 的网站 assemble.io 只有与 gulp-assemble 相关的信息。我们正在努力更新网站以提供有关最新版本的信息。
与此同时，您可能会发现 WIP 文档很有用。单元测试也是很好的例子！
组装网站是最新的吗？
不，正如上面提到的，它已经完全过时了。如果您使用 grunt-assemble，assemble.io 上的一些文档可能仍然有用。如果您使用的是 assemble v0.6.0 及更高版本，则该文档几乎在所有方面都可能是错误的。
我们正在积极（每天）进行重构，这是一个非常高的优先级。
汇编核心和汇编有什么区别？
Assemble 添加了一个 CLI、一些内置视图集合： pages 、 layouts和partials 、用于解析前面内容的中间件，以及我们发现许多用户期望的其他一些基本默认值。如果您喜欢不同的默认值，assemble-core 是一个很好的起点。
如果您想要处理模板、渲染、引擎、助手、集合等的东西，但不需要运行任务或使用文件系统，那么请考虑使用模板而不是 assemble-core。
我使用gulp，为什么建议直接使用assemble，而不是用gulp运行assemble？
您可以使用 assemble 运行 gulp 插件，但反之则不然。这是因为，作为一个构建系统，assemble 可以做 gulp 不做的事情，比如处理中间件。
例如，assemble 的.src和.dest方法具有内置的.onStream 、 .preWrite和.postWrite中间件处理程序。如果您仍然希望使用 gulp 并且您的构建周期包括需要这些处理程序的中间件，则可以将 assemble-handle 插件与 gulp 一起使用，以确保仍根据需要调用处理程序。
这是一个很长的说法，你可以找到让 gulp 工作的方法，但你只需向你的项目添加一个额外的依赖项来完成 assemble 已经完成的事情。
gulp 和 assemble 之间有什么关系？
请阅读我们的 gulp 常见问题解答以获取更多信息。
获取 Assemble 开发的最新信息并与项目维护者和社区成员聊天。
在 Twitter 上关注@assemblejs。
如果您喜欢 Assemble 并想发布有关它的推文，请随时提及@assemblejs或使用#assemble主题标签
阅读并订阅官方 Assemble 博客。
加入官方 Slack 房间。
加入 Gitter 上的对话
告诉我们您的组装项目
通过主演《集合》来表达你的爱吧！
在 StackOverflow 上获取实现帮助（请在问题中使用 assemble assemble标签）
Gitter在 Gitter 上与我们讨论集合
为了最大程度地提高可发现性，插件开发人员应在通过 npm 或类似交付机制分发时修改或添加 Assemble 功能的包上使用关键字assembleplugin 。
贡献
如果您想了解有关为该项目做出贡献的更多信息，请阅读我们的贡献指南。
您可能还对 @doowb 和 @jonschlinkert 的这些项目感兴趣：
如果 assemble 不能满足您的需要，您可能会对我们的朋友在 GitHub 上创建的其他一些很棒的开源项目感兴趣（按字母顺序排列）：
静态站点生成器
博客框架
变更日志条目使用以下标签进行分类（来自 keep-a-changelog ）：
added ：用于新功能changed ：用于现有功能的更改deprecated ：在即将发布的版本中删除了曾经稳定的功能removed ：针对此版本中删除的已弃用功能fixed ：修复任何错误此变更日志中使用的自定义标签：
dependencies ：碰撞依赖性housekeeping ：代码重新组织、较小的编辑或不属于其他类别之一的其他更改。 额外
固定的
isbinaryfile尝试从不存在的文件中读取的错误。 依赖关系
view在由app创建时用.toStream()装饰（相对于集合）。 依赖关系
固定的
view.stat更改后在某些情况下view.path为 nullview.base对于不是从文件系统创建的视图并不总是正确的依赖关系
dest处理的改进依赖关系
list上提供的新方法依赖关系
依赖关系
.log()方法，它还公开其他方法，例如.log.info() 、 .log.success()等。support/docs ，以便可以将 markdown 文档构建到docs目录.data方法中删除renameKey选项。请改用namespace选项。 将 assemble-core 升级到 v0.22.0，以利用查找方法的修复和改进： .find和getView 。未进行任何 API 更改。如果出现回归，请告知我们。
List错误app.getView()和app.find()queue属性的支持。有关更多详细信息，请参阅 assemble-core。file.base错误，导致在某些情况下 dest 目录相对于 cwd 而不是 glob 父级。renameKey在集合加载器选项上定义时并不总是使用。debug方法和相关代码已被删除node_modules并重新安装所有依赖项，以避免出现isRegistered is not a function等错误.watch方法，转而使用base-watch插件。（由 helper-changelog 生成的变更日志）
拉取请求和星星总是受欢迎的。对于错误和功能请求，请创建问题。
请阅读贡献指南，获取有关开放问题、拉取请求和编码标准的建议。
如果 Assemble 不能满足您的需要，请告诉我们
| 提交 | 贡献者 |
|---|---|
| 第1497章 | 永施林克特 |
| 第842章 | 杜布 |
| 11 | 安德斯·约翰逊 |
| 7 | 阿基马阿吉 |
| 7 | 史蒂芬瓦尔特 |
| 4 | 平均电压 |
| 4 | 弯曲者 |
| 2 | 伟大圣罗 |
| 2 | 劳贝尔丹尼尔 |
| 2 | 奥诺库穆斯 |
| 2 | 罗布·洛奇 |
| 2 | 史蒂文·布莱克 |
| 2 | 西西弗 |
| 2 | 艾因 |
| 1 | 阿桑斯 |
| 1 | 鲍尔卡 |
| 1 | 凯西G1204 |
| 1 | 海扎克 |
| 1 | 莫塔里 |
| 1 | 批判性混搭 |
| 1 | 乔纳西 |
| 1 | 约旦托马斯 |
| 1 | 弗雷耶尔 |
| 1 | 犯人 |
| 1 | 普布尔查尔 |
| 1 | 斯克莫里森 |
| 1 | 肿瘤 |
| 1 | 泰勒霍沃斯 |
| 1 | 克洛基 |
乔恩·施林克特
布赖恩·伍德沃德
版权所有 © 2017，乔恩·施林克特。麻省理工学院
该文件由 verb-generate-readme v0.6.0 于 2017 年 12 月 27 日生成。
