# 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.

[Marko]: https://next.markojs.com

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

- [Question/Answer board, custom markdown parser and components][q+a].
- [File viewer with fast ui/ux + optimized media streaming][file].
- [Personal, friends-only blog with password protection][friends].

[q+a]: https://paperclover.net/q+a
[file]: https://paperclover.net/file
[friends]: https://paperclover.net/friends

## 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

<!-- `repl.js` will open a read-eval-print-loop where plugin state is cached (on my -->
<!-- 2014 dev laptop, startup time is 600-1000ms). every file in `framework` and -->
<!-- `src` besides `hot.ts` can be edited and quickly re-run. for example, to run -->
<!-- `framework/generate.ts`, you can type "generate" into the shell. since -->
<!-- top-level await is not supported (plugins are built on `require` as Node has -->
<!-- poor module support), CLIs can include a `main` function, which is executed -->
<!-- when the REPL runs it. -->

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://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, one may need to manually purge images via
`docker image rm ix-clover-backend -f` when an update is desired

TODO: deployment instructions for a web node

## Contributions

No contributions to `src` accepted, only `framework`.