schlump

A static site generator utilizing reactjs.

schlump generates html and copies your static resources into a give folder structure. Aftewards the generated html is validated for consistency.

Installation

npm install schlump

Quickstart

Create the following folder structure:

src
src/pages     <-- place your content here
src/templates <-- place your page components here
src/statics   <-- place all static assets here
src/helpers   <-- place all helper functions here (optional)

./node_modules/.bin/schlump

The result is written into the dist folder.

Usage

$ schlump

Usage
  $ schlump [options]

Options

  --help, -h             Usage information
  --src                  Source folder (defaults to src)
  --src-pages            Folder to look for pages (default to <src>/pages)
  --src-templates        Folder to look for templates (defaults to <src>/templates)
  --src-statics          Folder to look for static files (defaults to <src>/statics). Repeat for mulitple sources.
  --src-helpers          Folder to look for helper functions (defaults to <src>/helpers)
  --dest                 Destination folder (defaults to dist)
  --dest-statics         Folder to write statics (defaults to <dest>/statics)
  --var.<name>=<value>   Define global properties which are usable during build pages
  --disable-validation   Disable html validation (no link and resource checking)
  --redirect-map         A json file with key value pairs of url-path (source) and full qualifed urls (target)
  --scoped-css           Path of the file to write all scoped css to
  --css-variables        Enable support for css-variables
  --template-import='<file-or-node-module-path>[:<namespace>]'
                         Imports the react-components from the given path at the given namespace

Examples
  $ schlump # Execute with default
  $ schlump --src-statics=./statics-one --src-statics=./statics-two

Pages

Pages in schlump are JSX files (only the JSX code without JavaScript boilerplate). All pages are stateless function components which could have a frontmatter preamble. The frontmatter could contain a route entry to specify the URL of the page to create. All other frontmatter data is given to the page under the scope frontmatter.

---
route: /index.html
text: Content!
---
<p>{frontmatter.text}</p>

Templates

Templates for schlump are either JSX files (only the JSX code without JavaScript boilerplate), SVG files or Markdown files. All templates are stateless function components which could have as well a frontmatter preamble.

The component name is either given in frontmatter as name or derived from the file name.

For example in a file named src/templates/my-component.html:

---
name: MyComponent
---
<div>
    {props.message || 'Lorem ipsum'}
</div>

This template (component) could then be used in a page with the name MyComponent.

For example in a file named src/pages/index.html:

<MyComponent message="Hello World!" />

Helpers

Helpers are functions which could be used in all templates.

Helpers must export a function at module.exports, the name of the helper is deduced from the camel-cased file name of the helper function.

For example in a file named src/helpers/hello-world.js:

module.exports = function () { return 'Hello World!'; };

This results in a helper which could be called in a template like this:

<div>
    {helpers.helloWorld()}
</div>

Note: The helpers are only availalbe in templates, NOT in pages.

Globals

Global variables which are available in all pages. These values are available as top-level props.

If schlump is executed with schlump --var.foo=bar and the following page:

<div>
    {props.foo}
</div>

this html is rendered as result: <div>bar</div>.

Validation

Currently the following elements get validated:

• a[href] - relative links to pages must exist (no dead links)
• img[src] - relatie image resources must exist
• img[srcset] - relatie image resources must exist
• *[style] background-image - relative resources in inline-style background-images must exist
• link[href] - relative external resources must exist

Redirects

Given schlump is started with the parameter --redirect-map map.json and map.json contains:

{
  "/old/page/url": "https://github.com/sinnerschrader/schlump"
}

then schlump generates a page at <dest>/old/page/url/index.html which contains a meta refresh to https://github.com/sinnerschrader/schlump.

Scoped CSS

Pages and Templates could have a scoped css tag which contains the styles of that component. Only simple selectors are possible which implicitly means that the style rules are scoped to that component.

For ease of use and to keep templates dry and reusable css-variables have been implemented. That includes full support for inheritance/scoping. (Note: There is no interoperability between javascript and css. This means it is not possible to dynamically set variables.)

---
name: Element
---
<style scoped>
.element {
    color: blue;
    background-color: var(--common-background-color);
}
.element h1 {
    color: green;
}
h1 + p {
    color: red;
}
</style>
<div className={style.element}>
    <h1>headline<h1>
    <p>
        copytext
    </p>
</div>

Template Imports

With the option --template-import it is possible to integrate external React libraries (e.g. elemental ui) into schlump sites.

The libraries are either referenced from node_modules (e.g. elemental) or by relative path (e.g. ./node_modules/elemental) and could be imported into an optional given namespace.

$ # This would import elemental-ui into the namespace UI
$ schlump --template-import='elemental:UI'

Afterwards all components of the library could be used with the given namespace.

<body>
    <UI.Button/>
</body>

The option could occurr multiple times on the cli. If there are name clashes in the namespace and module names, the last given option overwrites former imports.

If there is no namespace given, then the library is imported into the default schlump template space. But it is not possible to overwrite local schlump templates by an imported library.

schlump is built with JavaScript and :heart: and released under the MIT license.