site

The landing page for katoptra.org, and the mark of each katoptra repository.

This repository is a Hugo site. It shows each mirror as a tile, below a Public / Private switch. The Public group has the public mirrors. The Private group has the private mirrors, which copy the owner's accounts. Each tile shows these items:

• The upstream
• The cadence
• The repository
• The status
• The age of the last sync.

The page gets the status and the age of the last sync when it loads. Cloudflare Pages deploys the site at each push to main, and it also publishes the files in The brand.

How it works

1. Shell. themes/katoptra/ is the shell of a katoptra page: the masthead, the footer, the head, the 404 page, the base CSS and the files in The brand. The site root has the mirror index: the tiles, the switch, the status script and the data.
2. Data. data/mirrors.toml has one entry for each mirror. It supplies the data for the homepage tiles and the ItemList JSON-LD. Thus, to add or remove a mirror, you edit that file and no other file.
3. Status. When the page loads, assets/js/status.js reads the healthchecks.io JSON badge of each mirror and the runs of its sync workflow on GitHub Actions. The script makes a tile red when its sync is late, and it shows the age of the last sync. It also fills two bars and the words under them: the runs bar has one segment for each of the last 10 runs, and the next-sync bar fills until the next sync. If the script cannot fetch a source, the tile stays neutral, the age and the words stay a dash, and the bars stay gray. The pipeline of each mirror pings a healthcheck at the end of each run, and the badge shows the result (katoptra/lib gives more data).
4. Deploy. At each push to main, Cloudflare Pages runs hugo --minify --gc.

The brand

The mark is two chevrons that point to a hairline:

• The upstream, on the left side, in one ink
• The copy, on the right side, in a second ink
• The mirror plane, which is the hairline between them.

The mark is on a rounded tile that stays dark in the light theme and in the dark theme. Thus, one file is correct for a light page and for a dark page. The font is Gabarito. Its rounded terminals agree with the corners of the tile and with the caps of the chevrons. The palette has these colors:

• A warm off-white background and a near-black background
• A gray ramp for text
• One blue-violet for links.

brand/build.py is the one source of the brand. It has the geometry and the two palettes, and it makes each brand file from them. Each file that it writes is in git, and katoptra.org serves it. Thus, a README in a different repository refers to the URL, and it does not keep a copy.

File	Served at	Use
katoptra-mark.svg, katoptra-mark-dark.svg	/brand/	The mark on its tile, for a light page or a dark page
katoptra-mark-224.png, katoptra-mark-dark-224.png	/brand/	The same at 224px, for READMEs at a width of 112
katoptra-mark-1024.png, katoptra-mark-dark-1024.png	/brand/	The same at 1024px, for larger images
katoptra-avatar.svg, katoptra-avatar.png	/brand/	The mark on a full-bleed square, for the GitHub org avatar and for each surface that has rounded corners
tokens.css	/brand/	The palette as custom properties, light and dark
favicon.svg, favicon.ico, apple-touch-icon.png	/	The icons of the site
images/og.png	/images/	The 1200x630 unfurl card

Each repository README in the org starts with the mark, as a link to the organization. The two READMEs in .github do not. This is the HTML:

<p align="center">
  <a href="https://github.com/katoptra">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://katoptra.org/brand/katoptra-mark-dark-224.png">
      <img src="https://katoptra.org/brand/katoptra-mark-224.png" alt="Katoptra" width="112">
    </picture>
  </a>
</p>

To change the mark or a color:

1. Edit MARK, LIGHT or DARK in brand/build.py.
2. Run task brand.

If the committed files are different from the files that the script makes, task check gives an error. Thus, the artwork always agrees with the script.

task brand:fonts makes the font files in themes/katoptra/static/fonts/. It fetches Gabarito from google/fonts at a pinned commit, and it subsets the font to latin. The license of the font is in the same directory.

Want your own?

These files identify this site:

• static/llms.txt
• themes/katoptra/static/site.webmanifest
• static/robots.txt
• static/.well-known/security.txt
• The footer, in themes/katoptra/layouts/partials/footer.html
• brand/build.py, which makes the mark.

To make a site for your mirrors:

1. Fork katoptra/site.
2. Replace the entries in data/mirrors.toml with your mirrors.
3. Set baseURL in hugo.toml to your domain.
4. Write new versions of the files in that list.
5. Put your mark in brand/build.py.
6. Put the site on a web host that you select.

Hugo builds the site to a static site, which all web hosts can serve.

Operating it

task               # the menu
task serve         # local dev server with drafts and watch
task check         # brand files match a rebuild; build; fail if any mirrors.toml URL is missing from the page, the social card is absent, or the JSON-LD does not parse
task brand         # rebuild every brand file from brand/build.py
task brand:fonts   # re-fetch and re-subset Gabarito (network)

For a layout change, look at the rendered page in the light and the dark color scheme. Do this at desktop width and at approximately 390px. Make sure that the full page shows in a 1440x900 viewport without an internal scroll. Make sure that no element overflows horizontally at 390px.

Pull requests are welcome.

MIT licensed. Built by Josh Vaughen.