Co-op Cloud Website
Jekyll theme and site for the Co-op Cloud Federation website, built on Sutty Base Bootstrap 5 and maintained as a heavily customized fork.
- Testing site: https://coopcloud.testing.sutty.nl
- Repository: https://git.coopcloud.tech/kawaiipunk/new-website-jekyll-theme
- Deploy target: Sutty (no deployment jobs live in this repository)
Overview
This repository contains both the Jekyll theme and the site content:
- Bootstrap 5-based layout and component library
- CMS-driven content stored as Jekyll documents in
_en/and_es/ - Dynamically generated recipe and taxonomy pages
- Static full-text search using Pagefind
- ActivityPub/Fediverse support through
jekyll-activity-pub - Production assets compressed with Brotli and Gzip
Content is normally authored through the Sutty CMS, which commits changes to the repository and triggers a build on the Sutty platform.
Stack
| Layer | Technology |
|---|---|
| Site generator | Jekyll 4.4 |
| CSS | Bootstrap 5.3, Sass, sass-embedded |
| JavaScript | esbuild, Stimulus, Turbo |
| Search | Pagefind |
| Deployment | Sutty |
| CI | GitLab CI |
| Task runner | go-task |
| Package managers | Bundler, pnpm |
| Media | Git LFS, libvips |
Requirements
For a complete local build:
- Ruby 3.1.5
- Bundler 2.6.9
- Node.js with pnpm 9
- go-task
- Git LFS
- libvips
file/ libmagicpyftsubsetfrom Python FontTools, only when regenerating icons
The CI image is git.sutty.abyaya.la/containers/ruby:3.17.10-3.1.5, which is
Alpine-based. Gemfile.lock currently targets x86_64-linux-musl.
Getting started
1. Fetch LFS assets
Fonts, images, the compiled JavaScript bundle, and the Pagefind binary are tracked with Git LFS:
git lfs install
git lfs pull
Without this step, these files are small text pointer files and the site will build with broken assets.
2. Install dependencies
bundle install
pnpm install
bundle install uses the gem source from GEMS_SOURCE, defaulting to:
https://gems.sutty.nl
3. Build
Plain Jekyll build:
bundle exec jekyll build
Production build:
JEKYLL_ENV=production bundle exec jekyll build
Output is written to _site/.
Sutty local sandbox
Sutty-based development uses the haini.sh environment configured in
.env.development:
task build
This task:
- Installs Node and Ruby dependencies
- Adds the local domain to
/etc/hosts - Starts nginx through
haini.sh - Runs
jekyll build
It requires the external haini.sh environment and sudo access, so it is not
portable to ordinary machines or CI.
The local URL is printed by:
task url
JavaScript
JavaScript sources live in _packs/ and are bundled with esbuild.
Development bundle with live rebuilds:
task watch
Production bundle:
task pack
task pack writes a hashed bundle to assets/js/pack.[hash].js, updates
_data/manifest.json, and commits both. In production, _includes/pack.html
loads the bundle referenced by the manifest.
In development, the site loads /pack.js, which only exists after running
task watch. A development build without that file has no JavaScript.
Important: task build does not rebuild JavaScript. Run task pack and
commit the output whenever _packs/ changes.
CSS and theming
assets/css/styles.scss imports Bootstrap from node_modules and injects theme
values from the theme document using custom Liquid-to-Sass filters.
The theme document is currently:
_en/2026-05-31-coopcloud-theme.markdown
It controls colors, fonts, rounded corners, shadows, and heading sizes. The
compiled stylesheet is served with an integrity hash generated by
_plugins/digest_pages_and_static_files.rb.
Fonts are either self-hosted files in assets/fonts/ or loaded through the
generated font Sass partials in _sass/.
Content
Content is stored in locale directories:
_en/
_es/
Currently only en is enabled in _config.yml:
locales:
- en
Spanish content exists but is not published until es is added to locales.
Collections from layouts
Documents are grouped into Jekyll collections based on their layout, using
_plugins/jekyll_collections_from_layout.rb and _data/inflections.yml.
Examples:
| Layout | Collection |
|---|---|
post |
posts |
document |
documents |
about |
abouts |
menu_internal |
menu_internals |
card_contact |
cards_contact |
When adding a new layout that contains documents, add its plural form to
_data/inflections.yml. The build aborts if a layout has no plural mapping.
Content front matter
Typical fields include:
title: Page title
description: Short description
layout: document
permalink: /example/
uuid: ...
order: 10
draft: false
locales: []
render_with_liquid: false
categories: []
topics: []
tags: []
status: active
Most CMS-authored bodies contain raw HTML with render_with_liquid: false.
Render components
The theme replaces Liquid's render tag with _plugins/render_with_schema.rb.
Includes declare a typed schema in their front matter:
---
title:
type: 'string'
default: ''
---
Components are called with:
{% render 'bootstrap/card.html', title: post.title, url: post.url %}
The plugin validates parameter types, applies defaults, and caches renders in production.
Internal links
CMS links carry a data-id attribute matching another document's uuid.
_plugins/update_internal_permalinks.rb rewrites these to the current URL after
permalink changes and removes links to missing documents.
Generated pages
_plugins/routes.rb creates pages at build time for:
- One page per software recipe from
_data/recipes.json /recipes/- Indexed search result cards
- Category, topic, tag, and status archive pages
Recipe data is expected to be placed in _data/recipes.json; the route
generates a page for every top-level key.
Search
Search is powered by Pagefind:
- Markup is rendered with
data-pagefind-bodyand filter metadata in_layouts/default.html. _plugins/pagefind.rbruns_bin/pagefindafterjekyll write._bin/pagefindis a Git LFS binary and must be executable.- The generated index lives under
_site/pagefind/.
If the Pagefind step fails, it is usually because the LFS binary was not fetched.
ActivityPub
jekyll-activity-pub is configured in _config.yml:
activity_pub:
url: https://social.distributed.press
announce: false
activity_pub_private_key: "./privkey.pem"
Posts do not federate by default:
defaults:
- scope:
type: posts
values:
activity: false
privkey.pem is not committed. It must be provisioned by the Sutty
environment or supplied at build time.
Build tasks
| Task | Purpose |
|---|---|
task / task build |
Full local Sutty build |
task gems |
Install Ruby gems |
task node-modules |
Install Node modules |
task pack |
Build and commit production JS |
task watch |
Rebuild JS during development |
task lint |
Check formatting with Prettier |
task format |
Apply Prettier |
task rubocop |
Lint changed Ruby plugins |
task fa |
Regenerate the Fork Awesome subset font |
task fa-add -- name |
Add an icon to _data/fa.yml |
task google-font -- URL |
Download and add a Google Font |
task optimize-svg -- file.svg |
Optimize an SVG |
task gem-audit |
Audit Ruby dependencies |
task node-audit |
Audit Node dependencies |
task issue -- 42 |
Create issue-42 from antifascista |
CI
.gitlab-ci.yml runs only a test stage:
| Job | Trigger |
|---|---|
gem-audit |
Scheduled pipelines |
node-audit |
Scheduled pipelines |
rubocop |
Merge requests |
lint |
Merge requests |
build |
Merge requests |
The build job runs:
go-task bundle -- exec jekyll build --trace --profile
with:
JEKYLL_ENV=production
HAINISH=""
CI does not deploy the site and does not preserve _site as an artifact.
Deployment is handled entirely by Sutty.
Deployment
Sutty builds and serves this site. The repository intentionally has no deploy stage, SSH configuration, container, or static-host configuration.
Expected Sutty build command:
bundle exec jekyll build
with JEKYLL_ENV=production.
Check the following in the Sutty dashboard:
- The project points to the
coopcloud.testing.sutty.nlbranch. - The production environment provides Airbrake credentials:
AIRBRAKE_PROJECT_IDAIRBRAKE_PROJECT_KEY
privkey.pemis provisioned for ActivityPub.- LFS assets are available to the build environment.
- Git LFS is fetched before building.
Because Sutty may run only jekyll build, generated assets must be committed:
assets/js/pack.*and_data/manifest.jsonafter changing_packs/assets/fonts/forkawesome-webfont.woff2after changing_data/fa.yml
Verifying a deployment
After publishing:
- Confirm the live
Last-Modifiedheader is newer than the deployed commit. - Check that these return
200://assets/css/styles.css- the JS path referenced by
_data/manifest.json /assets/fonts/forkawesome-webfont.woff2/pagefind/pagefind.js
- Confirm generated pages resolve, for example
/recipes/and/the-community/.
The testing site is intentionally marked noindex; keep that behavior.
Project structure
_en/ English content
_es/ Spanish content
_data/ CMS schemas, translations, Bootstrap data, recipes
_docs/ Internal documentation
_includes/ Liquid components
_layouts/ Jekyll layouts
_packs/ JavaScript entry point and Stimulus controllers
_plugins/ Custom Jekyll plugins
_sass/ Sass partials and generated font styles
assets/ CSS, JS, fonts
public/ Uploaded media
_bin/ Helper scripts and Pagefind binary
Taskfile.yaml Development tasks
_config.yml Jekyll configuration
Troubleshooting
Assets are text files mentioning git-lfs
LFS objects were not fetched:
git lfs install
git lfs pull
forkawesome-webfont.woff2 returns 404
The generated icon font is missing. Regenerate and commit it:
task fa
git add assets/fonts/forkawesome-webfont.woff2
git commit -m "build: regenerate Fork Awesome subset"
JavaScript is missing in development
Run:
task watch
Production builds require task pack and a committed bundle.
Build fails on libvips or libmagic
Install the native dependencies:
# Fedora
sudo dnf install vips file
Gem installation fails
Verify access to https://gems.sutty.nl, or override the source:
GEMS_SOURCE=https://rubygems.org bundle install
Note that some Sutty-specific gems may not exist on rubygems.org.
Pagefind fails after the build
Check that _bin/pagefind is a real executable, not an LFS pointer:
file _bin/pagefind
_bin/pagefind --version
Changes are not visible on the live site
Confirm that:
- The commit is on the branch mapped to the Sutty project.
- The site was republished from the Sutty dashboard or webhook.
- The live
Last-Modifiedheader reflects the new build.
License
The theme is distributed under the Anti-Fascist MIT License. See
LICENSE.txt.
Content licensing is defined by the documents in the site itself, including the
license page under _es/2026-05-26-licencia.markdown.