Website docs

site/content/contribute/build.md

@@ -3,4 +3,6 @@ title = "Build from Source"
 description = "How to build Kerolox from source."
 +++
 
+# Cloning the Repository
+
 TODO

site/content/contribute/security.md

@@ -0,0 +1,18 @@
++++
+title = "Security"
+description = "Kerolox's security policy and it affects contributions."
++++
+
+TODO
+
+# npm
+
+Unfortunately for everybody, JavaScript is the language of the web. Kerolox does its best to be free of dependencies on web technology, but occasionally, some JavaScript-based tooling is necessary. We encourage _secure_ use of npm whenever possible and avoid npm whenever security cannot be guaranteed.
+
+[npm](https://www.npmjs.com/) and its package repository are the main tools for creating web-compatible JavaScript. It's also infamously vulnerable[^mini-shai-hulud][^tanstack] to [supply chain attacks](https://en.wikipedia.org/wiki/Supply_chain_attack). Because npm is configured to run arbitrary scripts while installing packages, this means that anybody installing dependencies from the npm package registry is at risk.
+
+[^mini-shai-hulud]: [Mini Shai-Hulud attack](https://www.aikido.dev/blog/mini-shai-hulud-is-back-tanstack-compromised)
+
+[^tanstack]: [Tanstack supply chain attack](https://tanstack.com/blog/npm-supply-chain-compromise-postmortem)
+
+- TODO: describe workarounds

site/content/contribute/site.md

@@ -3,6 +3,45 @@ title = "Website"
 description = "How to contribute to the Kerolox website."
 +++
 
+This website is extremely important to the project because it contains the main onboarding documentation for new users. It also hosts contributor documentation such as what you're reading now. If you have ideas on how to improve it, please let us know![^help-contact]
+
+[^help-contact]: TODO: provide direct contact guidelines
+
+# Dependencies
+
+The site is generated using [Zola](https://www.getzola.org), a reasonably minimal static site generator. Each page is written in [Markdown](https://www.markdownguide.org/) and templated into HTML. You can find instructions to install Zola [here](https://www.getzola.org/documentation/getting-started/installation/).
+
+To best communicate visual information throughout our documentation, we use [Typst](https://typst.app/) to generate diagrams during the site compilation process. It's a required dependency for building the site, so please follow [Typst's installation instructions](https://github.com/typst/typst#installation) to install it for your system.
+
+We use the [Abridge](https://github.com/jieiku/abridge/) Zola theme to provide our styling and HTML templating. It provides lots of web accessibility features while staying lightweight. The theme _does_ use `npm` for some preprocessing, so please bear in mind [our npm security guidelines](@/contribute/security.md#npm) while customizing it. Use of npm for contributing to the site should not be necessary very often, though.
+
+Abridge is included as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules), so in order to build the website, you must update that submodule. If you've already [cloned the repository](@/contribute/build.md#cloning-the-repository), you can ensure that the Abridge submodule is updated correctly by running the following commands:
+
+```sh
+git submodule init
+git submodule update
+```
+
+# Building the Website
+
+To build the website, run `make` in the `site` directory of the repository:
+
+```sh
+make build
+```
+
+This will automatically build all dependencies of the website, run Zola to compile the website itself, then place the results in `site/public`.
+
+To rapidly iterate on the website, you can also use the `serve` target:
+
+```sh
+make serve
+```
+
+This runs Zola as an HTTP server of the site's content at `http://localhost:1111`. Note that while Zola will reload the _contents_ of the site, the _dependencies_ of the site, such as Typst diagrams, will _not_ be. To reload those, kill the server with `Ctrl+C` and run `make serve` again.
+
+# Website To-Do Items
+
 - TODO: [PWA support](https://abridge.pages.dev/overview-abridge/#pwa) for mobile sandbox
 - TODO: Atkinson Hyperlegible Next
 - TODO: document how to report bugs and get help
@@ -13,5 +52,4 @@ description = "How to contribute to the Kerolox website."
   - automatic secret sanitation
 - TODO: cookbook for common Kerolox idioms
 - TODO: tag example pages by demonstrated concept
-
-TODO
+- TODO: favicon