| ... | ... | @@ -1,67 +1,70 @@ |
| 1 | | # clover sitegen framework
|
| 2 | |
|
| 3 | | this repository contains clover's "sitegen" framework, which is a set of tools
|
| 4 | | that assist building websites. these tools power https://paperclover.net.
|
| 5 | |
|
| 6 | | - HTML "Server Side Rendering") engine written from scratch.
|
| 7 | | - A more practical JSX runtime (`class` instead of `className`, etc).
|
| 8 | | - Transparent integration with [Marko][1] to mix component types.
|
| 9 | | - MDX support for text-heavy content pages.
|
| 10 | | - Incremental static site generator and build system
|
| 11 | | - Build entire production site at start, incremental updates when pages
|
| 12 | | change; Build system state survives coding sessions.
|
| 13 | | - The only difference in development and production mode is hidden
|
| 14 | | source-maps and stripped assertions and `console.debug` calls. The site
|
| 15 | | you see locally is the site you see deployed.
|
| 16 | | - Tools for building complex, content heavy web sites.
|
| 17 | | - Static asset serving with ETag and build-time compression.
|
| 18 | | - Dynamic server side rendering from within backend code.
|
| 19 | | - Databases with a typed SQLite wrapper.
|
| 20 | | - Built on the battle-tested Node.js runtime. Partial support for Deno and Bun.
|
| 21 | |
|
| 22 | | [1]: https://next.markojs.com
|
| 23 | |
|
| 24 | | Included is `src`, which contains `paperclover.net`. Website highlights:
|
| 25 | |
|
| 26 | | - [Question/Answer board, custom markdown parser and components][q+a].
|
| 27 | | - [File viewer with prefetching + client-side navigation][file].
|
| 28 | | - [Personal, friends-only blog with password protection][friends].
|
| 29 | |
|
| 30 | | [q+a]: https://paperclover.net/q+a
|
| 31 | | [file]: https://paperclover.net/file
|
| 32 | | [friends]: https://paperclover.net/friends
|
| 33 | |
|
| 34 | | ## Development
|
| 35 | |
|
| 36 | | minimum system requirements:
|
| 37 | | - a cpu with at least 1 core.
|
| 38 | | - random access memory.
|
| 39 | | - windows 7 or later, macos, or other operating system.
|
| 40 | |
|
| 41 | | my development machine, for example, is Dell Inspiron 7348 with Core i7
|
| 42 | |
|
| 43 | | ```
|
| 44 | | npm install
|
| 45 | |
|
| 46 | | # production generation
|
| 47 | | node run generate
|
| 48 | |
|
| 49 | | # live development environment
|
| 50 | | node repl
|
| 51 | | ```
|
| 52 | |
|
| 53 | | `repl.js` will open a read-eval-print-loop where plugin state is cached (on my
|
| 54 | | 2014 dev laptop, startup time is 600-1000ms). every file in `framework` and
|
| 55 | | `src` besides `hot.ts` can be edited and quickly re-run. for example, to run
|
| 56 | | `framework/generate.ts`, you can type "generate" into the shell. since
|
| 57 | | top-level await is not supported (plugins are built on `require` as Node has
|
| 58 | | poor module support), CLIs can include a `main` function, which is executed
|
| 59 | | when the REPL runs it.
|
| 60 | |
|
| 61 | | TODO: in the future, the repl will have a "dev" command which will do the incremental
|
| 62 | | site build + host, possibly immediatly on opening the repl.
|
| 63 | |
|
| 64 | | ## Contributions
|
| 65 | |
|
| 66 | | No contributions to `src` accepted, only `framework`.
|
| 67 | |
|
| 1 | # clover sitegen framework |
| 2 | |
| 3 | this repository contains clover's "sitegen" framework, which is a set of tools |
| 4 | that assist building websites. these tools power https://paperclover.net. |
| 5 | |
| 6 | - HTML "Server Side Rendering") engine written from scratch. |
| 7 | - A more practical JSX runtime (`class` instead of `className`, etc). |
| 8 | - Transparent integration with [Marko][1] to mix component types. |
| 9 | - MDX support for text-heavy content pages. |
| 10 | - Incremental static site generator and build system |
| 11 | - Build entire production site at start, incremental updates when pages |
| 12 | change; Build system state survives coding sessions. |
| 13 | - The only difference in development and production mode is hidden |
| 14 | source-maps and stripped assertions and `console.debug` calls. The site |
| 15 | you see locally is the site you see deployed. |
| 16 | - (TODO) Tests, Lints, and Type-checking is run alongside, and only re-runs |
| 17 | checks when the files change. For example, changing a component re-tests |
| 18 | only pages that use that component and re-lints only the changed file. |
| 19 | - Integrated libraries for building complex, content heavy web sites. |
| 20 | - Static asset serving with ETag and build-time compression. |
| 21 | - Dynamicly rendered pages with static client. (`#import "#sitegen/view"`) |
| 22 | - Databases with a typed SQLite wrapper. (`import "#sitegen/sqlite"`) |
| 23 | - TODO: Meta and Open Graph generation. (`export const meta`) |
| 24 | - TODO: Font subsetting tools to reduce |
| 25 | - Built on the battle-tested Node.js runtime. Partial support for Deno and Bun. |
| 26 | |
| 27 | [1]: https://next.markojs.com |
| 28 | |
| 29 | Included is `src`, which contains `paperclover.net`. Website highlights: |
| 30 | |
| 31 | - [Question/Answer board, custom markdown parser and components][q+a]. |
| 32 | - [File viewer with prefetching + client-side navigation][file]. |
| 33 | - [Personal, friends-only blog with password protection][friends]. |
| 34 | |
| 35 | [q+a]: https://paperclover.net/q+a |
| 36 | [file]: https://paperclover.net/file |
| 37 | [friends]: https://paperclover.net/friends |
| 38 | |
| 39 | ## Development |
| 40 | |
| 41 | minimum system requirements: |
| 42 | - a cpu with at least 1 core. |
| 43 | - random access memory. |
| 44 | - windows 7 or later, macos, or other operating system. |
| 45 | |
| 46 | my development machine, for example, is Dell Inspiron 7348 with Core i7 |
| 47 | |
| 48 | ``` |
| 49 | npm install |
| 50 | |
| 51 | # production generation |
| 52 | node run generate |
| 53 | node .clover/out/server |
| 54 | |
| 55 | # "development" watch mode |
| 56 | node run watch |
| 57 | ``` |
| 58 | |
| 59 | <!-- `repl.js` will open a read-eval-print-loop where plugin state is cached (on my --> |
| 60 | <!-- 2014 dev laptop, startup time is 600-1000ms). every file in `framework` and --> |
| 61 | <!-- `src` besides `hot.ts` can be edited and quickly re-run. for example, to run --> |
| 62 | <!-- `framework/generate.ts`, you can type "generate" into the shell. since --> |
| 63 | <!-- top-level await is not supported (plugins are built on `require` as Node has --> |
| 64 | <!-- poor module support), CLIs can include a `main` function, which is executed --> |
| 65 | <!-- when the REPL runs it. --> |
| 66 | |
| 67 | ## Contributions |
| 68 | |
| 69 | No contributions to `src` accepted, only `framework`. |
| 70 | |
clover caruso <git@paperclover.net> 2025-06-13 00:29:30-07:00