diff --git a/readme.md b/readme.md index 05ce24f..7fd05dd 100644 --- a/readme.md +++ b/readme.md @@ -1,67 +1,70 @@ -# 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. - - A more practical JSX runtime (`class` instead of `className`, etc). - - Transparent integration with [Marko][1] to mix component types. - - MDX support for text-heavy content pages. -- 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 assertions and `console.debug` calls. The site - you see locally is the site you see deployed. -- Tools for building complex, content heavy web sites. - - Static asset serving with ETag and build-time compression. - - Dynamic server side rendering from within backend code. - - Databases with a typed SQLite wrapper. -- Built on the battle-tested Node.js runtime. Partial support for Deno and Bun. - -[1]: 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 prefetching + client-side navigation][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 - -# live development environment -node repl -``` - -`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. - -TODO: in the future, the repl will have a "dev" command which will do the incremental -site build + host, possibly immediatly on opening the repl. - -## Contributions - -No contributions to `src` accepted, only `framework`. - +# 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. + - A more practical JSX runtime (`class` instead of `className`, etc). + - Transparent integration with [Marko][1] to mix component types. + - MDX support for text-heavy content pages. +- 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 assertions and `console.debug` calls. The site + you see locally is the 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 +- Built on the battle-tested Node.js runtime. Partial support for Deno and Bun. + +[1]: 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 prefetching + client-side navigation][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 +``` + + + + + + + + + +## Contributions + +No contributions to `src` accepted, only `framework`. +