foojay.io is a static Hugo site, built from this repo and deployed to GitHub Pages behind Cloudflare. It replaced the WordPress site at cutover on 2026-09-22. If you're picking this up fresh, read this before making changes.
REDIRECTS.md documents the live Cloudflare redirect rules that carry old
URLs to their Hugo equivalents.
Publishing a post has to stay effortless for the author. Contributors send
posts as pull requests (see CONTRIBUTING.md); most of them write Java, not
Hugo, and they should be able to open a file, write Markdown, and be done.
Every flag, frontmatter key, naming rule or manual step is a tax on that, and a
thing an author can get wrong or forget.
So validate every change against this, and prefer, in order:
- Derive it. If the build can work it out from the content, it must —
don't ask the author. The layout detects code blocks in the rendered page
instead of reading an
enlighterjs:flag; sponsor article counts and "Topics covered" are computed fromauthors:rather than stored. - Default it. If it can't be derived, pick the right default and let the rare case override.
- Ask for it. Only when the answer genuinely lives in the author's head
(
title,related_posts, a sponsor'sauthors:list).
A flag that is always set to the same value is not configuration, it's a
chore — delete it. When a knob does have to exist, validate/Frontmatter.java
should catch a mistake at PR time rather than letting it fail silently.
A comment earns its place by saying what the code cannot. Keep new ones short:
- Say WHY, not what — the code already says what it does.
- Three or four lines is the ceiling, and one is usually enough. Only a genuinely subtle trap earns more.
- Say it once. If something is already explained elsewhere, point at it rather than repeating it.
- No narrating the diff, and no history of what the code used to do.
This applies to every language here: Go templates, CSS, JS, Java, frontmatter. Plenty of existing comments are longer than this allows — shorten them when you touch them, and don't take them as the model for new ones.
-
Hugo skeleton:
hugo.toml,themes/foojay/(layouts +static/css/style.css), andtemplate/(starter files for article, page, author, board member, ad and event, plus the category list — seetemplate/README.md). There is deliberately noarchetypes/: nothing runshugo new, and two sets of starter files drifted — the post archetype wrote a singularauthor:against author files where posts take anauthors:list of author folders. Add starter files totemplate/. -
scripts/is grouped by lifetime, not by verb —fetch/(external data, runs in CI) andvalidate/(PR-time checks). A script is named for what it produces, the folder supplying the verb (fetch/Jugs.java, notFetchJugs.java). All run from the repo root — they resolvecontent/anddata/against the working directory.scripts/README.mdis the index.transfer/,cleanup/and theshared/converter they both called were deleted at cutover. Where a convention below namesHtmlToMarkdown,Posts.javaorcleanup/images.py, that is one of them: they are named because they explain the shape of what is incontent/, not because there is a file to open. Read one out of git history if you need it. -
content/came out of a scraper, not a database export. The deletedtransfer/scripts read the live foojay.io site (no WP admin or DB access) and wrote the Markdown in the repo today. When something incontent/looks odd, the answer is usually "this is what the WordPress page rendered".
See scripts/fetch/AGENTS.md. All fetchers run daily from
sync-external-content.yml, commit their result, then dispatch a deploy.
Never hand-edit a generated file under data/.
worker/views/is a Cloudflare Worker over a D1 table of<section>/<slug> -> (legacy, live), routed atfoojay.io/api/views/*. Deployed by hand (wrangler deploy), never by CI, because it writes outside the repo and needs a credential. Deployed and seeded on 2026-08-24 by IT, sowrangler.toml'sdatabase_idis still theREPLACE_WITH_D1_DATABASE_IDplaceholder and a deploy from here would not work until it is filled in. Seeworker/views/README.md, and the read-counter convention below for why this exists rather than a hosted analytics service.
notify/SlackPosts.javaposts from the site's own RSS feed through two incoming webhooks (secretsSLACK_WEBHOOK_CONTENT,SLACK_WEBHOOK_GENERAL); unset, it prints and exits 0. "New" is a diff, not remembered state:build-deploy.ymlsaves the live feed before deploying and theannouncejob compares it with the new build's, so a scheduled post is announced when it goes live. An empty previous feed skips rather than announcing everything.slack-weekly.ymlposts the previous Monday-to-Sunday week every Monday.
See scripts/validate/AGENTS.md (Frontmatter.java, BuiltSite.java) and
tests/e2e/AGENTS.md (the browser half of the deploy gate).
-
build-deploy.ymlbuilds with Hugo and deploys to GitHub Pages on push tomainand onworkflow_dispatch— which is how the two scheduled syncs get their data onto the site. It refreshes and commits the generated data files before the Hugo step, so anything that makes that push fail takes the deploy down with it.hugo-versionislatest, here and inpr-check.yml, by decision.peaceiris/actions-hugoresolves it throughformulae.brew.sh, so anECONNRESETfrom Homebrew's API can fail a run before Hugo is downloaded: re-run it. A Hugo release that changes a template function shows up as a red build, not a silent one. -
Three workflows push to
main, the concurrency group covers only two, so every push RETRIES. The two syncs shareconcurrency: data-sync;build-deploy.ymlcannot join them, its group beingpageswithcancel-in-progress. That is not a stale-data bug, it is a lost deploy: the push runs before Hugo, so whichever job loses the race fails. All three wrap the push in a five-attemptgit pull --rebase --autostash && git pushloop. Don't replace that with concurrency configuration — pull-then-push is two commands and no group setting closes the window between them. And don't read! [rejected] main -> main (fetch first)as a protection failure; that is git's own fast-forward check, where a ruleset saysGH006. -
A PUSH BY A WORKFLOW DOES NOT BUILD THE SITE, so the deploy is DISPATCHED. Events triggered by
GITHUB_TOKENdo not create a workflow run, andworkflow_dispatchis the documented exception. For as long as the syncs existed their commits landed and nothing rebuilt — confirmed against the run history, not the docs. Both now end withgh workflow run build-deploy.yml --ref main, and only on runs where a file changed. Their commits also carry[skip ci], which did nothing underGITHUB_TOKENbut stops a double build now the pushes use an App token.Don't "simplify" this by relying on the push, and don't add a
workflow_runtrigger: that fires on every completed sync run, including the majority where nothing changed, and would deploy on a timestamp. -
publish-scheduled.ymlis what actually causes a scheduled post to go out — see the scheduling convention below. It commits nothing, which makes it the cheapest workflow here: no App token, no bypass entry, no toolchain. -
Protecting
main. LIVE since 2026-08-31 as a single repository ruleset targeting the default branch, carrying deletion, non_fast_forward, pull_request and required_status_checks (build-and-validate), bypassed byRepository adminand the app.BRANCH_PROTECTION.mdis the runbook.The blocker was never the rules, it was the token:
GITHUB_TOKENcannot be granted a bypass — a ruleset bypass list takes roles, teams, apps and deploy keys. So all three workflows mint an App token (actions/create-github-app-token@v2, app id4781767, Contents: read and write only), guarded byif: vars.DATA_SYNC_APP_ID != ''so a fork is unaffected.Require signed commitsstays off, because the bots do not sign. The bypass is verified by commit421fb7b57, a bot commit landing two minutes after the ruleset went active. A green sync run is not evidence — the one meant to prove it took an early branch and never reachedgit push.Two deployed details differ from what the runbook recommends, and both want a decision rather than a rediscovery:
- It is ONE ruleset, and
Repository adminbypasses it in modealways, so an admin currently bypasses deletion and non_fast_forward too — i.e.maincan be force-pushed or deleted. It wants to be two:main integrity(deletions + force pushes, with an empty bypass list, since those rules don't block an ordinary push) andmain review(PR + status checks, bypassing admin and the app). A bypass exempts an actor from every rule in its own ruleset, which is the whole reason to split. - Required approvals is 1, not 0. With a single maintainer that is not a
review gate — GitHub won't let an author approve their own PR, so merges
happen through the admin bypass rather than the rule. Set it to 0 if the
intent is "a PR must pass
build-and-validate".
- It is ONE ruleset, and
Most of what this section used to list closed at or before cutover: the
scrapers are deleted, the fetchers all run daily for real, the theme carries
the live site's own palette, Featured Authors exist, /java-terms-explained/ holds every
entry, search is live, and the paid banner carousel is built (see the ads
convention below). What is genuinely still open:
- Ketch's Google Consent Mode plugin is listed but not configured on the
azul/foojay_ioproperty: the config has"googletag": {}— an empty object, wheregpcbeside it carries realpurposeMappings. So Ketch records consent on its own side and never callsgtag('consent','update'). That is why loading GA4 directly flatlined analytics at cutover, and why the site is back on the GTM container with no Consent Mode defaults. Configuring that plugin is what would make a direct GA4 tag viable again — and a plugin key in the config listing is not evidence it is configured; only a browser can tell you. - The accessibility backlog is the site's biggest real gap — thousands of
images across
content/with no description, plus every podcast post with no transcript.Frontmatter.checkImageAltTextwarns rather than fails; see the accessibility convention for why. - Author-written dead links inside article bodies, reported by
BuiltSite.javarather than failing it. Three clusters: bare domains with no scheme, WordPress artifacts (_wp_link_placeholder,/wp-admin/…), and/wp-content/uploads/paths never localised, including two.mp4s and a PDF simply absent from the build. - Some external image references are unrecoverable — dead, behind a bot wall, mermaid.ink 503s, connection failures, and live CI badges, which are deliberate. Each is named with its post in the sweep's report.
worker/views/wrangler.tomlstill has a placeholderdatabase_id, so awrangler deployfrom this repo would not work. It was deployed by IT.- The two branch-protection deviations above want a decision: one ruleset instead of two, and required approvals at 1 instead of 0.
- Hotjar (
hjid2547610) and Reo.dev (b38cec169d83063) ran on the WordPress site and were deliberately not carried over. Decide separately.
A lesson worth keeping from a gap that closed: /java-terms-explained/ looked complete
because the WordPress index is paginated and lists only some of them.
terminology-sitemap.xml was the honest count. Check a sitemap, not an index
page, if anything here is ever compared against an archived copy of the old
site.
-
The site targets WCAG 2.2 AA, and
/accessibility/is the public statement of where it actually is. Not a legal deadline — foojay.io is very likely outside the European Accessibility Act's scope — but it is an Azul-branded property procurement asks about, and a Java-developer audience browses with a keyboard. Keep that page's "not there yet" list honest and update it when a gap closes.Seven things are load-bearing, each a measured failure before it was a rule:
--focus-ringis its own token, and in light it is NOT--brand-accent(2.02:1 on white, so the one cue a keyboard user navigates by was invisible). Dark keeps the accent at 8.57. Never writeoutline: none.- A link in running text is UNDERLINED (
.prose a) — no blue foojay owns clears 3:1 against both the body text and the page. Write it as a bare.prose a, never a chain of:not()s: each adds its argument's specificity and beat every exclusion (every champion avatar kept theirs). - Anything hidden off-screen must leave the TAB ORDER too.
visibilitydoes it; descendants useinherit, notvisible, or they climb back out of the fix. - A thing that covers the page is a modal: focus in, trapped, and
returned.
nav.jsandlightbox.jsdo it by hand;/calendar/'s dialog gets it free from native<dialog>, which is the better route. - A click handler on a non-focusable element is a mouse-only feature. Where an image is inside a link, bind the LINK.
- Anything moving for more than five seconds needs a visible pause
(2.2.2). A hover/focus pause is not one — a pause a mouse movement undoes
is not a pause, hence
stoppedinad-carousel.js. - A sideways-scrolling box needs
tabindex="0", and a table wide enough to need one must be in a box at all, or the whole page scrolls sideways.
Frontmatter.checkImageAltTextWARNS, it does not fail — the one check that doesn't. Whetheris wrong depends on whether the image carries meaning, which nothing there can see, and failing would block a first-time contributor over a judgement call whose predictable answer isalt="image"— worse than empty.pr-check.ymlpasses--changed-sinceso an author sees their own post, not the imported backlog.
-
Images have a per-file budget, and the deploy is why. The built site once went over GitHub Pages' hard 1 GB artifact limit, and that warning lands on a run that otherwise goes green. Check the built size before assuming there is headroom. An image a PR adds or changes over 2 MB fails the PR check (4 MB for what is already there).
JPEG, not WebP, for large PNGs — Frank's call; q85 saves most of what WebP does, either clears the limit, and JPEG is what nearly every other image already is. The hard limit is transparency: the files that genuinely use alpha stay PNG, which is not the same as having an alpha channel (many WordPress PNGs are RGBA with every pixel opaque). The
--png-minfloor is 100 KB, and it is what makes the policy self-selecting — a flame graph was measured and DECLINED, because flat line art compresses better as PNG.Four lessons from
cleanup/images.py, all of which cost real damage:- Finish each bundle before starting the next. Rewriting references at
the END let a mid-run commit capture converted files pointing at deleted
.gifs — 4 broken images on the live site. - Never unlink a source unless the destination is verified on disk. Two disagreeing thresholds lost two GIFs, recovered from git.
- Encode to a temp path and rename. A killed run left a 0-byte
.webpthat the "destination exists" guard then treated as real. - Do not verify an animation by exact frame count. libwebp merges duplicate frames heavily; the floor is 20%, catching gross truncation only.
rewrite_in_bundlematches WHOLE FILENAMES. A plainstr.replacecorrupted two posts: one bundle holds bothdummies.pngandimage-764x1024-dummies.png, so converting the first rewrote the suffix of the second. Audit every local image reference after any bulk image pass — a reference to a file that is not there is invisible in a build log. - Finish each bundle before starting the next. Rewriting references at
the END let a mid-run commit capture converted files pointing at deleted
-
Every image a post references is stored locally, and an external one is named
<stem>-<8 hex of its URL>.<ext>. Hotlinking spends a stranger's bandwidth, leaks each reader's IP, and dies without telling us — many hotlinked images were already dead at import. The hash is not decoration: bundles reference an external URL whose basename is already a file in that bundle, so without itFiles.existsshort-circuits and the page silently shows a different picture. A foojay-hosted image keeps its bare basename.Four rules govern anything added by hand now:
- Lookup is by STEM, ignoring extension, which finds a file later re-encoded and copes with external URLs that carry no extension.
- What came back has to BE an image. A dead URL rarely 404s cleanly — it
serves a login wall or placeholder with a 200, and writing that as
foo.pngturns a visibly broken image into one that looks localised. - WordPress's emoji images are restored to the CHARACTER, since the alt text is the character itself.
- A GitHub Actions
badge.svgstays hotlinked (5 incontent/) — it reports whether a build passes now. That is the whole exclusion list.
Shrink BEFORE the file enters the repo: nothing rewrites git history, so a full-size blob downloaded into
content/is there for ever. -
A body
<h1>is the author's heading. A bareh1in the scraper's noise selector, meant to drop the repeated title, removed hundreds of headings across over a hundred posts — and the text under a deleted heading stays, so articles silently read as one slab with nothing downstream able to tell. Only an h1 repeating the TITLE is removed; the rest are demoted to h2, sincetitle:is already the page's h1.
-
Idempotency everywhere: any script touching
content/must be safe to re-run. And a re-run must not produce a diff that carries no information — a large diff is what the next real change hides behind. Hence: write a data file only when its content changed, not when a timestamp moved; and emit a key only when the script could ever have filled it (gitlab:is omitted where empty, butbluesky: ""stays, because that genuinely means "we looked and there was no icon"). -
URLs are load-bearing. Every converted post, author and page keeps its legacy path via
aliases:(and an expliciturl:for pages) — don't restructure a URL without adding one. WordPress ran a redirect layer on top: The concrete rules arealiases:incontent/(chains resolved to their final destination, since an alias aimed at another redirect is one search engines discard), and a few regexes are Cloudflare config inREDIRECTS.md—^/blog/(.*)(foojay's original scheme),^/almanac/(jdk|java)-…and^/docs/(.*). Some export rules were deliberately skipped because their targets 404 on WordPress too.Three post URLs carry an emoji
aliases:entry written as the literal character, becausestripEmojiremoved it from the folder name. One deliberate exception: heading fragments. WP's#h2-N-sluganchors are gone, so pre-cutover deep links land at the top of the post. Accepted knowingly. -
Every page self-canonicalises, and
canonical:means "not ours".$selfis not.Permalink— on a paginated list that is page 1's URL for every pager, so/today/page/2/and every category pager declared themselves duplicates of page 1, asking Google to drop the only crawl path into the archive. The only legitimatecanonical:points at a different page or site: the cross-posted articles, and/download/.A cross-post canonical rots, and a dead one is worse than none — it tells Google the real version is at a URL that 404s. All of them were re-checked and the dead ones removed. The affected posts are
frozen: true, and that is the fix — an identical audit a week earlier removed the same ones and a re-scrape put every one back. Two traps if it is ever re-run: a 4xx from a bot wall is indistinguishable from a deleted page (Medium flip-flops 403/410 on the same URL, so probe four times and record all four), and check with two clients before believing a failure, and probe a redirect's TARGET rather than the chain. -
A headerless table is stored with an EMPTY header row, and
render-table.htmlomits the<thead>when every header cell is blank. GFM cannot express a table without a header, and Flexmark handed a headerless WordPress table emits a delimiter row with nothing above it — which Goldmark does not recognise as a table at all, so over a hundred tables rendered as a wall of literal pipes. An empty header, not promoting the first row: only a quarter have a first row that is actually a header, and promoting a legend turns a data row into a heading. -
Headings are stored as ATX (
##), not setext underlines. Levels map 1:1 to the original, and a setext underline heads the whole paragraph above it, which had three posts rendering prose inside their<h2>. Don't reintroduce----underlines. -
Code blocks are stored as Markdown fences and rendered as EnlighterJS.
_markup/render-codeblock.htmlturns a fence into the<pre class="EnlighterJSRAW">the vendored initialiser looks for; Hugo's own Chroma highlighting is bypassed. Storage and presentation stay separate so swapping the highlighter means editing one file, not 1000 posts. The hook maps fence tags to the languages in the vendored bundle — that list is derived by reading the bundle, not from docs, after a hand-written version silently rendered hundreds of blocks asgeneric. There is noenlighterjs:flag: detection covers every case, and defaulting it to true would pull the whole highlighter bundle onto every page with no code. Don't reintroduce one, and don't put raw<pre class="EnlighterJSRAW">intocontent/.Check the fence balance after any bulk content pass. A file ending inside an unclosed fence is invisible in the source and Hugo builds it without a word — 7 posts were live with everything after their last code sample rendered as one grey slab.
-
Mermaid diagrams are a
```mermaidfence, vendored and lazy. The hook branches on the tag before the EnlighterJS path (mermaid is not in$supported, so it would otherwise render as highlighted source), andbaseof.htmlloads the library when the RENDERED page contains one — so nomermaid:flag either. It is the ESM build (a small entry plus chunks, against a multi-MB UMD single file), which is whystatic/vendor/mermaid/is a hundred-odd files; update withnpm packand copy the entry plusdist/chunks/…, no.mapfiles.Four things are load-bearing:
htmlEscape+safeHTML(diagram syntax is full of-->and<br/>); the source is stashed indata-mermaid-sourcebefore rendering, because mermaid replaces the text with an<svg>and a theme flip needs a re-render; the CSS keys on mermaid's owndata-processed, since the<pre>survives and would otherwise keep code-block styling; andsuppressErrors: truewithsecurityLevel: "strict". -
AsciiDoc is a first-class content format: name the file
index.adoc. Everything else about a bundle is identical — same frontmatter, same images alongside, same PR checks.template/post.adocis the starter file. Rendering goes out to theasciidoctorbinary, whichhugo.toml's[security.exec]must allow (naming one binary REPLACES the default list, so all five are repeated there) and whoseGEM_HOME/GEM_PATHare inosEnvbecause Hugo hands the child a filtered environment.Hugo's render hooks are a Goldmark feature, so an AsciiDoc article gets none of them.
partials/article-html.htmlrewrites asciidoctor's HTML afterwards to close that gap, and is called frombaseof.htmltoo — which is not optional, since baseof decides whether to load mermaid by looking for markup this partial creates. It does four jobs: code blocks become EnlighterJS or mermaid elements (through the same language registry the Markdown hook uses, so the two cannot drift); root-relative and absolute foojay.io links get the baseURL subpath; external links gettarget="_blank", so the two formats agree on what a link to another site does (AsciiDoc's own^suffix still works and is left alone); and callouts become circled digits, because EnlighterJS re-renders a block from itstextContentand would otherwise print the marker's markup literally. -
A runnable snippet is the
{{< jdoodle >}}shortcode, whose.Inneris the code and whosefiles=names data files kept once inassets/jdoodle/.template/post.mddocuments it for authors. The loader is derived with.HasShortcode, so there is nojdoodle:flag — same rule as the EnlighterJS and mermaid loaders.It replaced hand-written HTML embeds that had drifted into four shapes, and the shortcode exists because three separate things silently corrupt a payload read as
textContent:hugo --minifycollapses a whitespace run outside<pre>, which had stripped every leading space from every snippet on the site (keepWhitespace = truedoes not fix it — measured — and costs +1.9 MB); a blank line inside the code ended the surrounding CommonMark HTML block and handed the rest to Goldmark; and<xmp>is not a<pre>, being RAWTEXT, soList<Person>reached the compiler literally. Inner text never reaches Goldmark now, leaving only the escaping —htmlEscapethensafeHTML, once, exactly asrender-codeblock.htmldoes.A data file is at
/uploads/<name>inside the sandbox, which is the path the snippet opens. Two tutorial steps read the sametestdata.csv, which is why it lives inassets/rather than being pasted into both.No
data-version-indexand noclientidparameter. The client id is foojay's own and identical everywhere, so it is a constant in the shortcode rather than a knob set to one value. The version is omitted entirely: the plugin readsdataset.versionIndexandJSON.stringifydrops it when undefined, so leaving it off means JDoodle's current default — which is what a tutorial teaching Java wants, and what the pins it replaced (4 and 6, both years stale) had stopped being.Verify a change here by extracting the payload from the BUILT, MINIFIED HTML exactly as pym does —
textContentof the div, or of its[data-type=script]/[data-type=file]children whendata-has-files— thenjavacand run it. Nothing static can check this: indentation loss, an undecoded entity and a truncated snippet all build green and fail only inside somebody else's iframe. The conversion was verified that way, every payload byte-identical to what the old markup produced.The two posts that explain JDoodle keep raw HTML inside code fences as documentation samples. Those are inert and deliberate; don't convert them.
-
Email addresses are decoded on the way in, never left obfuscated. Cloudflare's Email Address Obfuscation turns every address into a placeholder plus an XOR-encoded copy. Two rules: a decode that isn't an address becomes text rather than a link (the matcher has false positives like
setup-java@v5.5.0), and an address inside code is always plain text, or--docker-email="a@b"becomesmailto:a@b. -
WordPress's decorative
<hr>s and<br>spacers are dropped, not converted — they carried styling the WP theme supplied. A<br>with text on its line is a real hard break and stays. -
Posts are filed by publish date (
content/posts/<y>/<m>/<d>/<slug>/), purely to keep a directory of thousands of posts browsable. It has no effect on the URL. -
There is no
tagstaxonomy, deliberately. WordPress tags its posts but never renders them, so the scrapers never saw one and every post landed with an emptytags:— no term pages, against categories' hundreds. All of it was removed. Categories are the taxonomy. -
Emoji come off post TITLES, never out of bodies. A title is the card, the RSS item, the browser tab and the
og:title. Bodies are untouched: hundreds of posts carry thousands of emoji, among which arrows,(TM)and comparison-table check marks are load-bearing. The rule is\p{IsExtended_Pictographic}plus skin tones, keycaps, variation selectors and ZWJ — not\p{IsEmoji}, which is true for ASCII digits and would eat the "5" out of "The 5 Knights". -
related_postsis manual, chosen by the author — never replace it with an automated similarity algorithm. Four entries is the house convention. -
Galleries are the
{{< gallery >}}shortcode, migrated posts included: one filename per line,| caption,| |before differing alt text, plus optionalcols=andcaption=. The template derives the link to each image's full-size original from the thumbnail name. Don't reintroduce WordPress block markup. -
render-image.htmlemitswidth/height, and only for rasters — without them every image in a long post shoves the text below it down as it decodes. The check is on.MediaType.SubType, notResourceType: Hugo reports an SVG as an image but.Widthon one halts the build. -
render-link.htmlresolves page-bundle resources, the same wayrender-image.htmldoes. Without it a link to a PDF or zip in the author's own folder resolved against the SITE ROOT while Hugo published it inside the bundle — over a hundred internal links were dead this way, unnoticed becauseresolved and[handout](handout.pdf)did not. -
Render hooks must redo the escaping Goldmark would have done. Two live shapes:
render-codeblock.htmlneedshtmlEscape .Inner | safeHTML, or html/template escapes a second time and->reaches the reader as->(about a thousand posts);render-link.html/render-image.htmlneedhtmlUnescapeon.Destination/.Title, or?a=1&b=2becomes a param namedamp;b(about a hundred posts). Check both when editing a hook.
See themes/foojay/AGENTS.md, which also holds the template- and
JS-level notes for the sections below.
-
The calendar has two sources, split on "does it publish a feed?" JUG meetups sync daily into
data/jug-events.json; a conference has no feed, so those are hand-added, one file per event,data/events/<slug>.yaml.template/event.yamlis the schema andFrontmatter.checkEventsthe check. Three things: the generated file isjug-events.json, notevents.json, because Hugo mergesdata/events.jsonanddata/events/into one key; one file per event, never a shared list, so two contributors never touch the same bytes; and nothing has to be deleted, since the layout drops an event the day after it ends.checkEventsenforces a closed key set — data files are not content, so Hugo says nothing aboutwebsite:instead ofurl:, and the event just renders with a piece missing. -
Scheduling a post is a future
date:, and nothing else.buildFutureis false, so a future-dated post is skipped entirely — no page, no entry in any list, feed, sitemap or search index. That is already the right semantics, so there is noscheduled:flag and nodraft:mechanism; publishing is a maintainer movingdraft/<slug>/intocontent/posts/<y>/<m>/<d>/.Four pieces make it work, three because the default breaks something:
partials/scheduled-posts.htmlreads pending posts OFF DISK (the home widgetcoming-soon.htmland/today/coming-soon/both render its list), since no template canrangea page that was never built. It is the home page aside widget: four directory listings per build, not a walk of every post. Titles are plain text, not links — the page does not exist yet..IsHomeis checked insidebar.html, which also bounds the cost. The byline isbyline.htmlgiven slugs instead of a Page (that input exists for this caller), so faces and names here cannot look or resolve differently from a card's.buildFuture = trueis the trap: it would need awhere .Date "lt" nowin every list, term, feed and JSON-LD template plus the Pagefind body, and ONE missed spot publishes an embargoed article early, silently.BuiltSite.javawould otherwise BLOCK THE DEPLOY, since it asserts a built page for every source — so scheduling a post would take the site down from the moment it merged.isScheduled()skips future-dated sources, and the count is printed next to the built one.Frontmatter.checkPostDatesenforces two rules. A post'sdate:must MATCH its folder — the folder is the visible half but thedate:is what Hugo publishes off, so a draft moved into October with August still in frontmatter goes live immediately, filed eight weeks back where nobody sees it, every check green. And a future-dated post carries no time.publish-scheduled.ymlis what causes the build.
The publish time is not the author's to choose. Everything goes out on the one daily build, so a scheduled post is dated
YYYY-MM-DD— midnight UTC, giving that build seven hours of slack. Actions cron is best-effort and never fires early, so a time cannot make a post publish sooner and can only make it LATER:09:00is still in the future at the 07:00 build, so the post misses its morning and lands at whatever deploy happens next. Hence a hard PR failure. Don't move the cron earlier to make publication "more punctual" — it cannot be, and the slack is what stops a late run publishing on the wrong date.The dispatch window starts at the LAST SUCCESSFUL deploy, not 24 hours ago, which is what makes it self-healing: a skipped run still reaches back past the post it missed, and a 03:00 human push means the window correctly contains nothing. Bounded to 14 days, and it says out loud when nothing is due, because "nothing was due" and "the scan is broken" are otherwise the same green run.
Two things worth not rediscovering: a frontmatter reader must stop at the closing
---(one post has elevendate:lines in its body at column 0), and YAML erases the distinction the no-time rule polices, so the check reads the RAW line. -
A multi-page series is a folder of pages with a
weight, and nothing else.partials/series-steps.htmlis the single definition; the progress bar and the previous/next cards derive everything from it. Both render nothing when the page has no weight, which is load-bearing: the fiveinstall-java/pages are alternatives, not a sequence, so they correctly get no navigation.checkSeriesWeightsfails the PR on two pages sharing a weight, since Hugo's stable sort would silently mis-order them. -
/java-quick-start/other-tutorials/is tiles from a frontmatter list. It deliberately does not copy the board's folder-of-pages mechanism: every entry exists to send the reader elsewhere, so a page each would mint a URL, a view key and a file to hold four fields. -
A page must never list its own
url:inaliases:, andcheckSelfAliasesfails the PR. Dozens of pages carried one, and on two it had taken the page off the air — Hugo wrote the redirect stub OVER the real page, so/java-quick-start/served nothing but a refresh pointing at itself. The rest happened to win the race, which is exactly why this is a check and not a one-time cleanup. -
/team/and/community-support/are gone, and both taught the same lesson./team/was the web agency's profile, not foojay's team; its aliases moved tomeet-the-team.mdand its view key was remapped./community-support/was an alias of/our-sponsors/that the scraper had followed and stored as a page — and itsurl:collided with the section's ownaliases:entry, which Hugo does not warn about, so the stub built into no page at all while still appearing in both sitemaps. Check for aurl:collision when a page renders as nothing. -
WordPress's placeholder title/description are not metadata — replace them on sight. Yoast served one title and one description for any page it had nothing for, so 7 pages shared an
<h1>and 8 shared anog:description..Titleis the page's H1 and half its<title>, so a placeholder is visible twice on every affected page. -
Sponsor folders can be renamed; the WP URL still has to work. Each bundle records
wpSlug:, and analiases:entry is emitted when folder andwpSlugdiffer. Never hand-edit those two fields. -
Sponsors ↔ articles is an author list, hand-maintained. Each sponsor bundle carries
authors:, andpartials/sponsor-posts.htmlis the single definition — the grid, the counts and "Topics covered" all derive from it, so nothing goes stale. Our numbers legitimately differ from WordPress's, because author-based attribution is broader; narrow the list if a sponsor should own fewer posts.An entry can be date-bounded, because people change employer — either a bare slug or a map with
from:/till::authors: - "tim-kelly" # still there: nothing to say - slug: "pratik-patel" till: "2026-04-01" # the day they left
The bare string stays the default because it is the common case. Four things are load-bearing: the range is half-open
[from, till), so the same date is correct for both employers with no gap and no double-attribution; a post counts when it is inside the window of AT LEAST ONE author, so a co-written piece is still the sponsor's; dates go throughtime.Formatbefore comparison, since YAML turns an unquoted date into an object and a quoted one into a string and comparing the two silently fails; and the entry key set is closed, sinceuntil:fortill:would be ignored with nothing saying why. -
Featured Authors are two slugs in
hugo.toml, and nothing else. The pick rotates monthly and lives in an editor's head — case 3 of the rule. Everything on display is derived. Don't add afeatured: truefrontmatter flag: that is two files to edit per rotation and two to remember to unset, which is how an author silently stays featured for ever. -
The glossary's folder is
content/pedia/but its URL is/java-terms-explained/, and/pedia/…survives as an alias on every entry. Templates reach it throughsite.GetPage "/pedia", never a literal path. -
A pedia entry is: prose, then optional "More reading on Foojay:", then
## See Also. The two blocks mean different things — More reading links ARTICLES, See Also links other GLOSSARY TERMS. Headings start at##. The See Also lists are derived in three tiers (the entry's own links, then entries linking to it, then its topical group, only to top a short list up to three), capped at six, and root-relative. A pedia image lives instatic/images/pedia/<slug>/, never hotlinked — entries are single files, not bundles, so there is no folder to co-locate a resource in. -
The Advisory Board is a folder, not a list. Each member is a page at
/board/<slug>/, andpartials/board-members.htmlis the single definition — the grid, the organisation count and the "other members" strip all derive from it. Adding a member is one file plus a logo. It stays a landing page undercontent/pages/rather than becoming a section, because the page has a large WordPress view count under thepages/boardkey and a section would have renamed it. Logos carrylogoBackgroundfor the same reason sponsor logos do. -
Paid home page banners are page bundles under
content/ads/, one per campaign, so a banner's creative sits next to its copy (template/ad.mdis the schema,Frontmatter.checkAdsthe check). It is a campaign model, not a sponsor one — one sponsor runs many banners a year, each with its own creative and date window — which is why this is not in the sponsor bundles. Three settings incontent/ads/_index.mdkeep a banner from becoming a page, all verified against a real build:render: never(no URL, no sitemap entry, nothing for Pagefind),publishResources(without itrender: nevertakes the creative with it and every slide silently loses its picture), andlist: local.expiryDate:retires a campaign on its own;sponsored: falseis for foojay's own promotions, which carry no "Sponsored Content" label. -
The read counter is ours, first-party, and keyed
<section>/<slug>. Three reasons, all of which have to hold: privacy by construction (the Worker receives a slug and stores a slug and an integer — nothing to anonymise); first-party, so the number is true (a third-party analytics domain is blocked for a large share of an audience of Java developers, and the count would silently run tens of percent low — the one failure a published number can't have); and one number, not two (WordPress's count is thelegacycolumn, live views accumulate inlive,/allreturns the sum, so no template adds them and there is nolegacy_views:field).Counting and displaying are separate.
views-beacon.htmlposts the slug withsendBeaconand renders nothing unless[params.views] endpointis set, so a local build never counts. The number shown is baked into the HTML fromdata/views.json— no JavaScript, and it works on cards, which a per-page fetch cannot. Up-to-a-day-stale is not a defect in a view count.partials/views-key.htmlis the single definition of what gets counted and under which key, followed by the display, the beacon and the import; drift between them shows up as a number that silently stays at zero. The Worker validates the key's shape rather than an allow-list, so a forgotten redeploy can't drop a whole section. A combined total isviews-total.html, a build-time sum, so an author's total cannot disagree with the cards below it. Author pages have no WordPress baseline and started at zero — don't go looking for the import that "must have failed". -
Third-party analytics is the GTM container
GTM-M6ZT5NW.partials/analytics.html(head, as high as possible) andpartials/analytics-noscript.html(straight after<body>) are the only places the site asks a browser to run someone else's code. Both render nothing unless[params.analytics] gtmis set, so a fork or a local build reports nothing.The GA4 id appears nowhere, and a grep will tell you the site has no analytics. The container fires Universal Analytics tags on
UA-726113-5, which Google resolves server side toG-GS21L12HYKthrough its UA-to-GA4 connected site tag. Verified in a browser: the hit is/j/collectwithtid=UA-726113-5and agjid, which is that bridge.Loading GA4 directly instead is what broke analytics at cutover — it needed Consent Mode defaults, Ketch's
googletagplugin is present but empty on this property, so nothing ever sent the update and every hit went outgcs=G100. There are nogtag('consent', …)defaults now, and azul.com has none either; gating is Ketch's own, not Consent Mode's. Restoring the container fixed it, confirmed live in GA on 2026-09-23.The container also injects Ketch, so
[params.analytics.ketch]is commented out — setting it loads Ketch twice. Worth fixing the other way round: azul.com loads Ketch from the page, first thing in<head>, ahead of its container, and its container carries no Ketch tag (checked). Delete the Custom HTML tag in the GTM console, then uncomment.A comment meant to reach view-source must go through
printf | safeHTML— Go'shtml/templatestrips HTML comments out of a template.GA4 and
data/views.jsonwill never agree, and GA4 is always lower. That is not a bug in either. Google's collection domains are on Firefox's Enhanced Tracking Protection blocklist, strict by default in private windows, and every adblocker does the same — observed live, not assumed. The read counter is first-party and indistinguishable from the rest of the site. The two count different populations: don't reconcile them, don't swap the view counts for GA4 numbers because GA4 looks more authoritative, and don't treat a growing gap as drift. Also: a consent test in a Firefox private window measures ETP, not consent. -
Posts are contributed via PR (see
CONTRIBUTING.md); the repo is public.