Transform source patterns and pages into static HTML output.
$ npm install --save drizzle-builder
import drizzle from 'drizzle-builder';
drizzle(options).then(drizzleData => {
// drizzleData object contains data about the build
});Drizzle builds static HTML output from source resource files.
- Pages are compiled against a page layout template and output as HTML files.
- Patterns are parsed into collections, which are compiled against a collection layout template and output as HTML files.
- Data files can be used to provide data to patterns and pages.
Pages and patterns can use YAML front matter to override defaults, set particular attributes or provide arbitrary local data for the resource during template compilation. In general, data defined in front matter is made available at the top level of compilation (template) context for that resource.
Certain properties are reserved at the top level for Drizzle use. Each resource has its own reserved keys as well, but the following keys should not be used in front matter for any resource:
contents: Used by Drizzle to store parsed and rendered contents for resources.data: Used for storing pattern- and page-specific data in global objects.drizzle: Thedrizzleproperty is reserved for global context during template compilation.outputPath: Used by Drizzle to record where the resource should be output to the file system.path: Used by Drizzle to retain the path to the original resource source file.
Each file that matches the pages glob (options.src.pages.glob) will generate an HTML page.
layout: Specify the layout template to use for this page resource (default layout templated is defined inoptions.layouts.page).
name: Override default naming for the pattern, which is based on filename.hidden: A truthy value will "hide" this pattern, making it available as data, but not rendered on its collection's page.order: Numeric value for where this pattern should appear in its collection's list of patterns. Defaults to alphabetical by filename. Items are ordered like the CSSorderproperty. Items with negative values come first, then items without values, then items with positive values.
collection: Used by Drizzle to attach some metadata about this pattern's collection.
Collections are "meta" resources. Each directory within the glob match for options.src.patterns.glob that contains at least one matching pattern file is considered a "collection." By default, collections are named based on their directory name. One output HTML page is generated per collection.
Creating a file named collection.yaml, collection.yml or collection.json in a pattern directory allows you to override data about that collection. Accepted properties are:
name{String}: Override default directory-based naminghidden: AnArrayof{String}pattern ids to hide in the collection's output (base filename without extension)order: AnArrayof{String}pattern ids in the order you'd like them to display. Items are ordered like the CSSorderproperty. Items with negative values come first, then items without values, then items with positive values.
hidden and order values can also be defined in individual patterns' front matter. Local pattern data will override data in collection metadata files.
Unlike other resources, properties in collection metadata files that are not one the properties listed here will be ignored.
items: Used by Drizzle to store all of the patterns in this collection (even hidden ones)patterns: Used by Drizzle to store all of the visible, ordered patterns in this collection.
Files that match options.src.data.globs will be parsed and made available to templates. See documentation about global scope in the templates section.
The context available to resources during template compilation is a combination of a shared global context and a local context specific to the resource.
Templates receive a drizzle data at the top level of their context. Top-level keys on this object are:
data: Structured object of parsed data filesoptions: Object of options that drizzle is usingpages: Structured object of all page datapatterns: Structured object of all patternstemplates: Structured object of all templates (partials, layouts) and their contents
options {Object}- return:
Promiseresolving to{Object}of build data
All options are optional.
{Object} of options to pass to js-beautify, which is used to pretty-fy source code.
Default:
beautifier: {
indent_size: 1,
indent_char: ' ',
indent_with_tabs: true
}
{Object}
Default:
debug: {
logFn: console.log
}
logFn{Function}that takes amsgargument. Defaults toconsole.log. You could change this if you wanted messages and errors to go somewhere else.
{Object} of {String} paths for outputting drizzle pages and pattern collection HTML files.
Can be relative to project root.
Default:
dest: {
pages : './dist',
patterns: './dist/patterns'
}
An {Object} associating different drizzle output page types with their default layout (template). Currently relevant for page and collection. String values correspond to the filename (minus extension) of the layout under the src.templates directory/glob.
Defaults to:
layouts: {
page : 'default',
collection: 'collection'
}
An {Object} of parser objects for parsing different kinds of source files. Any passed here will extend the default parsers.
@TODO: More docs here
parsers : parsers
{Object} source globs and "basedirs" for different types of drizzle resources.
The glob property is probably more straightforward: that's a glob to match files of that type of resource.
The basedir property is directory level to start keying the associated object from—sort of like a "relative path" to use as a root for keying the resources. It should be a {string} that matches one of the directories in the glob expression.
The default value of the src.patterns property, e.g.:
patterns: {
glob: 'src/patterns/**/*.html',
basedir: 'patterns'
}
indicates, e.g., that we should consider all pattern resources "relative" to the directory "patterns" and start the keying of the patterns object from there. Note: You can leave basedir alone unless you make significant changes to globs from default.
src properties include:
data: data files that contain (typically) YAML or JSON data to make available on drizzleData global context.pages: source page files (typically Handlebars with YAML frontmatter) to transform into HTML pages.patterns: patterns.templates: Handlebars source files—layouts and partials—to be registered as partials on Handlebars. Also made available on thetemplatesproperty of global data.
Default:
src: {
data : {
basedir: 'src/data',
glob: 'src/data/**/*'
},
pages : {
basedir: 'src/pages',
glob: 'src/pages/**/*'
},
patterns: {
basedir: 'src/patterns',
glob: 'src/patterns/**/*.html'
},
templates: {
basedir: 'src/templates',
glob: 'src/templates/**/*'
}
}
drizzle() returns a Promise resolving to an Object (drizzleData) representing the data about the build.
options: Theoptionsthe build was ultimately created with.data: Parsed data from data source files.pages: Contents of parsed page source files and their metadata.patterns: Hierarchical structure of patterns, their containing collections and metadata.templates: Contents of parsed layouts and partials.
npm build:babel-izesrcintodistnpm test:build, then runmochatests