clover sitegen framework and typescript library

this repository contains clover's "sitegen" framework, which is a set of tools that assist building websites. additionally, this is the home of her typescript library lib, containing many high quality standalone sub-projects. all these tools power https://paperclover.net.

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's source code. Highlights:

• TODO: flashy homepage.
• Question/Answer board, custom markdown parser and components.
• File viewer with fast ui/ux + optimized media streaming.
• Personal, friends-only blog with password protection.
• Blog with pretty automatic table of contents.

Development

minimum system requirements:

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

required software:

• node.js v24

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

# install, build, serve, and watch for incremental rebuilds
node run watch

# create a production site
node run generate
node --enable-source-maps .clover/o/backend

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,
      # docker will cache the image to not re-fetch on reboot.
      context: http://127.0.0.1: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, images may need to be purged via docker image rm {image} -f when an update is desired. Some docker GUIs support force pulls, some are buggy.

The web server performs rendering. A Dockerfile for it is present in src/web.dockerfile but it is currently unused. Deployments are done by building the project locally, and then using rsync to copy files.

node run generate
rsync .clover/o "$REMOTE_USER:~/paperclover" --exclude=.clover --exclude=.env \
  --delete-after --progress --human-readable
ssh "$REMOTE_USER" /bin/bash << EOF
    set -e
    cd ~/paperclover
    npm ci
    pm2 restart site
    echo "-> https://paperclover.net"
EOF

Contributions

No contributions to src accepted, only lib and framework.