assemble
1.0.0
Auf der Suche nach dem Grunz-Plugin? Bitte besuchen Sie grunt-assemble.
(Beachten Sie, dass die aktuelle Website „assemble.io“ für grunt-assemble gedacht ist. Vielen Dank für Ihre Geduld, während wir daran arbeiten, die Website mit der Dokumentation für die neueste Assemble-Version zu aktualisieren.)
(Klicken Sie auf die folgenden Abschnitte, um sie zu erweitern)
(Inhaltsverzeichnis, generiert durch Verb mit Markdown-Toc)
Assemble ist ein Befehlszeilentool und Entwickler-Framework für Rapid Prototyping, statische Site-Generierung und vieles mehr.
Assemble wird von Tausenden von Entwicklern und Teams in mehr als 170 Ländern verwendet! Hier sind einige Beispiele für Websites, die mit Assemble erstellt wurden:
Ist Ihre Website, Ihr Blog oder Ihr Projekt mit Assemble erstellt? Bitte teilen Sie uns dies mit!
Assemble kann eigenständig verwendet werden, ist jedoch noch leistungsfähiger, wenn es zusammen mit den folgenden Bibliotheken verwendet wird:
Hier sind nur einige der Funktionen, die Assemble bietet:
Fügen Sie devDependencies Ihres Projekts mit npm zusammen:
$ npm install -D assemble Sie sollten jetzt in der Lage sein, Assembler direkt auszuführen (mithilfe von node assemblefile.js usw.) oder mit npm -Skripten. Fügen Sie beispielsweise Folgendes zu package.json hinzu:
{
"scripts" : {
"build" : " assemble "
}
}Dann lauf
$ npm run build Sie können die CLI auch global assemblieren, wodurch der assemble -Befehl zu Ihrem Systempfad hinzugefügt wird, sodass er von jedem Verzeichnis aus ausgeführt werden kann.
$ npm install --global assembleBeachten Sie, dass es sich empfiehlt, Assembler auch bei globaler Installation lokal in jedem Projekt zu installieren, um sicherzustellen, dass Ihre Projekte vor potenziell wichtigen Änderungen geschützt sind, die zwischen Entwicklungszyklen in Assembler auftreten können.
Um die CLI von Assemble verwenden zu können, müssen Sie Ihrem Projekt eine assemblefile.js hinzufügen. Der schnellste Weg, dies zu tun, besteht darin, den folgenden Befehl auszuführen:
$ assemble Wenn im aktuellen Projekt keine assemblefile.js vorhanden ist, werden Sie von Assembler gefragt, ob Sie eine hinzufügen möchten. Wenn Sie mit „Ja“ antworten, generiert Assembler eine grundlegende assembfile.js für Sie.
Führen Sie Assembler über die Befehlszeile aus.
$ assemble < tasks > [options]Geben Sie eine oder mehrere durch Leerzeichen getrennte Aufgaben zur Ausführung an.
Beispiele
Führen Sie die Aufgabe foo aus
$ assemble foo Führen Sie die Aufgaben foo und bar aus
$ assemble foo bar Nicht-Aufgabenoptionen werden mit dem Präfix -- versehen.
Beispiele
Legen Sie --cwd fest, um „assemblefile.js“ in einem anderen Verzeichnis auszuführen:
$ assemble --cwd=docs Geben Sie Ansichten aus, während sie geladen werden, und protokollieren Sie sie in stderr :
$ assemble --emit=viewWeitere [Befehlszeilenoptionen](#Befehlszeilenoptionen) anzeigen
Objektpfade können mithilfe der Punktnotation entweder für den Schlüssel oder den Wert in einem Befehlszeilenargument angegeben werden.
Darüber hinaus verwendet Assembler expand-object (und einige benutzerdefinierte Analysen), um die Übergabe nicht trivialer Optionen und Befehle über die Befehlszeile zu erleichtern. Somit sind alle folgenden Formate möglich.
Beispiele
Boolesche Werte:
$ assemble --foo
# { foo: true }Schlüssel-Wert-Paare:
$ assemble --foo=bar
# { foo: 'bar' }Verschachtelte boolesche Werte:
$ assemble --option=foo
# {options: { foo: true }}Verschachtelte Schlüssel-Wert-Paare:
$ assemble --option=foo:bar
# {options: { foo: 'bar' }}Tief verschachtelte Schlüssel-Wert-Paare:
$ assemble --option=foo.bar.baz:qux
# {options: foo: { bar: { baz: 'qux' }}}} Oder auf der linken Seite von = :
$ assemble --option.foo.bar.baz=qux
# {options: foo: { bar: { baz: 'qux' }}}} Ändern Sie den cwd für die auszuführende assemblefile.js und geben Sie optional die auszuführenden Aufgaben an:
$ assemble < tasks > --cwd [directory]Beispiel
Um das scaffolds -Beispiel im Verzeichnis examples/ auszuführen, geben Sie Folgendes ein:
$ assemble --cwd examples/scaffoldsBei Erfolg sollte in der Befehlszeile etwa Folgendes angezeigt werden:
Geben Sie den Namen der Konfigurationsdatei an, damit die CLI von Assembler ausgeführt werden soll. Der Standardwert ist assemblefile.js .
Beispiel
$ assemble --file assemblefile.dev.js Erstellen Sie eine assemble App. Dies ist die Hauptfunktion, die vom Assemble-Modul exportiert wird.
Parameter
options {Objekt} : Übergeben Sie optional Standardoptionen zur Verwendung.Beispiel
var assemble = require ( 'assemble' ) ;
var app = assemble ( ) ;Assemble stellt die gesamte API der Vorlagenbibliothek für die Arbeit mit Vorlagen und Vorlagensammlungen bereit. Die API ist viel umfangreicher als das, was hier dokumentiert ist. Weitere Dokumentation finden Sie in den Vorlagen.
Vorlagen und Ansichten
In der folgenden Dokumentation beziehen sich die Begriffe „Vorlage“ und „Ansicht“ beide auf Aspekte derselben Sache. Das bedeuten sie:
template : eine tatsächliche Vorlagenzeichenfolgeview : ein Objekt mit einer content , die die Vorlagenzeichenfolge enthält. Da Ansichten Instanzen von Vinyl sind, können Sie sich eine Ansicht als „Vinyldatei für Vorlagen“ vorstellen. Erstellen Sie eine Vorlagensammlung zum Zwischenspeichern von Ansichten:
app . create ( 'includes' , { viewType : 'partial' } ) ;Optionen
cwd {String} : das Basisverzeichnis, das beim Laden von Vorlagen aus einem Glob in die Sammlung verwendet werden soll
viewType : {String|Array} : Ein oder mehrere Ansichtstypen, die der Sammlung zugeordnet werden sollen
Ansichten hinzufügen
Fügen Sie der Sammlung eine Ansicht hinzu:
app . include ( 'foo.md' , { contents : new Buffer ( 'this is contents' ) } ) ;Mehrere Ansichten hinzufügen:
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' } ) ; Ansichtstypen werden für eine Sammlung definiert, um zu bestimmen, wie Vorlagen in der Sammlung während des [Renderzyklus][] behandelt werden.
Verfügbare Typen
Assemble unterstützt drei Ansichtstypen:
partial : Ansichten dieses Typs können als „Teilansichten“ (oder „Teilansichten“) verwendet werden, die in andere Ansichten eingefügt werden können. Nützlich für Komponenten, Dokumentfragmente oder andere wiederverwendbare Code- oder Inhaltsausschnitte. Diese Ansichten werden an Rendering-Engines übergeben, um sie als Teilansichten oder als Variablen im Kontext zu verwenden, wenn Teilansichten nicht direkt unterstützt werden.layout : Ermöglicht Ansichten, andere Ansichten (jeglichen Typs, einschließlich anderer Layouts oder Teilansichten) mit gemeinsamem Code oder Inhalt zu „umschließen“.renderable : Ansichten, die eine Eins-zu-eins-Beziehung zu gerenderten Dateien haben, die schließlich für einen Benutzer oder Besucher einer Website sichtbar sind. Zum Beispiel: Seiten oder Blogbeiträge. Der renderable Ansichtstyp wird automatisch festgelegt, wenn keine anderen Ansichtstypen festgelegt sind.Ansichtstypen definieren
Sie können Ansichtstypen definieren, wenn eine Sammlung erstellt wird:
app . create ( 'snippet' , { viewType : 'partial' } ) ;Oder direkt zu den Abholmöglichkeiten:
app . create ( 'snippet' ) ;
app . snippets . option ( 'viewType' , [ 'partial' ] ) ; // string or array Registrieren Sie die Template-Engine zum Rendern von Ansichten mit der angegebenen ext :
app . engine ( ext , fn ) ;Parameter
ext {String} : Die Dateierweiterung der Dateien, die mit der Engine gerendert werden sollenfn {Funktion} : Asynchrone Funktion, die den Konsolidierungs-Engine-Konventionen folgt und drei Argumente akzeptiert: str , locals und callback .Beispiel
// 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 ) ;
} ) ; Sie können Assembler anweisen, für alle Dateierweiterungen dieselbe Engine zu verwenden, indem Sie einen Wert für options.engine festlegen.
Beispiel
// use engine `hbs` for rendering all files
app . option ( 'engine' , 'hbs' ) ;Oder wenn Sie .renderFile verwenden, können Sie die Verwendung einer bestimmten Engine erzwingen, indem Sie den Engine-Namen übergeben.
Beispiel
Verwenden Sie die hbs -Engine, um alle Vorlagen zu rendern:
app . src ( 'templates/*.*' )
. pipe ( app . renderFile ( 'hbs' ) ) Rendern Sie eine Ansicht mit den angegebenen locals und callback .
app . render ( view , { title : 'Foo' } , function ( err , view ) {
// `view` is an object with a rendered `content` property
} ) ;Parameter
view {Object|String} : Die zu rendernde Ansichtlocals {Object} : Locals, die an die Template-Engine übergeben werden, um Vorlagen in view darzustellencallback {Funktion}Assemble bietet die folgenden Low-Level-Methoden für die Arbeit mit dem Dateisystem:
Assemble bietet erstklassige Unterstützung für Vinyl-FS, sodass jedes Gulp-Plugin in Ihrer Assemble-Pipeline verwendet werden kann.
Erstellen Sie einen Vinyl-Stream. Übernimmt Glob-Muster oder Dateipfade zum Lesen der Quelldateien.
Parameter
glob {String|Array} : Glob-Muster oder Dateipfade zu Quelldateien.options {Object} : Optionen oder Locals zum Zusammenführen in den Kontext und/oder zur Übergabe an src -PluginsBeispiel
app . src ( 'src/*.hbs' ) ;
// define `src` options
app . src ( 'src/*.hbs' , { layout : 'default' } ) ; Geben Sie ein Ziel für verarbeitete Dateien an.
Parameter
dest {String|Function} : Dateipfad oder Umbenennungsfunktion.options {Object} : Optionen und Locals, die an dest -Plugins übergeben werden sollenBeispiel
app . dest ( 'dist/' ) ; Kopieren Sie Dateien mit den angegebenen Glob- patterns an das angegebene dest .
Parameter
patterns {String|Array} : Glob-Muster der zu kopierenden Dateien.dest {String|Function} : Zielverzeichnis.returns : Stream, um die Verarbeitung bei Bedarf fortzusetzen.Beispiel
app . task ( 'assets' , function ( ) {
// return, to let assemble know when the task has completed
return app . copy ( 'assets/**' , 'dist/' ) ;
} ) ; Rendert Dateien, während sie durch den Stream übertragen werden.
app . src ( '*.hbs' )
. pipe ( app . renderfile ( ) )
. pipe ( app . dest ( 'foo' ) ) ;Erzwingen Sie die Verwendung einer bestimmten Engine zum Rendern von Dateien:
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 verfügt über die folgenden Methoden zum Ausführen von Aufgaben und Steuern von Arbeitsabläufen:
Definieren Sie eine Aufgabe, die ausgeführt werden soll, wenn die Aufgabe aufgerufen wird.
Parameter
name {String} : Aufgabennamefn {Funktion} : Funktion, die aufgerufen wird, wenn die Aufgabe ausgeführt wird.Beispiel
app . task ( 'default' , function ( ) {
app . src ( 'templates/*.hbs' )
. pipe ( app . dest ( 'site/' ) ) ;
} ) ; Führen Sie eine oder mehrere Aufgaben aus.
Parameter
tasks {Array|String} : Aufgabenname oder Array von Aufgabennamen.cb {Funktion} : Rückruffunktion, die err offenlegtBeispiel
app . build ( [ 'foo' , 'bar' ] , function ( err ) {
if ( err ) throw err ;
console . log ( 'done!' ) ;
} ) ; Überwachen Sie Dateien und führen Sie eine oder mehrere Aufgaben aus, wenn sich eine überwachte Datei ändert.
Parameter
glob {String|Array} : Dateipfade oder Glob-Muster.tasks {Array} : Zu beobachtende Aufgabe(n).Beispiel
app . task ( 'watch' , function ( ) {
app . watch ( 'docs/*.md' , [ 'docs' ] ) ;
} ) ; Plugins aus allen auf Basis erstellten Anwendungen sollten mit Assemble funktionieren und können in Ihrer assemblefile.js verwendet werden:
basepluginassembleplugingenerateplugintemplatespluginupdatepluginverbpluginBesuchen Sie den Plugin-Dokumentationsleitfaden, um zu erfahren, wie Sie Plugins verwenden, erstellen und veröffentlichen.
Nehmen Sie Kontakt auf!
Haben Sie Fragen, Anregungen oder möchten Sie den Zusammenbau besprechen? Nehmen Sie an der Diskussion auf Gitter teil oder rufen Sie uns auf Twitter an. Das Assemble-Team und die Community helfen immer gerne weiter!
Die Website ist veraltet und wird überarbeitet!
Die Website von Assemble, assemble.io, enthält nur Informationen zu gulp-assemble. Wir arbeiten hart daran, die Website mit Informationen zur neuesten Version zu aktualisieren.
In der Zwischenzeit könnten die WIP-Dokumente für Sie hilfreich sein. Auch die Unit-Tests sind tolle Beispiele!
Ist die Assemble-Website aktuell?
Nein, wie oben erwähnt, ist es völlig veraltet. Wenn Sie grunt-assemble verwenden, könnten einige der Dokumentationen unterassemble.io dennoch nützlich sein. Wenn Sie Assembler v0.6.0 und höher verwenden, ist die Dokumentation wahrscheinlich in fast jeder Hinsicht falsch.
Wir arbeiten aktiv (täglich) an einem Refactoring und es hat sehr hohe Priorität.
Was ist der Unterschied zwischen Assemble-Core und Assemble?
Assemble fügt eine CLI, einige integrierte Ansichtssammlungen hinzu: pages , layouts “ und partials , Middleware zum Parsen von Frontmater und einige andere grundlegende Standardeinstellungen, die unserer Meinung nach viele Benutzer erwarten. Wenn Sie andere Standardeinstellungen bevorzugen, ist assemble-core ein guter Ausgangspunkt.
Wenn Sie etwas möchten, das Vorlagen, Rendering, Engines, Helfer, Sammlungen usw. verwaltet, Sie aber keine Aufgaben ausführen oder mit dem Dateisystem arbeiten müssen, sollten Sie die Verwendung von Vorlagen anstelle von Assemble-Core in Betracht ziehen.
Ich verwende gulp. Warum wird empfohlen, assemble direkt zu verwenden, anstatt assemble mit gulp auszuführen?
Sie können Gulp-Plugins mit Assemble ausführen, aber umgekehrt funktioniert es nicht immer. Dies liegt daran, dass Assemble als Build-System Dinge tut, die Gulp nicht kann, wie z. B. die Handhabung von Middleware.
Beispielsweise verfügen die Methoden .src und .dest von Assembler über integrierte Middleware-Handler .onStream , .preWrite und .postWrite . Wenn Sie gulp weiterhin verwenden möchten und Ihr Build-Zyklus Middleware enthält, die diese Handler erfordert, können Sie das Assemble-Handle-Plugin mit gulp verwenden, um sicherzustellen, dass die Handler weiterhin nach Bedarf aufgerufen werden.
Das ist ein langer Weg zu sagen: Sie können Möglichkeiten finden, Gulp zum Laufen zu bringen, aber Sie würden Ihrem Projekt nur eine zusätzliche Abhängigkeit hinzufügen, um Dinge zu tun, die Assembler bereits tut.
Welche Beziehung besteht zwischen Schlucken und Zusammenbauen?
Weitere Informationen finden Sie in unseren Gulp-FAQ.
Erhalten Sie Updates zur Entwicklung von Assemble und chatten Sie mit den Projektbetreuern und Community-Mitgliedern.
Folgen Sie @assemblejs auf Twitter.
Wenn Ihnen Assemble gefällt und Sie darüber twittern möchten, können Sie gerne @assemblejs erwähnen oder den Hashtag #assemble verwenden
Lesen und abonnieren Sie den offiziellen Assemble-Blog.
Treten Sie dem offiziellen Slack-Raum bei.
Beteiligen Sie sich an der Diskussion auf Gitter
Erzählen Sie uns von Ihrem Montageprojekt
Zeigen Sie Ihre Liebe, indem Sie Assemble in der Hauptrolle spielen!
Holen Sie sich Hilfe bei der Implementierung von StackOverflow (bitte verwenden Sie bei Fragen das Assemble- assemble Tag)
Gitter Besprechen Sie Assemble mit uns auf Gitter
Für maximale Auffindbarkeit sollten Plugin-Entwickler das Schlüsselwort assembleplugin für Pakete verwenden, die die Funktionalität von Assemble ändern oder erweitern, wenn sie über npm oder ähnliche Bereitstellungsmechanismen verteilt werden.
Mitwirken
Bitte lesen Sie unseren Beitragsleitfaden, wenn Sie mehr darüber erfahren möchten, wie Sie zu diesem Projekt beitragen können.
Diese Projekte von @doowb und @jonschlinkert könnten Sie auch interessieren:
Wenn Assemble nicht das tut, was Sie brauchen, gibt es einige andere großartige Open-Source-Projekte, die Sie interessieren könnten und die von unseren Freunden auf GitHub erstellt wurden (in alphabetischer Reihenfolge):
Statische Site-Generatoren
Blog-Frameworks
Changelog-Einträge werden anhand der folgenden Labels (von keep-a-changelog ) klassifiziert:
added : für neue Funktionenchanged : für Änderungen an der vorhandenen Funktionalitätdeprecated : ausnahmsweise stabile Funktionen, die in kommenden Versionen entfernt werdenremoved : für veraltete Funktionen, die in dieser Version entfernt wurdenfixed : für etwaige FehlerbehebungenBenutzerdefinierte Beschriftungen, die in diesem Änderungsprotokoll verwendet werden:
dependencies : Erhöht Abhängigkeitenhousekeeping : Neuorganisation des Codes, kleinere Änderungen oder andere Änderungen, die nicht in eine der anderen Kategorien passen. hinzugefügt
behoben
isbinaryfile versuchte, aus einer Datei zu lesen, die nicht existierte. Abhängigkeiten
view mit .toStream() dekoriert wird, wenn sie von app erstellt wird (im Gegensatz zu einer Sammlung). Abhängigkeiten
behoben
view.stat in einigen Fällen nach der Änderung von view.path null warview.base war bei Ansichten, die nicht aus dem Dateisystem erstellt wurden, nicht immer korrekt Abhängigkeiten
dest -Verarbeitung zu profitieren Abhängigkeiten
list verfügbar sind Abhängigkeiten
Abhängigkeiten
.log() -Methode, die auch zusätzliche Methoden wie .log.info() , .log.success() usw. verfügbar macht.support/docs verschoben, sodass Markdown-Dokumente im docs -Verzeichnis erstellt werden könnenrenameKey aus der .data -Methode entfernt wird. Verwenden Sie stattdessen die namespace -Option. Bringt assemble-core auf v0.22.0, um Korrekturen und Verbesserungen an den Suchmethoden zu nutzen: .find und getView . Es wurden keine API-Änderungen vorgenommen. Bitte teilen Sie uns mit, wenn es zu Regressionen kommt.
List , der dazu führte, dass Sammlungshelfer explodiertenapp.getView() und app.find()queue wurde für Sammlungen entfernt. Weitere Details finden Sie unter assemble-core.file.base verwendet wurde, was dazu führte, dass das Zielverzeichnis in einigen Fällen relativ zu cwd und nicht zum Glob-Parent war.renameKey nicht immer verwendet wurde, wenn es in den Optionen des Collection-Loaders definiert wurde.debug Methoden und zugehöriger Code wurden entferntnode_modules vollständig entfernen und alle Abhängigkeiten neu installieren, um Fehler wie isRegistered is not a function zu vermeiden .watch Methode zugunsten der Verwendung des Base-Watch-Plugins entfernt wird.(Von helper-changelog generiertes Änderungsprotokoll)
Pull-Requests und Stars sind jederzeit willkommen. Bei Fehlern und Funktionswünschen erstellen Sie bitte ein Problem.
Bitte lesen Sie den Beitragsleitfaden, um Ratschläge zum Öffnen von Issues, Pull Requests und Codierungsstandards zu erhalten.
Wenn Assemble nicht das tut, was Sie benötigen, teilen Sie uns dies bitte mit
| Commits | Mitwirkender |
|---|---|
| 1497 | Jonschlinkert |
| 842 | doowb |
| 11 | AndersDJohnson |
| 7 | Arkkimaagi |
| 7 | stefanwalther |
| 4 | Avr |
| 4 | bendrucker |
| 2 | thegreatsunra |
| 2 | rauberdaniel |
| 2 | Onokumus |
| 2 | RobLoach |
| 2 | StevenBlack |
| 2 | xzyfer |
| 2 | ain |
| 1 | asans |
| 1 | bauerca |
| 1 | caseyg1204 |
| 1 | Hyzhak |
| 1 | mootari |
| 1 | Criticalmash |
| 1 | Joonasy |
| 1 | Jordanthomas |
| 1 | Ausfranser |
| 1 | Verteidiger |
| 1 | pburtchaell |
| 1 | scmorrison |
| 1 | oncletom |
| 1 | TylerHowarth |
| 1 | Klokie |
Jon Schlinkert
Brian Woodward
Urheberrecht © 2017, Jon Schlinkert. MIT
Diese Datei wurde am 27. Dezember 2017 von verb-generate-readme, v0.6.0, generiert.
