Nearsighted Paramecium Multiverse

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

    Keywords

    none

    Install

    npm i complate-ssg

    DownloadsWeekly Downloads

    22

    Version

    0.19.4

    License

    Apache-2.0

    Unpacked Size

    13.6 kB

    Total Files

    19

    Last publish

    Collaborators

    • fnd