clover sitegen framework

this repository contains clover's "sitegen" framework, which is a set of tools that assist building websites. these tools power https://paperclover.net.

HTML "Server Side Rendering") engine written from scratch. (~500 lines)
- A more practical JSX runtime (class instead of className, built-in clsx, html() helper over dangerouslySetInnerHTML prop, etc).
- Integration with Marko for concisely written components.
- TODO: MDX-like compiler for content-heavy pages like blogs.
- Different languages can be used at the same time. Supports async function components, <Suspense />, and custom extensions.
Incremental static site generator and build system.
- Build entire production site at start, incremental updates when pages change; Build system state survives coding sessions.
- The only difference in development and production mode is hidden source-maps and stripped console.debug calls. The site you see locally is the same site you see deployed.
- (TODO) Tests, Lints, and Type-checking is run alongside, and only re-runs checks when the files change. For example, changing a component re-tests only pages that use that component and re-lints only the changed file.
Integrated libraries for building complex, content heavy web sites.
- Static asset serving with ETag and build-time compression.
- Dynamicly rendered pages with static client. (#import "#sitegen/view")
- Databases with a typed SQLite wrapper. (import "#sitegen/sqlite")
- TODO: Meta and Open Graph generation. (export const meta)
- TODO: Font subsetting tools to reduce bytes downloaded by fonts.
Built on the battle-tested Node.js runtime.

None of these tools are complex or revolutionary. Rather, this project is the sum of many years of experience on managing content heavy websites, and an example on how other over-complicate other frameworks.

Included is src, which contains paperclover.net. Website highlights:

Development

minimum system requirements:

a cpu with at least 1 core.
random access memory.
windows 7 or later, macos, or other operating system.

my development machine, for example, is Dell Inspiron 7348 with Core i7

npm install

# production generation
node run generate
node .clover/out/server

# "development" watch mode
node run watch

for unix systems, the provided flake.nix can be used with nix develop to open a shell with all needed system dependencies.

Deployment

There are two primary server components to be deployed: the web server and the sourth of truth server. The latter is a singleton that runs on Clover's NAS, which holds the full contents of the file storage. The web server pulls data from the source of truth and renders web pages, and can be duplicated to multiple cloud hosts without issue.

Deployment of the source of truth can be done with Docker Compose:

services:
  backend:
    container_name: backend
    build:
      # this uses loopback to hit the self-hosted git server
      context: http://localhost:3000/clo/sitegen.git
      dockerfile: src/source-of-truth.dockerfile
    environment:
      # configuration
      - PORT=43200
      - CLOVER_DB=/data
      - CLOVER_FILE_RAW=/published
      - CLOVER_FILE_DERIVED=/data/derived
      - CLOVER_SOT_KEY=... # guards private/unreleased content
    ports:
      - '43200:43200'
    restart: unless-stopped
    volumes:
      - /mnt/storage1/clover/Documents/Config/paperclover:/data
      - /mnt/storage1/clover/Published:/published

Due to caching, one may need to manually purge images via docker image rm ix-paperclover-backend -f when an update is desired

TODO: deployment instructions for a web node

Contributions

No contributions to src accepted, only framework.

4.7 KiB Raw Blame History

clover sitegen framework

Development

Deployment

Contributions

4.7 KiB

Raw Blame History