2026-10-29 13:48:31 +00:00
2026-09-01 14:04:00 -03:00
2025-05-30 15:50:16 -03:00
2026-10-23 11:33:46 -06:00
2026-10-22 17:40:29 -03:00
2026-08-05 14:38:01 -03:00
2026-08-14 17:47:24 -06:00
2026-09-09 07:31:06 -03:00
2025-04-04 09:32:59 -03:00
2025-03-03 14:08:48 -03:00
2026-09-01 14:04:00 -03:00
2025-09-07 13:22:16 -03:00
2026-06-17 16:02:21 -03:00
2026-08-05 16:14:39 -03:00
2025-03-03 14:10:06 -03:00
2026-08-18 16:54:24 -03:00
2025-03-05 18:11:19 -03:00
2025-03-03 17:54:25 -03:00
2026-09-14 14:21:17 -03:00
2026-10-29 13:48:31 +00:00
2025-12-17 16:45:32 -03:00

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.

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 / libmagic
  • pyftsubset from 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:

  1. Installs Node and Ruby dependencies
  2. Adds the local domain to /etc/hosts
  3. Starts nginx through haini.sh
  4. 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.

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 is powered by Pagefind:

  • Markup is rendered with data-pagefind-body and filter metadata in _layouts/default.html.
  • _plugins/pagefind.rb runs _bin/pagefind after jekyll write.
  • _bin/pagefind is 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.nl branch.
  • The production environment provides Airbrake credentials:
    • AIRBRAKE_PROJECT_ID
    • AIRBRAKE_PROJECT_KEY
  • privkey.pem is 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.json after changing _packs/
  • assets/fonts/forkawesome-webfont.woff2 after changing _data/fa.yml

Verifying a deployment

After publishing:

  1. Confirm the live Last-Modified header is newer than the deployed commit.
  2. 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
  3. 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-Modified header 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.

S
Description
No description provided
Readme
38 MiB
Languages
HTML 36.9%
JavaScript 24.4%
SCSS 22%
Ruby 15.9%
Shell 0.8%