complate-ssg

0.19.4 • Public • Published

complate-ssg

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

package version build status Greenkeeper badge

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 amet

Views

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
        })
    }
};

Readme

Keywords

none

Package Sidebar

Install

npm i complate-ssg

Weekly Downloads

3

Version

0.19.4

License

Apache-2.0

Unpacked Size

13.6 kB

Total Files

19

Last publish

Collaborators

  • fnd