staticpagesjs.github.io

Project page for static-pages-js.

Static Pages JS

This project is in development by a single developer. There is much left to do, and this project page is also a bit outdated now. I plan to stick to this project and release updates and new components as my free time allows.

Yet another static pages generator for small and mid-sized projects written in JavaScript (TypeScript).

Concepts

I try to build this project as a toolbox, where each functionality is separated into its small well testable, documentable package, and build a documentation page later that links these components together with examples and use cases.

The main component is the @static-pages/core which provides the base functionalities. Other packages adds functionalities on top of that. A starter package that links together a few useful things is available at @static-pages/starter. It is a good point to start.

How does the static page generation works?

The user has to define Routes that describes a workflow for a batch of “similar” pages. A route has a source and a destination, and optionally a controller that manipulates the data in between.

A source is not more than an iterable list of page data. There are helpers to read this data from various sources (local fs, Gitlab, Github, etc.) and file formats (JSON, YAML, Markdown, etc.).

A destination is simply a callback function that renders and stores the actual page. There are helpers to render with popular template engines and to save them in the desired storage type.

Features (and the future)

File input and output

There are numerous sources to consider when it comes to reading and writing data. While the filesystem may be the most common source, other options such as web APIs to access Github, GitLab or other Git repositories can also be utilized.

I would like to provide the following packages for these file IO related tasks:

Under consideration: SQL database wrapper packages for SQLite, Oralce, Postgre, Mongo, and any other popular ones.

The SQL sources surely not my primary targets. It will be done when everything is ready and when I can’t improve other parts.

Formats

Parsers can understand and build an object from the raw data that the readers are providing. For instance, if we consider JSON data saved in plain text files, they can be likened to JSON.parse. There are many libraries out there, so I won’t try to implement any of these. The listed readers above will accept a parser property where you could plug in your own parser.

I plan to provide examples later with JSON, YAML, Markdown, Toml, INI inputs with third party libraries.

Renderers can transform your data to a webpage with a template. Again there are a lot of packages out there doing this better than I ever could. However I will try to make and maintain a few wrappers for Twig, EJS, Mustache and Pug for convience and to provide some examples.

Some popular template engines will get a bridge package under the @static-pages namespace. These packages will help to integrate these template engies better in the system.

Planned:

Not on the planned list, because its easy to configure without a bridge package:

Server side and administration

Lately my primary focus is on making administration interfaces and linking our existing workflow together with our static pages powered sites. Currently we are experimenting with ideas like:

I would like to build a headless CMS that can provide an admin page, simlar what DecapCMS does, but in a more programmable and flexible way. Validating by editor roles and data schemas, building on save, with live previews and many more. A lot can change until I’m ready with a working prototype, but one thing I’d definitely like to provide in the Static Pages project is a decoupled admin user interface alongside the existing generator.

Outdated packages

There are some outdated packages in the @static-pages namespace that will be marked as deprecated after some time.

These packages still can work together with the latest static pages engine, and probably always will, but they are built around an outdated concept or there are better alternatives available.

Previously the reading and writing was split into multiple different packages, but since @static-pages/io and the abstract filesystem these became obsolete:

The following package(s) became deprecated thanks to the redesign of the bridge packages for template engines:

Usage / Examples

Here you can find an example repository that are built to demonstrate the idea and to provide a template for you.

https://github.com/staticpagesjs/example-site

Current status

% Component Details
stable starter A good package to test this tool with.
near-stable core The main component.
stable io Helpers to read and write page data. Needs unit tests.
80% nodefs Adds “incremental build” support to nodejs fs module.
50% gitfs Git repository fs.
TODO gitlabfs Gitlab repository fs.
TODO githubfs Github repository fs.
1% Documentation/project page This site you are looking now.
needs update CLI module Allows to easily use the static generator from the command line.
needs update Docker image A docker image that contains my packages ready to use in a build process.

Visit on NPM: static-pages

Roadmap

  1. Create a node filesystem implementation that can process files incrementally (only read changed ones).
  2. Create a local git filesystem implementation.
  3. Create a Gitlab filesystem implementation.
  4. Create a Github filesystem implementation.
  5. Review and deprecate outdated packages if needed.
  6. Create a server-side REST API component.
  7. Create a CMS admin UI that uses the REST API or the Gitlab/Github API.
  8. Add documentation and examples where needed. Cookbook.
  9. Determine whats next.