Cabal Club's Website

The Cabal Club's new project website!

Building

Build the site by making your changes and then running sajt.com from within the repository:

./sajt.com --config config.toml

The new directory to serve from the webhost will be at dist/.

See sajt.com --help config for the full configuration documentation and sajt.com --help for how to search sajt's docs.

Viewing the website

For a way to view the site while developing, you can serve it with another terminal process using e.g. python3:

python3 -m http.server 8000 -d dist

This command serves the website files, which are inside the directory dist, making it available to visit in your browser at http://localhost:8000.

Before you can serve the website, you need to build it - see section Building above).

Publishing updates so that they appear on the webpage domain

TODO:

We aim to use Codeberg Pages for the hosting. That means the repo you are viewing is where the source code is saved, but the content is hosted by another repository called pages. It is located at https://codeberg.org/cabal/pages

The steps for making content appear on the website https://cabal.chat are:

# <make your changes, edit files and so on>

# run sajt to generate the html with all the changes
./sajt.com --config config.toml

# copy the contents of the dist/ directory to the pages repository. 
# NOTE: your paths might look different

cp ./dist/* ~/code/cabal/pages

# cd to pages repository, commit the new output, and push it
git commit -am "update website content"
git push

Development

The following is the recommended work flow for rapidly working on the site. It assumes you're on OSX or Linux, or that you know what you are doing inside a WSL (Linux under Windows) environment.

Many workflows are possible, this particular workflow assumes you are using entr. entr is a tool that lets you run a process when changes are detected. It also also suggested that you use e.g. python3 to serve the website for viewing in a web browser while making changes; see the Viewing the website instructions, above.

Using entr, you can auto-build the website when anything changes inside docs/, specs/, content/, templates/, links/ or config.toml with the following line:

ls docs/* specs/* content/* templates/* links/* config.toml | entr ./sajt.com --config config.toml

On website generation

Everything that's needed to build the website are the files in this repository and the tool sajt.com, which is also saved in this repository.

The idea is that it should be easy for someone comfortable with a terminal to edit any file and then build the website on their own computer. The means building it on Linux, OSX, or Windows and without downloading anything outside of this repository.

As of today, only Linux has been tested for this repository, so there might be bugs to fix for e.g. building on Windows.

docs/ and specs/

The docs and specs directories contain files from other cabal club repositories (github.com/cabal-club/cable-docs, and github.com/cabal-club/cable).

A choice was made to copy the source markdown files from the docs repository and the specs repository into this repo. Another option would've been to use git submodules, but it was deemed too complicated compared to vendoring the needed source files.

See specs/instructions and docs/instructions for how to generate outputs for these source files.