assemble
1.0.0
Procurando pelo plugin grunhido? Por favor, visite grunt-assembly.
(Observe que o site atual assemble.io é para grunt-assemble. Obrigado pela sua paciência enquanto trabalhamos na atualização do site com a documentação para a montagem mais recente) .
(Clique nas seções a seguir para expandi-las)
(TOC gerado por verbo usando markdown-toc)
Assemble é uma ferramenta de linha de comando e estrutura de desenvolvedor para prototipagem rápida, geração de sites estáticos e muito mais.
O Assemble é usado por milhares de desenvolvedores e equipes em mais de 170 países! Aqui estão alguns exemplos de sites construídos com montagem:
Seu site, blog ou projeto é construído em assembler? Por favor, deixe-nos saber sobre isso!
Assemble pode ser usado de forma independente, mas é ainda mais poderoso quando usado junto com as seguintes bibliotecas:
Aqui estão apenas alguns dos recursos que a montagem oferece:
Adicione a montagem das devDependencies do seu projeto usando npm:
$ npm install -D assemble Agora você deve ser capaz de executar o assemble diretamente (usando node assemblefile.js etc) ou usando scripts npm . Por exemplo, adicione o seguinte ao package.json:
{
"scripts" : {
"build" : " assemble "
}
}Então corra
$ npm run build Você também pode montar a CLI globalmente, o que adiciona o comando assemble ao caminho do sistema, permitindo que ele seja executado a partir de qualquer diretório.
$ npm install --global assembleObserve que mesmo que o assemble seja instalado globalmente, é uma boa prática instalá-lo localmente em cada projeto para garantir que seus projetos estejam protegidos contra quaisquer alterações potencialmente significativas que possam ocorrer no assembly entre os ciclos de desenvolvimento.
Para usar a CLI do assemble, você precisará adicionar um assemblefile.js ao seu projeto. A maneira mais rápida de fazer isso é executar o seguinte comando:
$ assemble Se não existir nenhum assemblefile.js no projeto atual, o assemble perguntará se você deseja adicionar um. Se você responder sim, o assemble irá gerar um assembfile.js básico para você.
Execute o assembler na linha de comando.
$ assemble < tasks > [options]Especifique uma ou mais tarefas separadas por espaço para execução.
Exemplos
Execute a tarefa foo
$ assemble foo Execute tarefas foo e bar
$ assemble foo bar As opções que não são de tarefa são prefixadas com -- .
Exemplos
Defina --cwd para executar um assemblefile.js em um diretório diferente:
$ assemble --cwd=docs Emita visualizações à medida que são carregadas e registre-as em stderr :
$ assemble --emit=viewVeja mais [opções de linha de comando](#opções de linha de comando)
Os caminhos dos objetos podem ser especificados usando a notação de ponto para a chave ou o valor em um argumento de linha de comando.
Além disso, o assemble usa expand-object (e alguma análise personalizada) para facilitar a passagem de opções e comandos não triviais por meio da linha de comando. Portanto, todos os formatos a seguir são possíveis.
Exemplos
Valores booleanos:
$ assemble --foo
# { foo: true }Pares de valores-chave:
$ assemble --foo=bar
# { foo: 'bar' }Booleanos aninhados:
$ assemble --option=foo
# {options: { foo: true }}Pares de valores-chave aninhados:
$ assemble --option=foo:bar
# {options: { foo: 'bar' }}Pares de valores-chave profundamente aninhados:
$ assemble --option=foo.bar.baz:qux
# {options: foo: { bar: { baz: 'qux' }}}} Ou no lado esquerdo do = :
$ assemble --option.foo.bar.baz=qux
# {options: foo: { bar: { baz: 'qux' }}}} Altere o cwd para a execução do assemblefile.js , especificando opcionalmente quaisquer tarefas a serem executadas:
$ assemble < tasks > --cwd [directory]Exemplo
Para executar o exemplo scaffolds no diretório examples/ , você digitaria:
$ assemble --cwd examples/scaffoldsSe for bem-sucedido, na linha de comando, você verá algo assim:
Especifique o nome do arquivo de configuração para a CLI do assembler ser executada, o padrão é assemblefile.js .
Exemplo
$ assemble --file assemblefile.dev.js Crie um aplicativo assemble . Esta é a principal função exportada pelo módulo assemble.
Parâmetros
options {Object} : Opcionalmente, passe opções padrão para usar.Exemplo
var assemble = require ( 'assemble' ) ;
var app = assemble ( ) ;Assemble expõe toda a API da biblioteca de modelos para trabalhar com modelos e coleções de modelos. A API é muito mais extensa do que está documentada aqui, consulte os modelos para obter mais documentação.
Modelos e visualizações
Na documentação a seguir, os termos "modelo" e "visualização" referem-se a aspectos da mesma coisa. Aqui está o que eles significam:
template : uma string de modelo realview : um objeto com uma propriedade content que contém a string do modelo. Como as visualizações são instâncias de vinil, você pode pensar em uma visualização como um “arquivo de vinil para modelos”. Crie uma coleção de modelos para armazenar visualizações em cache:
app . create ( 'includes' , { viewType : 'partial' } ) ;Opções
cwd {String} : o diretório base a ser usado ao carregar modelos na coleção a partir de um glob
viewType : {String|Array} : um ou mais tipos de visualização para associar à coleção
Adicionar visualizações
Adicione uma visualização à coleção:
app . include ( 'foo.md' , { contents : new Buffer ( 'this is contents' ) } ) ;Adicione várias visualizações:
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' } ) ; Os tipos de visualização são definidos em uma coleção para determinar como os modelos da coleção serão tratados durante o [ciclo de renderização][].
Tipos disponíveis
Assemble oferece suporte a três tipos de visualização:
partial : visualizações com este tipo podem ser usadas como "parciais" (ou "visualizações parciais"), que podem ser injetadas em outras visualizações. Útil para componentes, fragmentos de documentos ou outros trechos de código ou conteúdo reutilizável. Essas visualizações são passadas para mecanismos de renderização para serem usadas como parciais ou variáveis no contexto se parciais não forem diretamente suportadas.layout : permite que as visualizações "envolvam" outras visualizações (de qualquer tipo, incluindo outros layouts ou parciais) com código ou conteúdo comum.renderable : visualizações que têm um relacionamento individual com arquivos renderizados que eventualmente ficarão visíveis para um usuário ou visitante de um site. Por exemplo: páginas ou postagens de blog. O tipo de visualização renderable será definido automaticamente se nenhum outro tipo de visualização for definido.Definindo tipos de visualização
Você pode definir tipos de visualização quando uma coleção é criada:
app . create ( 'snippet' , { viewType : 'partial' } ) ;Ou diretamente nas opções de coleta:
app . create ( 'snippet' ) ;
app . snippets . option ( 'viewType' , [ 'partial' ] ) ; // string or array Registre o mecanismo de modelo para renderizar visualizações com o ext fornecido:
app . engine ( ext , fn ) ;Parâmetros
ext {String} : A extensão dos arquivos a serem renderizados com o mecanismofn {Function} : função assíncrona que segue as convenções do mecanismo de consolidação e recebe três argumentos: str , locals e callback .Exemplo
// 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 ) ;
} ) ; Você pode dizer ao assembler para usar o mesmo mecanismo para todas as extensões de arquivo definindo um valor em options.engine .
Exemplo
// use engine `hbs` for rendering all files
app . option ( 'engine' , 'hbs' ) ;Ou, se estiver usando .renderFile, você pode forçar o uso de um mecanismo específico passando o nome do mecanismo.
Exemplo
Use o mecanismo hbs para renderizar todos os modelos:
app . src ( 'templates/*.*' )
. pipe ( app . renderFile ( 'hbs' ) ) Renderize uma visualização com os locals e callback fornecidos.
app . render ( view , { title : 'Foo' } , function ( err , view ) {
// `view` is an object with a rendered `content` property
} ) ;Parâmetros
view {Object|String} : A visualização a ser renderizadalocals {Object} : locais a serem passados para o mecanismo de modelo para renderizar modelos na viewcallback {Função}Assemble oferece os seguintes métodos de baixo nível para trabalhar com o sistema de arquivos:
Assemble tem suporte de primeira classe para vinil-fs, então qualquer plugin gulp pode ser usado em seu pipeline de montagem.
Crie um fluxo de vinil. Leva padrões glob ou caminhos de arquivo para os arquivos de origem para leitura.
Parâmetros
glob {String|Array} : Padrões Glob ou caminhos de arquivo para arquivos de origem.options {Object} : Opções ou locais para mesclar no contexto e/ou passar para plugins srcExemplo
app . src ( 'src/*.hbs' ) ;
// define `src` options
app . src ( 'src/*.hbs' , { layout : 'default' } ) ; Especifique um destino para arquivos processados.
Parâmetros
dest {String|Function} : Caminho do arquivo ou função de renomeação.options {Object} : Opções e locais para passar para plugins destExemplo
app . dest ( 'dist/' ) ; Copie os arquivos com os patterns glob fornecidos para o dest especificado.
Parâmetros
patterns {String|Array} : padrões globais de arquivos a serem copiados.dest {String|Function} : Diretório de destino.returns {Stream} : Stream, para continuar o processamento, se necessário.Exemplo
app . task ( 'assets' , function ( ) {
// return, to let assemble know when the task has completed
return app . copy ( 'assets/**' , 'dist/' ) ;
} ) ; Renderiza os arquivos à medida que eles são enviados pelo stream.
app . src ( '*.hbs' )
. pipe ( app . renderfile ( ) )
. pipe ( app . dest ( 'foo' ) ) ;Force um mecanismo específico a ser usado para renderizar arquivos:
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 possui os seguintes métodos para executar tarefas e controlar fluxos de trabalho:
Defina uma tarefa a ser executada quando a tarefa for chamada.
Parâmetros
name {String} : nome da tarefafn {Function} : função que é chamada quando a tarefa é executada.Exemplo
app . task ( 'default' , function ( ) {
app . src ( 'templates/*.hbs' )
. pipe ( app . dest ( 'site/' ) ) ;
} ) ; Execute uma ou mais tarefas.
Parâmetros
tasks {Array|String} : Nome da tarefa ou array de nomes de tarefas.cb {Function} : função de retorno de chamada que expõe errExemplo
app . build ( [ 'foo' , 'bar' ] , function ( err ) {
if ( err ) throw err ;
console . log ( 'done!' ) ;
} ) ; Observe arquivos, execute uma ou mais tarefas quando um arquivo monitorado for alterado.
Parâmetros
glob {String|Array} : Caminhos de arquivo ou padrões glob.tasks {Array} : tarefas a serem observadas.Exemplo
app . task ( 'watch' , function ( ) {
app . watch ( 'docs/*.md' , [ 'docs' ] ) ;
} ) ; Plugins de qualquer aplicativo construído na base devem funcionar com Assemble e podem ser usados em seu assemblefile.js :
basepluginassembleplugingenerateplugintemplatespluginupdatepluginverbpluginVisite o guia de documentação de plug-ins para aprender como usar, criar e publicar plug-ins.
Entre em contato!
Tem dúvidas, sugestões ou deseja discutir a montagem? Participe da conversa no gitter ou ligue para nós no Twitter. A equipe de montagem e a comunidade estão sempre felizes em ajudar!
O site está desatualizado e sendo refatorado!
O site da Assemble, assemble.io, contém apenas informações relacionadas ao gulp-assemble. Estamos trabalhando muito para atualizar o site com informações sobre o lançamento mais recente.
Enquanto isso, você pode achar os documentos WIP úteis. Os testes unitários também são ótimos exemplos!
O site da montagem está atualizado?
Não, como mencionado acima, está completamente desatualizado. Se você estiver usando o grunt-assemble, parte da documentação em assemble.io ainda pode ser útil. Se você estiver usando o assemble v0.6.0 e superior, a documentação provavelmente está errada em quase todos os aspectos.
Estamos trabalhando ativamente (diariamente) em uma refatoração e isso é uma prioridade muito alta.
Qual é a diferença entre assemble-core e assemble?
Assemble adiciona uma CLI, algumas coleções de visualizações integradas: pages , layouts e partials , middleware para analisar o front-matter e alguns outros padrões básicos que descobrimos que muitos usuários esperam. Se você preferir padrões diferentes, o assemble-core é um excelente ponto de partida.
Se você deseja algo que lide com modelos, renderização, mecanismos, auxiliares, coleções, etc., mas não precisa executar tarefas ou trabalhar com o sistema de arquivos, considere usar modelos em vez de montar o núcleo.
Eu uso o gulp, por que é recomendado usar o assemble diretamente, em vez de executar o assemble com o gulp?
Você pode executar plug-ins gulp com montagem, mas nem sempre funcionará ao contrário. Isso ocorre porque, como um sistema de construção, o assemble faz coisas que o gulp não faz, como lidar com middleware.
Por exemplo, os métodos .src e .dest do assemble possuem manipuladores de middleware .onStream , .preWrite e .postWrite integrados. Se você ainda deseja usar o gulp e seu ciclo de construção inclui middleware que requer esses manipuladores, você pode usar o plug-in assemble-handle com o gulp para garantir que os manipuladores ainda sejam chamados conforme necessário.
Isso é um longo caminho para dizer que você pode encontrar maneiras de fazer o gulp funcionar, mas estaria apenas adicionando uma dependência extra ao seu projeto para fazer coisas que o assemble já faz.
Qual é a relação entre engolir e montar?
Por favor, leia nosso FAQ do gulp para obter mais informações.
Receba atualizações sobre o desenvolvimento do Assemble e converse com os mantenedores do projeto e membros da comunidade.
Siga @assemblejs no Twitter.
Se você gosta do Assemble e deseja twittar sobre ele, sinta-se à vontade para mencionar @assemblejs ou usar a hashtag #assemble
Leia e assine o Blog Oficial da Assemble.
Junte-se à sala oficial do Slack.
Participe da conversa no Gitter
Conte-nos sobre seu projeto de montagem
Mostre seu amor estrelando Assemble!
Obtenha ajuda de implementação no StackOverflow (use a tag assemble assemble nas perguntas)
Gitter Discuta a montagem conosco no Gitter
Para máxima descoberta, os desenvolvedores de plug-ins devem usar a palavra-chave assembleplugin em pacotes que modificam ou adicionam funcionalidade ao Assemble ao distribuir por meio de npm ou mecanismos de entrega semelhantes.
Contribuindo
Leia nosso guia de contribuição se quiser saber mais sobre como contribuir para este projeto.
Você também pode estar interessado nestes projetos de @doowb e @jonschlinkert:
Se o assemble não fizer o que você precisa, existem alguns outros excelentes projetos de código aberto nos quais você pode estar interessado, criados por nossos amigos no GitHub (em ordem alfabética):
Geradores de sites estáticos
Estruturas de blog
As entradas do changelog são classificadas usando os seguintes rótulos (de keep-a-changelog ):
added : para novos recursoschanged : para alterações na funcionalidade existentedeprecated : para recursos antes estáveis removidos em versões futurasremoved : para recursos obsoletos removidos nesta versãofixed : para qualquer correção de bugRótulos personalizados usados neste changelog:
dependencies : colide com dependênciashousekeeping : reorganização de código, pequenas edições ou outras alterações que não se enquadram em nenhuma das outras categorias. adicionado
fixo
isbinaryfile estava tentando ler um arquivo que não existia. dependências
view seja decorada com .toStream() quando criada pelo app (em vez de uma coleção). dependências
fixo
view.stat fosse nulo em alguns casos após a alteração view.pathview.base nem sempre estava correto em visualizações que não foram criadas no sistema de arquivos dependências
dest dependências
list s Dependências
Dependências
.log() , que também expõe métodos adicionais, como .log.info() , .log.success() , etc.support/docs , para que os documentos markdown possam ser compilados no diretório docsrenameKey do método .data . Use a opção de namespace . Aumenta o assemble-core para v0.22.0 para aproveitar as vantagens das correções e melhorias nos métodos de pesquisa: .find e getView . Nenhuma alteração de API foi feita. Informe-nos se ocorrerem regressões.
List que fazia com que os auxiliares de coleção explodissemapp.getView() e app.find()queue foi removido nas coleções. Consulte assemble-core para obter detalhes adicionais.file.base , fazendo com que o diretório dest fosse relativo ao cwd em vez do glob parent em alguns casos.renameKey nem sempre fosse usado quando definido nas opções do carregador de coleção.debug e código relacionado foram removidosnode_modules e reinstalar todas as dependências para evitar erros como isRegistered is not a function .watch em favor do uso do plugin base-watch.(Changelog gerado pelo helper-changelog)
Solicitações pull e estrelas são sempre bem-vindas. Para bugs e solicitações de recursos, crie um problema.
Leia o guia de contribuição para obter conselhos sobre problemas de abertura, solicitações pull e padrões de codificação.
Se o Assemble não fizer o que você precisa, avise-nos
| Confirmações | Contribuinte |
|---|---|
| 1497 | jonschlinkert |
| 842 | doowb |
| 11 | AndersDJohnson |
| 7 | Arkkimaagi |
| 7 | Stefan Walther |
| 4 | avr |
| 4 | bendrucker |
| 2 | thegreatsunra |
| 2 | rauberdaniel |
| 2 | onokumus |
| 2 | Rob Loach |
| 2 | Steven Black |
| 2 | xzyfer |
| 2 | ain |
| 1 | asans |
| 1 | Bauerca |
| 1 | caseyg1204 |
| 1 | hyzhak |
| 1 | mootari |
| 1 | críticomash |
| 1 | joonasy |
| 1 | Jordanthomas |
| 1 | fraer |
| 1 | defender |
| 1 | pburtchaell |
| 1 | scmorrison |
| 1 | oncletom |
| 1 | tylerhowarth |
| 1 | Klokie |
Jon Schlinkert
Brian Woodward
Direitos autorais © 2017, Jon Schlinkert. MIT
Este arquivo foi gerado por verbo-generate-readme, v0.6.0, em 27 de dezembro de 2017.
