statiq

statiq
======

A node.js static website generator

* Install
* Basic usage
* Content
* Templates
* Building
* Advanced
* Directory context
* Global context
* Directory indexes
* Command line tool
* Programmatic API
* Plugins
* Plugins API
* Included plugins

Install

$ npm install -g statiq

Basic usage:

Create a statiq website with the interactive cli tool:

$ statiq init

!statiqinit

This will bootstrap the folder structure, statiqfile.js and package.json in the current directory.
There are four directories: content, templates, assets and publish. By default, files in the assets folder will be copied as-is to the publish folder. Documents in the content folder will be merged into their corresponding templates from the templates folder and saved to the publish folder (mirroring content folder structure). For example, this structure:

content/index.md
content/about.md
content/docs/index.md

Will result in:

publish/index.html
publish/about.html
publish/docs/index.html

$3

By default, content is placed in .html files. If you added the markedPlugin, content is placed in markdown .md documents.

Sample index.md:

Welcome!
=======

This is a test page.

#### File variables

You can set context variables in each file, by placing a yaml/json object in its first lines, followed by a triple dash (---):

title: Index page
---

Welcome!
========
...

$3

Default templating engine is ejs. An index.html template file could look like this:

Context variables are available, and the special content variable contains the document itself.

$3

Finally, run:

$ statiq

And you're ready to go!

Advanced

$3

If files in a same folder share some metadata, you can put it in context files within the folder. For example, add a context.json or context.yaml file in a content/docs/ folder, like this:

subtitle: My documents
somedata: ...

Now, every document under content/docs/ (including sub-directories) will have those variables set at build time, unless they are overwritten by a deeper level context or in-file context.

$3

Use the context property in the configuration object within the statiqfile.js:

statiq.config({
...
context: {
sitename: "My awesome website",
...
}
})

This works just like putting a context file in the content/ root. However, by using the statiqfile, you may perform any data processing/manipulation and pass the result, or even pass functions (like moment.js, sorting methods, etc).

$3

In templates, you can iterate through files in a given folder using the special index[folder] variables.
Given this structure:

content/index.md
content/articles/myarticle.md
content/articles/myarticle2.md
content/articles/myarticle3.md
content/articles/subarticles/subarticle.md
content/articles/subarticles/subarticle2.md

You can list the articles folder in your templates accesing index['articles'], and the subarticles folder with index['articles/subarticles'].

Articles:

<% index['articles'].forEach(function(article){ %>

• <%= article.title %>

<% }) %>

Each index[folder] item is set to the context of that file plus a special path variable containing the relative path from the current file and a current variable which is true when the item is the same file accessing it.

#### Hidden documents

Files prefixed with _ will be processed but they won't be included in the index.

Command line tool

$ statiq
Look for nearest statiqfile.js and build website

$ statiq init
Create a new statiqfile and default folder structure

$ statiq init -s
Create a new statiqfile only

$ statiq add
Create a new website document/page/post

$ statiq add --= --=...
Create a new document and set local context values

$ statiq serve
Start a local server

$ statiq watch
Start a file watcher and rebuild website when changes occur

$ statiq serve -w
Start server and watcher

$ statiq help
Show help

Programmatic API

const statiq = require('statiq');
const site = statiq();

site.config({
...
});

site.run();

$3

#### site.config(object config)

Sets site configuration just like a statiqfile. Default configuration is:

{
contentPath: 'content',
templatesPath: 'templates',
publishPath: 'publish',
assetsPath: 'assets',
defaultTemplate: 'index.html',
contentExtension: '.md',
publishExtension: '.html',
hiddenRegex: /^_/, // filenames that shouldn't be included in indexes
plugins: [],
context: {}, // global context
cwd: process.cwd(), // if site is built using the cli tool, it's set to the statiqfile.js dir by default
}

Returns the config object.

#### site.use(fn plugin)

Adds a statiq plugin.
Returns void.

#### site.create(string file, object context, string content?)

Creates a document file with local context and content.
Returns a promise containing the document object.

Hooks: beforeCreate, afterCreate

#### site.read(string file)

Reads and cache a file in the content folder.
Returns a promise containing the document object.

Hooks: beforeRead, afterRead

#### site.update(string file, object context, string content)

Updates the context and content of a cached document file.
Returns a promise containing the document object.

Hooks: beforeUpdate, afterUpdate

#### site.build(string file)

Builds the cached document file. It'll use other cached documents and contexts to generate indexes.
Returns a promise containing the built document object.

Hooks: beforeBuild, afterBuild

#### site.buildAll()

Convenience method to build all the cached documents.

#### site.write(string file)

Writes the cached built document file to the filesystem.
Returns a promise containing the file path.

Hooks: beforeWrite, afterWrite

#### site.writeAll()

Convenience method to write all the cached built documents.

#### site.delete(string file)

Deletes the document file from the cache and the filesystem.
Returns a promise containing void.

#### site.scan(string path?)

Deep-scans the content directory and reads its documents. Specify a path if you don't want to start from the content root.
Returns a promise containing an array of read documents.

#### site.handleAssets()

Process the assets folder. By default, it'll just copy all files to the publish folder.

Hooks: beforeAsset, afterAsset

#### site.list()

Returns all the cached documents

#### site.run()

Convenience method to run scan(), buildAll() and writeAll().
Returns a promise containing an array of generated paths.

Plugins

Plugins can be loaded using the plugins array in the site configuration:

statiq.config({
context: { ... }
plugins: [myPlugin(), ejsPlugin(), markedPlugin()]
});

Or alternatively, loaded later using .use():

statiq.use(myPlugin());

A statiq plugin consists of a function that returns an object with a set of hook properties that will exec in a given step of the build process.

function myPlugin(options) {
return {
beforeBuild(document) {
document.title = "Foo";
return document;
},
}
}

These hooks are executed in the same order the plugins were loaded.
When an before hook returns a falsy value, it prevents its after execution and also any other before* in the chain.

$3

#### beforeCreate(object document)
Runs before a new document is written into the file system.
The document object contains contentPath, context, content and source.
Must return the document object (modified or not), a new document object, or falsy to cancel the document creation.

#### afterCreate(object document)
Runs after a new document has been written to the file system, and can be used to perform any side effects. Returns void.

#### beforeRead(object document)
Runs before a content file is read and cached.
The document object contains contentPath, publishPath, and context (including global context).
Must return the document object (modified or not), a new document object, or falsy to skip reading the document.

#### afterRead(object document)
Runs after a document has been read and cached, and can be used to perform any side effects. Returns void.

#### beforeUpdate(object document, object newContext, string newContent)
Runs before an update is made to a cached document.
To access the current context or content of the document, you can use document.context and document.content.
Must return the document object (modified or not), a new document object, or falsy to skip updating the document.

#### afterUpdate(object document)
Runs after a document has been updated in cache, and can be used to perform any side effects. Returns void.

#### beforeBuild(object document, string template)
Runs before a document is built in memory.
Must return the document object (modified or not), a new document object, or falsy to skip building the document.

#### afterBuild(object document)
Runs after a document has been built in cache, and can be used to perform any side effects. Returns void.

#### beforeWrite(object document)
Runs before a cached document is written to the file system.
Must return the document object (modified or not), a new document object, or falsy to skip writting the file.

#### afterWrite(object document)
Runs after a file has been written to the file system, and can be used to perform any side effects. Returns void.

#### beforeAsset(object assetDocument)
Runs when an asset file is found in the assets directory. assetDocument is an object containing assetPath and publishPath.
Must return the asset object (modified or not), a new object or falsy to skip processing this asset.

#### afterAsset(object assetDocument)
Runs after an asset has been processed, and can be used to perform any side effects.
Returns void.

$3

These plugins are shipped with statiq and can be imported from statiq/plugins.

#### markedPlugin

Lets you write documents content in markdown. Requires marked.

##### Usage

const { markedPlugin } = require('statiq/plugins');

statiq.use(markedPlugin(options))

###### Options

parseMultilineContext (boolean) Process context variables containing a multiline string. Defaults to true.

#### ejsPlugin

Lets you write templates using ejs. Requires ejs.

##### Usage

const { ejsPlugin } = require('statiq/plugins');

statiq.use(ejsPlugin())

#### lessPlugin

Converts .less files in the assets folder into .css files at build time. Requires less.

##### Usage

const { lessPlugin } = require('statiq/plugins');

statiq.use(lessPlugin(options))

###### Options

main (string) Optional. Copy only this filename to the publish folder.

The options object is passed as options to less' render method.

#### blocksPlugin

Lets you define content blocks in documents. Consider a multicolumn layout like this:

Instead of using the content variable, you can define block sections just like this:

title: Multi column
---

< Welcome!
========

Lorem ipsum dolor sit amet blah blah.
left;

< ### Useful links
Google
Wikipedia
right;

This is the main content.

These are Heredoc-ish declaration.
Blocks start with < and end with BLOCK_NAME; (both in their own lines).
Block names are case-sensitive alphanumeric strings. Their content is removed from the content variable.