assemble
1.0.0
¿Buscas el complemento gruñido? Por favor visite gruñido-ensamblaje.
(Tenga en cuenta que el sitio web actual, ensamblaje.io, es para grunt-assemble. Gracias por su paciencia mientras trabajamos en la actualización del sitio con documentación para el último ensamblaje) .
(Haga clic en las siguientes secciones para expandirlas)
(TOC generado por el verbo usando markdown-toc)
Assemble es una herramienta de línea de comandos y un marco de desarrollo para la creación rápida de prototipos, generación de sitios estáticos y mucho más.
¡Assemble es utilizado por miles de desarrolladores y equipos en más de 170 países! A continuación se muestran algunos ejemplos de sitios creados con ensamblado:
¿Su sitio web, blog o proyecto está construido con ensamblar? ¡Háganos saber al respecto!
Assemble se puede usar de forma independiente, pero es aún más poderoso cuando se usa junto con las siguientes bibliotecas:
Estas son solo algunas de las características que ofrece el ensamblaje:
Agregue y ensamble devDependencies de su proyecto usando npm:
$ npm install -D assemble Ahora debería poder ejecutar ensamblar directamente (usando node assemblefile.js , etc.) o usando scripts npm . Por ejemplo, agregue lo siguiente a package.json:
{
"scripts" : {
"build" : " assemble "
}
}Entonces corre
$ npm run build También puede ensamblar la CLI globalmente, lo que agrega el comando assemble a la ruta de su sistema, lo que permite ejecutarlo desde cualquier directorio.
$ npm install --global assembleTenga en cuenta que incluso si ensamblar se instala globalmente, es una buena práctica instalarlo localmente en cada proyecto para garantizar que sus proyectos estén protegidos contra cualquier cambio potencialmente importante que pueda ocurrir en ensamblar entre ciclos de desarrollo.
Para usar la CLI de ensamblar, deberá agregar un assemblefile.js a su proyecto. La forma más rápida de hacerlo es ejecutar el siguiente comando:
$ assemble Si no existe assemblefile.js en el proyecto actual, ensamblar le preguntará si desea agregar uno. Si responde que sí, ensamblar generará un assembfile.js básico para usted.
Ejecute ensamblar desde la línea de comando.
$ assemble < tasks > [options]Especifique una o más tareas separadas por espacios para ejecutar.
Ejemplos
Ejecutar tarea foo
$ assemble foo Ejecutar tareas foo y bar
$ assemble foo bar Las opciones que no son tareas tienen el prefijo -- .
Ejemplos
Configure --cwd para ejecutar un ensamblado.js en un directorio diferente:
$ assemble --cwd=docs Emita vistas a medida que se cargan y regístrelas en stderr :
$ assemble --emit=viewVer más [opciones de línea de comando](#opciones de línea de comando)
Las rutas de objetos se pueden especificar usando notación de puntos para la clave o el valor en un argumento de línea de comando.
Además, ensamblar utiliza expandir objeto (y algunos análisis personalizados) para facilitar la transferencia de opciones y comandos no triviales a través de la línea de comandos. Entonces todos los siguientes formatos son posibles.
Ejemplos
Valores booleanos:
$ assemble --foo
# { foo: true }Pares clave-valor:
$ assemble --foo=bar
# { foo: 'bar' }Booleanos anidados:
$ assemble --option=foo
# {options: { foo: true }}Pares clave-valor anidados:
$ assemble --option=foo:bar
# {options: { foo: 'bar' }}Pares clave-valor profundamente anidados:
$ assemble --option=foo.bar.baz:qux
# {options: foo: { bar: { baz: 'qux' }}}} O en el lado izquierdo de = :
$ assemble --option.foo.bar.baz=qux
# {options: foo: { bar: { baz: 'qux' }}}} Cambie el cwd para que se ejecute assemblefile.js , especificando opcionalmente cualquier tarea a ejecutar:
$ assemble < tasks > --cwd [directory]Ejemplo
Para ejecutar el ejemplo scaffolds en el directorio examples/ , deberá ingresar:
$ assemble --cwd examples/scaffoldsSi tiene éxito, en la línea de comando, debería ver algo como esto:
Especifique el nombre del archivo de configuración para que se ejecute la CLI de ensamblar; el valor predeterminado es assemblefile.js .
Ejemplo
$ assemble --file assemblefile.dev.js Crea una aplicación assemble . Esta es la función principal exportada por el módulo de ensamblaje.
parámetros
options {Objeto} : Opcionalmente, pase las opciones predeterminadas para usar.Ejemplo
var assemble = require ( 'assemble' ) ;
var app = assemble ( ) ;Assemble expone toda la API de la biblioteca de plantillas para trabajar con plantillas y colecciones de plantillas. La API es mucho más extensa de lo que se documenta aquí; consulte las plantillas para obtener más documentación.
Plantillas y vistas
En la siguiente documentación, los términos "plantilla" y "vista" se refieren a aspectos de la misma cosa. Esto es lo que quieren decir:
template : una cadena de plantilla realview : un objeto con una propiedad content que contiene la cadena de plantilla. Dado que las vistas son instancias de vinilo, puede considerarlas como un "archivo de vinilo para plantillas". Cree una colección de plantillas para almacenar en caché vistas:
app . create ( 'includes' , { viewType : 'partial' } ) ;Opciones
cwd {String} : el directorio base que se usará al cargar plantillas en la colección desde un globo
viewType : {String|Array} : uno o más tipos de vista para asociar con la colección
Agregar vistas
Añade una vista a la colección:
app . include ( 'foo.md' , { contents : new Buffer ( 'this is contents' ) } ) ;Agregar varias vistas:
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' } ) ; Los tipos de vista se definen en una colección para determinar cómo se manejarán las plantillas de la colección durante el [ciclo de renderizado][].
Tipos disponibles
Assemble admite tres tipos de vistas:
partial : las vistas con este tipo se pueden utilizar como "parciales" (o "vistas parciales"), que se pueden inyectar en otras vistas. Útil para componentes, fragmentos de documentos u otros fragmentos de código o contenido reutilizable. Estas vistas se pasan a los motores de renderizado para usarlas como parciales o variables en el contexto si los parciales no son compatibles directamente.layout : permite que las vistas "envuelvan" otras vistas (de cualquier tipo, incluidos otros diseños o parciales) con código o contenido común.renderable : vistas que tienen una relación uno a uno con archivos renderizados que eventualmente serán visibles para un usuario o visitante de un sitio web. Por ejemplo: páginas o publicaciones de blog. El tipo de vista renderable se configura automáticamente si no se configuran otros tipos de vista.Definición de tipos de vista
Puede definir tipos de vista cuando se crea una colección:
app . create ( 'snippet' , { viewType : 'partial' } ) ;O directamente en las opciones de recogida:
app . create ( 'snippet' ) ;
app . snippets . option ( 'viewType' , [ 'partial' ] ) ; // string or array Registre el motor de plantillas para renderizar vistas con la ext dada:
app . engine ( ext , fn ) ;parámetros
ext {String} : La extensión de archivo de los archivos para renderizar con el motor.fn {Función} : función asíncrona que sigue las convenciones del motor consolidada y toma tres argumentos: str , locals y callback .Ejemplo
// 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 ) ;
} ) ; Puede indicarle a ensamblar que use el mismo motor para todas las extensiones de archivo estableciendo un valor en options.engine .
Ejemplo
// use engine `hbs` for rendering all files
app . option ( 'engine' , 'hbs' ) ;O, si está utilizando .renderFile, puede forzar el uso de un motor específico pasando el nombre del motor.
Ejemplo
Utilice el motor hbs para renderizar todas las plantillas:
app . src ( 'templates/*.*' )
. pipe ( app . renderFile ( 'hbs' ) ) Representa una vista con los locals proporcionados y callback .
app . render ( view , { title : 'Foo' } , function ( err , view ) {
// `view` is an object with a rendered `content` property
} ) ;parámetros
view {Object|String} : La vista a renderizarlocals {Objeto} : locales para pasar al motor de plantillas para mostrar las plantillas a viewcallback {Función}Assemble ofrece los siguientes métodos de bajo nivel para trabajar con el sistema de archivos:
Assemble tiene soporte de primera clase para vinil-fs, por lo que se puede utilizar cualquier complemento gulp en su proceso de ensamblaje.
Crea una transmisión de vinilo. Toma patrones globales o rutas de archivos a los archivos fuente para leer.
parámetros
glob {String|Array} : patrones globales o rutas de archivos a los archivos fuente.options {Objeto} : Opciones o locales para fusionar en el contexto y/o pasar a complementos srcEjemplo
app . src ( 'src/*.hbs' ) ;
// define `src` options
app . src ( 'src/*.hbs' , { layout : 'default' } ) ; Especifique un destino para los archivos procesados.
parámetros
dest {Cadena|Función} : ruta del archivo o función de cambio de nombre.options {Objeto} : opciones y locales para pasar a los complementos destEjemplo
app . dest ( 'dist/' ) ; Copie archivos con los patterns globales dados al dest especificado.
parámetros
patterns {String|Array} : patrones globales de archivos para copiar.dest {Cadena|Función} : Directorio de destino.returns {Stream} : Stream, para continuar procesando si es necesario.Ejemplo
app . task ( 'assets' , function ( ) {
// return, to let assemble know when the task has completed
return app . copy ( 'assets/**' , 'dist/' ) ;
} ) ; Representa archivos a medida que se envían a través de la secuencia.
app . src ( '*.hbs' )
. pipe ( app . renderfile ( ) )
. pipe ( app . dest ( 'foo' ) ) ;Fuerce el uso de un motor específico para renderizar archivos:
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 tiene los siguientes métodos para ejecutar tareas y controlar flujos de trabajo:
Defina una tarea que se ejecutará cuando se llame a la tarea.
parámetros
name {String} : nombre de la tareafn {Función} : función que se llama cuando se ejecuta la tarea.Ejemplo
app . task ( 'default' , function ( ) {
app . src ( 'templates/*.hbs' )
. pipe ( app . dest ( 'site/' ) ) ;
} ) ; Ejecute una o más tareas.
parámetros
tasks {Array|String} : nombre de la tarea o conjunto de nombres de tareas.cb {Función} : función de devolución de llamada que expone errEjemplo
app . build ( [ 'foo' , 'bar' ] , function ( err ) {
if ( err ) throw err ;
console . log ( 'done!' ) ;
} ) ; Observe archivos, ejecute una o más tareas cuando cambie un archivo observado.
parámetros
glob {String|Array} : rutas de archivos o patrones globales.tasks {Array} : Tarea(s) a observar.Ejemplo
app . task ( 'watch' , function ( ) {
app . watch ( 'docs/*.md' , [ 'docs' ] ) ;
} ) ; Los complementos de cualquier aplicación creada en base deberían funcionar con Assemble y pueden usarse en su assemblefile.js :
basepluginassembleplugingenerateplugintemplatespluginupdatepluginverbpluginVisite la guía de documentación de complementos para aprender a usar, crear y publicar complementos.
¡Ponte en contacto!
¿Tiene preguntas, sugerencias o quiere discutir el montaje? Únase a la conversación en gitter o avísenos en Twitter. ¡El equipo de ensamblaje y la comunidad siempre estarán felices de ayudar!
¡El sitio web está desactualizado y se está refactorizando!
El sitio web de Assemble, ensamblar.io, solo tiene información relacionada con gulp-assemble. Estamos trabajando arduamente para actualizar el sitio con información sobre la última versión.
Mientras tanto, es posible que los documentos WIP le resulten útiles. ¡Las pruebas unitarias también son excelentes ejemplos!
¿Está actualizado el sitio web de la asamblea?
No, como se mencionó anteriormente, está completamente desactualizado. Si está utilizando grunt-assemble, parte de la documentación en ensamblar.io aún podría resultar útil. Si está utilizando ensamblador v0.6.0 y superior, la documentación probablemente sea incorrecta en casi todos los sentidos.
Estamos trabajando activamente (diariamente) en una refactorización y es una prioridad muy alta.
¿Cuál es la diferencia entre ensamblar-núcleo y ensamblar?
Assemble agrega una CLI, algunas colecciones de vistas integradas: pages , layouts y partials , middleware para analizar el contenido inicial y algunos otros valores predeterminados básicos que muchos usuarios esperan. Si prefiere valores predeterminados diferentes, ensamblar núcleo es un excelente punto de partida.
Si desea algo que maneje plantillas, renderizado, motores, ayudas, colecciones, etc. pero no necesita ejecutar tareas o trabajar con el sistema de archivos, considere usar plantillas en lugar de ensamblar núcleo.
Utilizo gulp, ¿por qué se recomienda utilizar ensamblar directamente en lugar de ejecutar ensamblar con gulp?
Puedes ejecutar complementos gulp con ensamblador, pero no siempre funcionará al revés. Esto se debe a que, como sistema de compilación, ensamblar hace cosas que gulp no hace, como manejar middleware.
Por ejemplo, los métodos .src y .dest de ensamblado tienen controladores de middleware .onStream , .preWrite y .postWrite integrados. Si aún desea usar gulp y su ciclo de compilación incluye middleware que requiere estos controladores, puede usar el complemento ensamblador-handle con gulp para asegurarse de que los controladores aún se llamen según sea necesario.
Esta es una manera larga de decir que puedes encontrar maneras de hacer que gulp funcione, pero solo estarías agregando una dependencia adicional a tu proyecto para hacer cosas que ensamblar ya hace.
¿Cuál es la relación entre tragar y ensamblar?
Lea nuestras preguntas frecuentes sobre gulp para obtener más información.
Obtenga actualizaciones sobre el desarrollo de Assemble y charle con los mantenedores del proyecto y los miembros de la comunidad.
Siga a @assemblejs en Twitter.
Si te gusta Assemble y quieres twittear sobre ello, no dudes en mencionar @assemblejs o usar el hashtag #assemble .
Lea y suscríbase al blog oficial de Assemble.
Únase a la sala oficial de Slack.
Únase a la conversación sobre Gitter
Cuéntanos sobre tu proyecto de montaje.
¡Muestre su amor protagonizando Assemble!
Obtenga ayuda para la implementación en StackOverflow (use la etiqueta assemble ensamblar en las preguntas)
Gitter Discute Reúnete con nosotros en Gitter
Para lograr la máxima visibilidad, los desarrolladores de complementos deben usar la palabra clave assembleplugin en paquetes que modifican o agregan funcionalidad a Assemble cuando se distribuyen a través de npm o mecanismos de entrega similares.
Contribuyendo
Lea nuestra guía de contribución si desea obtener más información sobre cómo contribuir a este proyecto.
Quizás también te interesen estos proyectos de @doowb y @jonschlinkert:
Si ensamblar no hace lo que necesita, hay otros excelentes proyectos de código abierto que podrían interesarle, creados por nuestros amigos en GitHub (en orden alfabético):
Generadores de sitios estáticos
Marcos de blogs
Las entradas del registro de cambios se clasifican utilizando las siguientes etiquetas (de keep-a-changelog ):
added : para nuevas característicaschanged : para cambios en la funcionalidad existentedeprecated : para funciones que alguna vez fueron estables, se eliminarán en próximas versionesremoved : para funciones obsoletas eliminadas en esta versiónfixed : para cualquier corrección de erroresEtiquetas personalizadas utilizadas en este registro de cambios:
dependencies : elimina las dependenciashousekeeping : reorganización del código, ediciones menores u otros cambios que no encajan en una de las otras categorías. agregado
fijado
isbinaryfile intentaba leer desde un archivo que no existía. dependencias
view esté decorada con .toStream() cuando la crea app (a diferencia de una colección). dependencias
fijado
view.stat fuera nulo en algunos casos después de que view.path cambiaraview.base no siempre fue correcto en las vistas que no se crearon desde el sistema de archivos dependencias
dest . dependencias
list Dependencias
Dependencias
.log() , que también expone métodos adicionales, como .log.info() , .log.success() , etc.support/docs , para que los documentos de rebajas se puedan crear en el directorio docs .renameKey del método .data . Utilice la opción de namespace en su lugar. Se actualiza el núcleo de ensamblaje a v0.22.0 para aprovechar las correcciones y mejoras en los métodos de búsqueda: .find y getView . No se realizaron cambios en la API. Háganos saber si se producen regresiones.
List que causaba que los ayudantes de colección explotaranapp.getView() y app.find()queue en las colecciones. Consulte ensamblar núcleo para obtener detalles adicionales.file.base , lo que provocaba que el directorio dest fuera relativo a cwd en lugar de glob parent en algunos casos.renameKey no siempre se usara cuando se define en las opciones del cargador de colecciones.debug y el código relacionado.node_modules y reinstalar todas las dependencias para evitar errores como que isRegistered is not a function .watch a favor del uso del complemento base-watch.(Registro de cambios generado por helper-changelog)
Las solicitudes de extracción y las estrellas siempre son bienvenidas. Para errores y solicitudes de funciones, cree un problema.
Lea la guía de contribución para obtener consejos sobre problemas de apertura, solicitudes de extracción y estándares de codificación.
Si Assemble no hace lo que necesita, háganoslo saber.
| Se compromete | Contribuyente |
|---|---|
| 1497 | jonschlinkert |
| 842 | puerta |
| 11 | andersdjohnson |
| 7 | Arkkimaagi |
| 7 | stefanwalther |
| 4 | avr |
| 4 | bendrucker |
| 2 | la gran sunra |
| 2 | rauberdaniel |
| 2 | onokumus |
| 2 | Rob Loach |
| 2 | StevenNegro |
| 2 | xzyfer |
| 2 | es |
| 1 | asanas |
| 1 | bauerca |
| 1 | caseyg1204 |
| 1 | hyzhak |
| 1 | mootari |
| 1 | mezcla crítica |
| 1 | joonasy |
| 1 | jordántomas |
| 1 | frayer |
| 1 | defensor |
| 1 | pburtchaell |
| 1 | scmorrison |
| 1 | oncletom |
| 1 | tylerhowarth |
| 1 | klokie |
Jon Schlinkert
Brian Woodward
Copyright © 2017, Jon Schlinkert. MIT
Este archivo fue generado por verb-generate-readme, v0.6.0, el 27 de diciembre de 2017.
