Every CalCOFI.io product is a card on calcofi.io, and the card is the record: its name, its section, where it lives, where its source is, its uptime history and its usage. This page lists them from that record and states the three small contracts that keep a product findable and recognisably CalCOFI’s. For the data team and anyone building a new one.
Every product
Table 14.1 is every card on the landing page, by section, with where the product lives, where its source is and how it is doing.
The ship’s log
calcofi.io/news merges four kinds of entry into one history, newest first — releases, datasets entering the release, new products, and hand-written notes — generated by _plugins/news.rb in CalCOFI/CalCOFI.github.io and republished as the Atom feed /feed.xml; the header’s News link wears a dot while any entry is under 30 days old. Three of the four are read off records this book already reads; only the fourth — a feature, a change to the site, a paper — is typed by hand, in the site’s _data/news.yml. A hand-written row carrying version: or dataset_key: replaces the generated entry of that key, for when the generated title is not the story.
Table 14.2 is what each kind is: its source, who is responsible for it appearing, when it shows up, and where it sends a reader — with how many of each this snapshot carries.
The three-slug contract
A product is one thing in three places, and it is the same string in all of them:
- its
key in the landing page’s products.yml (the card);
- its
slug in CalCOFI/uptime’s monitor list (the status page at status.calcofi.io/history/<slug>);
- its
slug in CalCOFI/analytics’ registry (the usage report at calcofi.io/analytics/<slug>/).
When the names diverged, none of the three was findable from the others. Cards are named for the thing itself — the repository or application name used everywhere else — except student contributions, which keep their human titles. The card’s status is its lifecycle (interim, superseded, archived), not its uptime; a superseded card names what replaced it, and the Explore chapter reads exactly that.
The brand contract
Every product wears one theme, one header and one favicon, and the rule is checked weekly rather than assumed. The contract is calcofi.io/brand/v2 — the SIO look, light by default, UCSD’s palette, Source Sans 3 and Teko, the horizontal lockup — and in one breath:
?theme=dark|light on any URL sets the theme, remembered across products only when a person chose it; a fresh visit is light.- The header is one bar: the lockup (the mark and the wordmark “CalCOFI.io”) at the far left links to calcofi.io, the product’s own name beside it (“Explorer”, “Query”, never “CalCOFI Query”) links to its own root, the theme toggle sits at the right. Where a framework owns the bar (Quarto, pkgdown, MkDocs, Shiny), the lockup goes in its brand slot and its toggle is bridged.
- An application declares its scale (
<meta name="cc-scale" content="app">); a page declares nothing and gets the reading rhythm. This book is a page.
?tour=off suppresses any guided tour, so live_url?theme=<t>&tour=off is a deterministic screenshot; every card carries a light and a dark shot taken that way.
calcofi4r::cc_brand_head() and cc_brand_header() give a Shiny app the head block and the bar; the Quarto sites include the same head file; check_brand.py in the landing repository probes every product for the theme, the favicon, the home link, the toggle, the version and the default.
Adding a product
- Build it on the release: read through the catalog (Access the data), never a typed path; apply the quality predicate; cite through
cc_cite().
- Wear the brand (above); honour
?theme= and ?tour=off; take the two screenshots.
- Add the card to
products.yml with its section, its datasets (the keys it covers, or all) and, if it opens a dataset directly, the dataset_url template the dataset pages link through.
- Add the same slug to the uptime monitors and the analytics registry, and tag the page for analytics.
- Push; the landing page, the status page and the usage report rebuild themselves, and this table follows.