kerolox/site/content/contribute/site.md

+++ 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¹

Dependencies

The site is generated using Zola, a reasonably minimal static site generator. Each page is written in Markdown and templated into HTML. You can find instructions to install Zola here.

To best communicate visual information throughout our documentation, we use Typst to generate diagrams during the site compilation process. It's a required dependency for building the site, so please follow Typst's installation instructions to install it for your system.

We use the 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 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, so in order to build the website, you must update that submodule. If you've already cloned the repository, you can ensure that the Abridge submodule is updated correctly by running the following commands:

git submodule init
git submodule update

Building the Website

To build the website, run make in the site directory of the repository:

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:

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 for mobile sandbox
• TODO: Atkinson Hyperlegible Next
• TODO: document how to report bugs and get help
• TODO: cookbook for common Kerolox idioms
• TODO: tag example pages by demonstrated concept
• TODO: favicon

---

1. TODO: provide direct contact guidelines ↩︎