assemble
1.0.0
Ищете плагин grunt? Пожалуйста, посетите grunt-assemble.
(Обратите внимание, что текущий веб-сайт assemble.io предназначен для grunt-assemble. Спасибо за ваше терпение, пока мы работаем над обновлением сайта документацией для последней сборки) .
(Нажмите следующие разделы, чтобы развернуть их)
(TOC генерируется глаголом с использованием markdown-toc)
Assemble — это инструмент командной строки и среда разработки для быстрого прототипирования, создания статических сайтов и многого другого.
Assemble используют тысячи разработчиков и команд в более чем 170 странах! Вот несколько примеров сайтов, созданных с помощью Assemble:
Ваш веб-сайт, блог или проект построен на сборке? Пожалуйста, сообщите нам об этом!
Assemble можно использовать автономно, но он становится еще более мощным, если используется вместе со следующими библиотеками:
Вот лишь некоторые особенности сборных предложений:
Добавьте сборку devDependencies вашего проекта с помощью npm:
$ npm install -D assemble Теперь вы сможете запускать сборку напрямую (используя node assemblefile.js и т. д.) или используя сценарии npm . Например, добавьте в package.json следующее:
{
"scripts" : {
"build" : " assemble "
}
}Затем запустите
$ npm run build Вы также можете глобально использовать CLI сборки, что добавляет команду assemble в системный путь, позволяя запускать ее из любого каталога.
$ npm install --global assembleОбратите внимание: даже если сборка установлена глобально, рекомендуется устанавливать ее локально в каждом проекте, чтобы гарантировать защиту ваших проектов от любых потенциально критических изменений, которые могут произойти в сборке между циклами разработки.
Чтобы использовать CLI сборки, вам необходимо добавить файл assemblefile.js в свой проект. Самый быстрый способ сделать это — выполнить следующую команду:
$ assemble Если в текущем проекте assemblefile.js не существует, сборка спросит, хотите ли вы его добавить. Если вы ответите «да», сборка сгенерирует для вас базовый 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' }}}} Измените cwd для запуска assemblefile.js , при необходимости указав любые задачи для запуска:
$ assemble < tasks > --cwd [directory]Пример
Чтобы запустить пример scaffolds в каталоге examples/ , вы должны ввести:
$ assemble --cwd examples/scaffoldsВ случае успеха в командной строке вы должны увидеть что-то вроде этого:
Укажите имя файла конфигурации для запуска CLI сборки, по умолчанию — assemblefile.js .
Пример
$ assemble --file assemblefile.dev.js Создайте приложение assemble . Это основная функция, экспортируемая модулем сборки.
Параметры
options {Object} : опционально передать параметры по умолчанию для использования.Пример
var assemble = require ( 'assemble' ) ;
var app = assemble ( ) ;Assemble предоставляет весь API из библиотеки шаблонов для работы с шаблонами и коллекциями шаблонов. API гораздо более обширен, чем описано здесь; дополнительную документацию см. в шаблонах.
Шаблоны и представления
В следующей документации термины «шаблон» и «представление» относятся к одному и тому же аспекту . Вот что они означают:
template : фактическая строка шаблонаview : объект со свойством content , содержащим строку шаблона. Поскольку представления являются экземплярами винила, представление можно рассматривать как «виниловый файл для шаблонов». Создайте коллекцию шаблонов для кэширования представлений:
app . create ( 'includes' , { viewType : 'partial' } ) ;Параметры
cwd {String} : базовый каталог, используемый при загрузке шаблонов в коллекцию из глобального объекта.
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' } ) ; Типы представлений определяются в коллекции, чтобы определить, как шаблоны в коллекции будут обрабатываться на протяжении [цикла рендеринга][].
Доступные типы
Сборка поддерживает три типа представления:
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 .
Пример
// 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} : локальные значения для передачи в механизм шаблонов для рендеринга шаблонов в viewcallback {функция}Assemble предлагает следующие низкоуровневые методы работы с файловой системой:
Assemble имеет первоклассную поддержку виниловых файлов, поэтому в вашем конвейере сборки можно использовать любой плагин gulp.
Создайте виниловый поток. Принимает шаблоны glob или пути к исходным файлам для чтения.
Параметры
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/' ) ; Скопируйте файлы с заданными patterns glob в указанное dest .
Параметры
patterns {String|Array} : шаблоны файлов для копирования.dest {String|Function} : Каталог назначения.returns {Stream} : 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 :
basepluginassembleplugingenerateplugintemplatespluginupdatepluginverbpluginПосетите руководство по документации плагинов, чтобы узнать, как использовать, создавать и публиковать плагины.
Свяжитесь с нами!
Есть вопросы, предложения или хотите обсудить сборку? Присоединяйтесь к обсуждению на Gitter или сообщите нам об этом в Твиттере. Команда сборки и сообщество всегда рады помочь!
Сайт устарел и находится на рефакторинге!
На веб-сайте Assemble.io представлена только информация, относящаяся к gulp-assemble. Мы прилагаем все усилия, чтобы обновлять сайт информацией о последней версии.
Тем временем документация WIP может оказаться вам полезной. Модульные тесты также являются отличным примером!
Обновлен ли сайт сборки?
Нет, как уже говорилось выше, оно полностью устарело. Если вы используете grunt-assemble, некоторая документация на assemble.io может оказаться полезной. Если вы используете сборку v0.6.0 и выше, документация, вероятно, неверна почти во всех отношениях.
Мы активно (ежедневно) работаем над рефакторингом, и это очень высокий приоритет.
В чем разница между сборкой ядра и сборкой?
Assemble добавляет интерфейс командной строки, несколько встроенных коллекций представлений: pages , layouts и partials , промежуточное программное обеспечение для анализа исходной информации и несколько других базовых настроек по умолчанию, которые, как мы обнаружили, ожидают многие пользователи. Если вы предпочитаете другие значения по умолчанию, сборка ядра — отличная отправная точка.
Если вам нужно что-то, что обрабатывает шаблоны, рендеринг, механизмы, помощники, коллекции и т. д., но вам не нужно запускать задачи или работать с файловой системой, рассмотрите возможность использования шаблонов вместо assemble-core.
Я использую gulp, почему рекомендуется использовать сборку напрямую, а не запускать сборку с помощью gulp?
Вы можете запускать плагины gulp с помощью ассемблера, но наоборот это не всегда работает. Это связано с тем, что, как система сборки, сборка делает то, чего не делает gulp, например, обрабатывает промежуточное программное обеспечение.
Например, методы сборки .src и .dest имеют встроенные обработчики промежуточного программного обеспечения .onStream , .preWrite и .postWrite . Если вы все еще хотите использовать gulp и ваш цикл сборки включает промежуточное программное обеспечение, требующее этих обработчиков, вы можете использовать плагин assemble-handle с gulp, чтобы гарантировать, что обработчики по-прежнему вызываются по мере необходимости.
Это слишком длинное слово: вы можете найти способы заставить gulp работать, но вы просто добавите в свой проект дополнительную зависимость, чтобы делать то, что сборка уже делает.
Какова связь между gulp и assemble?
Пожалуйста, прочитайте наш FAQ по gulp для получения дополнительной информации.
Получайте обновления о разработке Assemble и общайтесь с сопровождающими проекта и членами сообщества.
Следите за @assemblejs в Твиттере.
Если вам нравится Assemble и вы хотите написать об этом в Твиттере, не стесняйтесь упомянуть @assemblejs или использовать хэштег #assemble .
Читайте и подписывайтесь на официальный блог Assemble.
Присоединяйтесь к официальной комнате Slack.
Присоединяйтесь к обсуждению на Gitter
Расскажите нам о своем сборочном проекте
Покажите свою любовь, сыграв главную роль в Assemble!
Получите помощь по реализации на StackOverflow (пожалуйста, используйте тег assemble в вопросах)
Gitter Обсудить сборку с нами на Gitter
Для максимальной видимости разработчикам плагинов следует использовать ключевое слово assembleplugin в пакетах, которые изменяют или добавляют функциональность Assemble при распространении через npm или аналогичные механизмы доставки.
Содействие
Пожалуйста, прочитайте наше руководство по участию, если вы хотите узнать больше о том, как внести свой вклад в этот проект.
Вас также могут заинтересовать эти проекты @doowb и @jonschlinkert:
Если сборка не делает того, что вам нужно, есть еще несколько замечательных проектов с открытым исходным кодом, которые могут вас заинтересовать, созданные нашими друзьями на GitHub (в алфавитном порядке):
Генераторы статических сайтов
Фреймворки для блогов
Записи журнала изменений классифицируются с использованием следующих меток (из Keep-a-changelog ):
added : для новых функцийchanged : для изменений в существующей функциональностиdeprecated : для некогда стабильных функций, удаленных в будущих выпусках.removed : для устаревших функций, удаленных в этом выпуске.fixed : для любых исправлений ошибокПользовательские метки, используемые в этом журнале изменений:
dependencies : увеличивает зависимостиhousekeeping : реорганизация кода, незначительные правки или другие изменения, которые не вписываются ни в одну из других категорий. добавлен
зафиксированный
isbinaryfile пытался прочитать файл, которого не существовало. зависимости
view будет украшено .toStream() при создании app (а не коллекцией). зависимости
зафиксированный
view.stat становился нулевым после изменения view.pathview.base не всегда был корректным для представлений, созданных не из файловой системы. зависимости
dest . зависимости
list s. Зависимости
Зависимости
.log() , который также предоставляет дополнительные методы, такие как .log.info() , .log.success() и т. д.support/docs , чтобы документы с уценкой можно было создавать в каталоге docs .renameKey из метода .data . Вместо этого используйте опцию namespace . Обновлено ядро сборки до версии 0.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 | xzyfer |
| 2 | нет |
| 1 | асаны |
| 1 | Бауэрка |
| 1 | Caseyg1204 |
| 1 | хыжак |
| 1 | мутари |
| 1 | Критикмаш |
| 1 | безумие |
| 1 | Иордантомас |
| 1 | дробовик |
| 1 | защитник |
| 1 | Пбурчель |
| 1 | Скморрисон |
| 1 | онклетом |
| 1 | Тайлерховарт |
| 1 | клоки |
Джон Шлинкерт
Брайан Вудворд
Авторские права © 2017, Джон Шлинкерт. Массачусетский технологический институт
Этот файл был создан verb-generate-readme, v0.6.0, 27 декабря 2017 г.
