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