complate-ssg
v0.19.4
Published
static-site generator for complate
Downloads
10
Readme
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:
title: Hello World
lorem ipsum
* foo
* bar
dolor sit ametViews
HTML is rendered using complate views:
function render({ slug, metadata, html }) {
return <DefaultLayout title={meta.title}>
{safe(html)}
</DefaultLayout>;
}
function DefaultLayout({ title }, ...children) {
return <html>
<head>
<meta charset="utf-8" />
<title>{title}</title>
</head>
<body>
{children}
</body>
</html>;
}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:
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:
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:
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:
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:
options.transforms = {
adoc: (source, metadata) => asciidoc(source, { layout: metadata.layout })
};Here's an approximation of complate-ssg's default values for reference:
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
})
}
};