assemble
1.0.0
Vous recherchez le plugin Grunt ? Veuillez visiter grunt-assemble.
(Notez que le site Web actuel assemble.io est destiné à grunt-assemble. Merci de votre patience pendant que nous travaillons à la mise à jour du site avec la documentation du dernier assemble) .
(Cliquez sur les sections suivantes pour les développer)
(TOC générée par le verbe en utilisant markdown-toc)
Assemble est un outil de ligne de commande et un framework de développement pour le prototypage rapide, la génération de sites statiques et bien plus encore.
Assemble est utilisé par des milliers de développeurs et d'équipes dans plus de 170 pays ! Voici quelques exemples de sites construits avec assemble :
Votre site Web, votre blog ou votre projet est-il construit avec Assemble ? S'il vous plaît laissez-nous savoir!
Assemble peut être utilisé de manière autonome, mais il est encore plus puissant lorsqu'il est utilisé avec les bibliothèques suivantes :
Voici quelques-unes des fonctionnalités proposées par Assemble :
Ajoutez assembler devDependencies de votre projet à l’aide de npm :
$ npm install -D assemble Vous devriez maintenant pouvoir exécuter assemble directement (en utilisant node assemblefile.js , etc.) ou en utilisant des scripts npm . Par exemple, ajoutez ce qui suit à package.json :
{
"scripts" : {
"build" : " assemble "
}
}Puis cours
$ npm run build Vous pouvez également utiliser la CLI d'assembly globalement, qui ajoute la commande assemble à votre chemin système, lui permettant ainsi d'être exécutée à partir de n'importe quel répertoire.
$ npm install --global assembleNotez que même si assemble est installé globalement, il est recommandé de l'installer localement dans chaque projet pour garantir que vos projets sont protégés contre toute modification potentiellement brutale qui pourrait survenir dans assemble entre les cycles de développement.
Pour utiliser la CLI d'assemble, vous devrez ajouter un assemblefile.js à votre projet. Le moyen le plus rapide de procéder consiste à exécuter la commande suivante :
$ assemble Si aucun assemblefile.js n'existe dans le projet en cours, assemble vous demandera si vous souhaitez en ajouter un. Si vous répondez oui, assemble générera alors un assembfile.js de base pour vous.
Exécutez assemble à partir de la ligne de commande.
$ assemble < tasks > [options]Spécifiez une ou plusieurs tâches séparées par des espaces à exécuter.
Exemples
Exécuter la tâche foo
$ assemble foo Exécuter les tâches foo et bar
$ assemble foo bar Les options hors tâche sont préfixées par -- .
Exemples
Définissez --cwd pour exécuter un assemblefile.js dans un répertoire différent :
$ assemble --cwd=docs Émettez des vues au fur et à mesure de leur chargement et enregistrez-les dans stderr :
$ assemble --emit=viewVoir plus [options de ligne de commande](#options de ligne de commande)
Les chemins d'objet peuvent être spécifiés en utilisant la notation par points pour la clé ou la valeur dans un argument de ligne de commande.
De plus, assemble utilise un objet expand (et une analyse personnalisée) pour faciliter la transmission d'options et de commandes non triviales via la ligne de commande. Tous les formats suivants sont donc possibles.
Exemples
Valeurs booléennes :
$ assemble --foo
# { foo: true }Paires clé-valeur :
$ assemble --foo=bar
# { foo: 'bar' }Booléens imbriqués :
$ assemble --option=foo
# {options: { foo: true }}Paires clé-valeur imbriquées :
$ assemble --option=foo:bar
# {options: { foo: 'bar' }}Paires clé-valeur profondément imbriquées :
$ assemble --option=foo.bar.baz:qux
# {options: foo: { bar: { baz: 'qux' }}}} Ou sur le côté gauche du = :
$ assemble --option.foo.bar.baz=qux
# {options: foo: { bar: { baz: 'qux' }}}} Modifiez le cwd pour que assemblefile.js s'exécute, en spécifiant éventuellement les tâches à exécuter :
$ assemble < tasks > --cwd [directory]Exemple
Pour exécuter l'exemple scaffolds dans le répertoire examples/ , vous devez saisir :
$ assemble --cwd examples/scaffoldsEn cas de succès, sur la ligne de commande, vous devriez voir quelque chose comme ceci :
Spécifiez le nom du fichier de configuration à exécuter par la CLI d'assembly, la valeur par défaut est assemblefile.js .
Exemple
$ assemble --file assemblefile.dev.js Créez une application assemble . C'est la fonction principale exportée par le module assemble.
Paramètres
options {Object} : transmettez éventuellement les options par défaut à utiliser.Exemple
var assemble = require ( 'assemble' ) ;
var app = assemble ( ) ;Assemble expose l'intégralité de l'API de la bibliothèque de modèles pour travailler avec des modèles et des collections de modèles. L'API est beaucoup plus étendue que ce qui est documenté ici, voir les modèles pour plus de documentation.
Modèles et vues
Dans la documentation suivante, les termes « modèle » et « vue » font tous deux référence à des aspects de la même chose. Voici ce qu'ils signifient :
template : une véritable chaîne de modèleview : un objet avec une propriété content qui contient la chaîne du modèle. Puisque les vues sont des instances de vinyle, vous pouvez considérer une vue comme un « fichier vinyle pour modèles ». Créez une collection de modèles pour mettre les vues en cache :
app . create ( 'includes' , { viewType : 'partial' } ) ;Possibilités
cwd {String} : le répertoire de base à utiliser lors du chargement de modèles sur la collection à partir d'un glob
viewType : {String|Array} : Un ou plusieurs types de vues à associer à la collection
Ajouter des vues
Ajoutez une vue à la collection :
app . include ( 'foo.md' , { contents : new Buffer ( 'this is contents' ) } ) ;Ajoutez plusieurs vues :
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' } ) ; Les types de vues sont définis sur une collection pour déterminer comment les modèles de la collection seront gérés tout au long du [cycle de rendu][].
Types disponibles
Assemble prend en charge trois types de vues :
partial : les vues de ce type peuvent être utilisées comme "partielles" (ou "vues partielles"), qui peuvent être injectées dans d'autres vues. Utile pour les composants, les fragments de documents ou d’autres extraits de code ou de contenu réutilisables. Ces vues sont transmises aux moteurs de rendu pour être utilisées comme partielles ou comme variables sur le contexte si les partielles ne sont pas directement prises en charge.layout : permet aux vues de "envelopper" d'autres vues (de tout type, y compris d'autres mises en page ou partielles) avec du code ou du contenu commun.renderable : vues qui ont une relation individuelle avec les fichiers rendus qui seront éventuellement visibles par un utilisateur ou un visiteur d'un site Web. Par exemple : des pages ou des articles de blog. Le type de vue renderable est automatiquement défini si aucun autre type de vue n'est défini.Définir des types de vues
Vous pouvez définir des types de vues lors de la création d'une collection :
app . create ( 'snippet' , { viewType : 'partial' } ) ;Ou directement sur les options de collecte :
app . create ( 'snippet' ) ;
app . snippets . option ( 'viewType' , [ 'partial' ] ) ; // string or array Enregistrez le moteur de modèle pour le rendu des vues avec l' ext donnée :
app . engine ( ext , fn ) ;Paramètres
ext {String} : L'extension des fichiers à restituer avec le moteurfn {Function} : fonction asynchrone qui suit les conventions du moteur de consolidation et prend trois arguments : str , locals et callback .Exemple
// 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 ) ;
} ) ; Vous pouvez demander à assemble d'utiliser le même moteur pour toutes les extensions de fichiers en définissant une valeur sur options.engine .
Exemple
// use engine `hbs` for rendering all files
app . option ( 'engine' , 'hbs' ) ;Ou, si vous utilisez .renderFile, vous pouvez forcer l'utilisation d'un moteur spécifique en transmettant le nom du moteur.
Exemple
Utilisez le moteur hbs pour afficher tous les modèles :
app . src ( 'templates/*.*' )
. pipe ( app . renderFile ( 'hbs' ) ) Afficher une vue avec les locals et callback donnés.
app . render ( view , { title : 'Foo' } , function ( err , view ) {
// `view` is an object with a rendered `content` property
} ) ;Paramètres
view {Object|String} : La vue à restituerlocals {Object} : Locals à transmettre au moteur de modèles pour le rendu des modèles en viewcallback {Fonction}Assemble propose les méthodes de bas niveau suivantes pour travailler avec le système de fichiers :
Assemble a un support de première classe pour vinyl-fs, donc n'importe quel plugin gulp peut être utilisé dans votre pipeline d'assemblage.
Créez un flux de vinyle. Prend des modèles globaux ou des chemins de fichiers vers les fichiers source à lire.
Paramètres
glob {String|Array} : modèles Glob ou chemins de fichiers vers les fichiers sources.options {Object} : Options ou locales à fusionner dans le contexte et/ou passer aux plugins srcExemple
app . src ( 'src/*.hbs' ) ;
// define `src` options
app . src ( 'src/*.hbs' , { layout : 'default' } ) ; Spécifiez une destination pour les fichiers traités.
Paramètres
dest {String|Function} : Chemin du fichier ou fonction de renommage.options {Object} : Options et locales à transmettre aux plugins destExemple
app . dest ( 'dist/' ) ; Copiez les fichiers avec les patterns globaux donnés vers le dest spécifié.
Paramètres
patterns {String|Array} : Modèles Glob des fichiers à copier.dest {String|Function} : Répertoire de destination.returns {Stream} : Stream, pour poursuivre le traitement si nécessaire.Exemple
app . task ( 'assets' , function ( ) {
// return, to let assemble know when the task has completed
return app . copy ( 'assets/**' , 'dist/' ) ;
} ) ; Restitue les fichiers au fur et à mesure qu'ils sont transmis dans le flux.
app . src ( '*.hbs' )
. pipe ( app . renderfile ( ) )
. pipe ( app . dest ( 'foo' ) ) ;Forcer l'utilisation d'un moteur spécifique pour le rendu des fichiers :
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 dispose des méthodes suivantes pour exécuter des tâches et contrôler les flux de travail :
Définissez une tâche à exécuter lorsque la tâche est appelée.
Paramètres
name {String} : Nom de la tâchefn {Fonction} : fonction appelée lors de l'exécution de la tâche.Exemple
app . task ( 'default' , function ( ) {
app . src ( 'templates/*.hbs' )
. pipe ( app . dest ( 'site/' ) ) ;
} ) ; Exécutez une ou plusieurs tâches.
Paramètres
tasks {Array|String} : Nom de la tâche ou tableau de noms de tâches.cb {Function} : fonction de rappel qui expose errExemple
app . build ( [ 'foo' , 'bar' ] , function ( err ) {
if ( err ) throw err ;
console . log ( 'done!' ) ;
} ) ; Surveillez les fichiers, exécutez une ou plusieurs tâches lorsqu'un fichier surveillé change.
Paramètres
glob {String|Array} : chemins de fichiers ou modèles globaux.tasks {Array} : Tâche(s) à surveiller.Exemple
app . task ( 'watch' , function ( ) {
app . watch ( 'docs/*.md' , [ 'docs' ] ) ;
} ) ; Les plugins de toutes les applications construites sur la base devraient fonctionner avec Assemble et peuvent être utilisés dans votre assemblefile.js :
basepluginassembleplugingenerateplugintemplatespluginupdatepluginverbpluginConsultez le guide de documentation des plugins pour savoir comment utiliser, créer et publier des plugins.
Entrer en contact!
Vous avez des questions, des suggestions ou souhaitez discuter du montage ? Rejoignez la conversation sur gitter ou contactez-nous sur Twitter. L'équipe Assemble et la communauté sont toujours heureuses de vous aider !
Le site Web est obsolète et est en cours de refonte !
Le site Web d'Assemble, assemble.io, ne contient que des informations relatives à gulp-assemble. Nous travaillons dur pour mettre à jour le site avec des informations sur la dernière version.
En attendant, les documents WIP pourraient vous être utiles. Les tests unitaires sont également d’excellents exemples !
Le site Web d'assemble est-il à jour ?
Non, comme mentionné ci-dessus, c'est complètement obsolète. Si vous utilisez grunt-assemble, une partie de la documentation sur assemble.io peut encore être utile. Si vous utilisez assemble v0.6.0 et versions ultérieures, la documentation est probablement fausse à presque tous les égards.
Nous travaillons activement (quotidiennement) sur un refactor et c'est une très haute priorité.
Quelle est la différence entre assembler-core et assembler ?
Assemble ajoute une CLI, quelques collections de vues intégrées : pages , layouts et partials , un middleware pour l'analyse des éléments préliminaires et quelques autres valeurs par défaut de base auxquelles de nombreux utilisateurs s'attendent. Si vous préférez des valeurs par défaut différentes, assemble-core est un excellent point de départ.
Si vous voulez quelque chose qui gère les modèles, le rendu, les moteurs, les assistants, les collections, etc. mais que vous n'avez pas besoin d'exécuter des tâches ou de travailler avec le système de fichiers, envisagez d'utiliser des modèles au lieu d'assembler-core.
J'utilise gulp, pourquoi est-il recommandé d'utiliser assemble directement, au lieu d'exécuter assemble avec gulp ?
Vous pouvez exécuter des plugins gulp avec assemble, mais cela ne fonctionnera pas toujours dans l'autre sens. En effet, en tant que système de build, assemble fait des choses que gulp ne fait pas, comme gérer le middleware.
Par exemple, les méthodes .src et .dest d'assembly ont des gestionnaires middleware .onStream , .preWrite et .postWrite intégrés. Si vous souhaitez toujours utiliser gulp et que votre cycle de construction inclut un middleware qui nécessite ces gestionnaires, vous pouvez utiliser le plugin assemble-handle avec gulp pour vous assurer que les gestionnaires sont toujours appelés selon les besoins.
C'est une longue façon de dire que vous pouvez trouver des moyens de faire fonctionner gulp, mais vous ajouteriez simplement une dépendance supplémentaire à votre projet pour faire des choses que assemble fait déjà.
Quelle est la relation entre avaler et assembler ?
Veuillez lire notre FAQ gulp pour plus d'informations.
Obtenez des mises à jour sur le développement d'Assemble et discutez avec les responsables du projet et les membres de la communauté.
Suivez @assemblejs sur Twitter.
Si vous aimez Assemble et souhaitez tweeter à ce sujet, n'hésitez pas à mentionner @assemblejs ou à utiliser le hashtag #assemble
Lisez et abonnez-vous au blog officiel d'Assemble.
Rejoignez la salle Slack officielle.
Rejoignez la conversation sur Gitter
Parlez-nous de votre projet d'assemblage
Montrez votre amour en mettant en vedette Assemble !
Obtenez de l'aide pour la mise en œuvre sur StackOverflow (veuillez utiliser la balise assemble assemble dans les questions)
Gitter Discutez de Assemblez-vous avec nous sur Gitter
Pour une visibilité maximale, les développeurs de plugins doivent utiliser le mot-clé assembleplugin sur les packages qui modifient ou ajoutent des fonctionnalités d'Assemble lors de la distribution via npm ou des mécanismes de livraison similaires.
Contribuer
Veuillez lire notre guide de contribution si vous souhaitez en savoir plus sur la contribution à ce projet.
Vous pourriez également être intéressé par ces projets de @doowb et @jonschlinkert :
Si assemble ne fait pas ce dont vous avez besoin, il existe d'autres excellents projets open source qui pourraient vous intéresser, créés par nos amis sur GitHub (par ordre alphabétique) :
Générateurs de sites statiques
Cadres de blog
Les entrées du journal des modifications sont classées à l'aide des étiquettes suivantes (de keep-a-changelog ) :
added : pour les nouvelles fonctionnalitéschanged : pour les modifications des fonctionnalités existantesdeprecated : pour les fonctionnalités une fois stables supprimées dans les versions à venirremoved : pour les fonctionnalités obsolètes supprimées dans cette versionfixed : pour toute correction de bugÉtiquettes personnalisées utilisées dans ce journal des modifications :
dependencies : bumps dépendanceshousekeeping : réorganisation du code, modifications mineures ou autres modifications qui ne rentrent dans aucune des autres catégories. ajouté
fixé
isbinaryfile essayait de lire à partir d'un fichier qui n'existait pas. dépendances
view est décorée avec .toStream() lorsqu'elle est créée par app (par rapport à une collection). dépendances
fixé
view.stat dans certains cas après la modification view.pathview.base n'était pas toujours correct sur les vues qui n'étaient pas créées à partir du système de fichiers dépendances
dest dépendances
list s Dépendances
Dépendances
.log() , qui expose également des méthodes supplémentaires, comme .log.info() , .log.success() , etc.support/docs , afin que les documents markdown puissent être créés dans le répertoire docsrenameKey de la méthode .data . Utilisez plutôt l’option namespace . Passe assemble-core à la v0.22.0 pour profiter des correctifs et des améliorations des méthodes de recherche : .find et getView . Aucune modification de l'API n'a été apportée. Veuillez nous faire savoir si des régressions se produisent.
List qui faisait exploser les aides à la collecteapp.getView() et app.find()queue a été supprimée sur les collections. Voir assemble-core pour plus de détails.file.base , ce qui faisait que le répertoire dest était relatif à cwd au lieu du parent glob dans certains cas.renameKey de toujours être utilisé lorsqu'il était défini dans les options du chargeur de collection.debug et le code associé ont été supprimésnode_modules et de réinstaller toutes les dépendances pour éviter des erreurs telles que isRegistered is not a function .watch au profit de l'utilisation du plugin base-watch.(Journal des modifications généré par helper-changelog)
Les demandes de tirage et les étoiles sont toujours les bienvenues. Pour les bogues et les demandes de fonctionnalités, veuillez créer un problème.
Veuillez lire le guide de contribution pour obtenir des conseils sur l'ouverture des problèmes, les demandes d'extraction et les normes de codage.
Si Assemble ne fait pas ce dont vous avez besoin, veuillez nous le faire savoir
| S'engage | Donateur |
|---|---|
| 1497 | Jonschlinkert |
| 842 | doowb |
| 11 | AndersDJohnson |
| 7 | Arkkimaagi |
| 7 | stefanwalther |
| 4 | avril |
| 4 | Bendrucker |
| 2 | le grand soleil |
| 2 | rauberdaniel |
| 2 | onokumus |
| 2 | RobLoach |
| 2 | StevenNoir |
| 2 | xzyfer |
| 2 | aïn |
| 1 | asans |
| 1 | Bauerca |
| 1 | caseyg1204 |
| 1 | hyzhak |
| 1 | Mootari |
| 1 | critique |
| 1 | joonasy |
| 1 | jordanthomas |
| 1 | effiloché |
| 1 | défenseur |
| 1 | pburtchaell |
| 1 | scmorrison |
| 1 | oncletom |
| 1 | TylerHowarth |
| 1 | klokie |
Jon Schlinkert
Brian Woodward
Copyright © 2017, Jon Schlinkert. MIT
Ce fichier a été généré par verb-generate-readme, v0.6.0, le 27 décembre 2017.
