114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
# 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`.
|