complate-ssg

complate-ssg
============

static-site generator for complate, creating HTML pages
from Markdown and other formats


Getting Started
---------------

``
$ npm install complate-ssg
`

`
$ complate-ssg [options] [content_directory [target_directory]]
`

(See complate-ssh -h for a list of options.)

Source files (see Source Content below) reside in the content
directory, resulting HTML files will be created in the target directory.

The easiest way is to start from the samples (e.g. by copying
node_modules/complate-ssg/samples):

* complate is used to generate a views bundle for rendering HTML – typically
with faucet-pipeline compiling JSX
* complate-ssg uses these views to generate HTML pages from Markdown files


Source Content
--------------

Out of the box, complate-ssg treats .md files as
Markdown. For additional formats, see
Customization below.

Each file must contain a metadata preamble (AKA front matter) at the top,
separated by a blank line:

`markdown
title: Hello World

lorem ipsum

* foo
* bar

dolor sit amet
`


Views
-----

HTML is rendered using complate views:

`jsx
function render({ slug, metadata, html }) {
return
{safe(html)}
;
}

function DefaultLayout({ title }, ...children) {
return






{children}

;
}
`

The render function serves as the entry point for all pages; it might render
different layouts based on slug, which is passed in alongside source contents'
metadata and html.

Next we need to register that render function and allow complate-ssg to invoke
it via renderView:

`jsx
import Renderer, { createElement, safe } from "complate-stream";

let { registerView, renderView } = new Renderer();

registerView(render);

export default renderView;
`

Finally, we need to compile our JSX views to a bundle (dist/views.js by
default), e.g. using faucet-pipeline – see the
samples directory for details.


Customization
-------------

Rendering of source content can be customized via the imperative API – e.g. for
additional file extensions, formats or to adjust link URIs.

Let's create a file ssg.js:

`javascript
let ssg = require("complate-ssg");
let markdown = require("complate-ssg/src/markdown");

// all arguments are optional; defaults are shown below
let referenceDir = __dirname;
let options = { // all entries are optional
transforms: {
md: (source, metadata) => markdown(source)
}
};
ssg(referenceDir, options);
`

The built-in Markdown module supports influencing link targets, e.g. to remove
the .html file extension for internal links:

`javascript
options.transforms = {
html: (source, metadata, pages) => markdown(source, {
resolveURI: uri => {
if(pages.has(uri)) {
return uri.replace(".html", "");
}
return uri;
}
})
};
`

If we want to support a different file extension, we need to add an entry to
options.transforms:

`javascript
options.transforms = {
txt: (source, metadata) => source
};
`

This will add support for .txt files in the content directory, passing
contents through unmodified. (Note that these files also require a metadata
preamble, even though it's unused here.)

We might also want to support other formats, e.g.
AsciiDoc – in which case we'd have to find some
library to generate HTML from .adoc sources:

`javascript
options.transforms = {
adoc: (source, metadata) => asciidoc(source, { layout: metadata.layout })
};
`

Here's an approximation of complate-ssg's default values for reference:

`javascript
let referenceDir = process.cwd();
let options = {
content: "./content",
target: "./dist/site",
views: {
bundle: "./dist/views.js",
name: "render"
},
transforms: {
md: (source, metadata) => markdown(source, {
// if true, this activates typographic enhancements like smart
// quotes, dashes and ellipses
smart: metadata.smart,
// if true, this disallows raw HTML in Markdown sources
safe: metadata.safe
})
}
};
``