Here we collect tips on using arc42.
For every arc42 section, you find
- Motivation: Why is this section useful
- Content: What shall be included in this section
- Form: How could this be done, usually with several variants
- Tips and practical advice
It's powered by Jekyll and a modified TTSCK theme (see below) - the site is generated by github-pages.
The examples are referenced from single markdown files under _examples, and automatically included in the respective sections.
As all of the arc42 content, this FAQ is free to use under a liberal Creative-Commons license:
For documentation on this theme, see the original documentation.
We implemented several enhancements over the original theme (e.g. responsive navigation, thx to Falk Hoppe)
The training block at the foot of ~200 section pages is rendered at build time
from _data/trainings.json — an expiry-filtered copy of
https://trainings.arc42.org/api/trainings.json that
.github/workflows/refresh-trainings.yml refreshes weekly (Mondays 04:47 UTC),
manually via workflow dispatch, or immediately on a repository_dispatch event
(trainings-updated) pushed by trainings.arc42.org-site right after its feed
republishes — committing only when the dates actually changed. The push
dispatch is an accelerator, never a dependency (ADR-0006 in meta.arc42.org):
if it doesn't arrive, the weekly cron still bounds staleness at one week, and
a failed fetch simply keeps the last committed snapshot. Edit dates in the
trainings repo's _data/trainings.yml, never here;
_includes/training-dates.html owns the rendering, _sass/_utilities.scss the
styling. This replaced the former runtime htmx fetch from the Vercel fragment
backend (see the integration spec in the arc42 workspace's
docs/superpowers/specs/2026-08-04-docs-faq-training-dates-design.md).