Skip to content

Features

Jump to bottom
Will Luck edited this page Nov 1, 2026 · 1 revision

Features

This page explains what each part of Waymark shows and the rules behind it. Back to the README.

Contents

What it shows

Waymark shows each project's state, what is waiting on you, versions and deploys, CI, issues, plans in progress, a ship log and a map.

Nothing on the page is typed in by hand: every state comes from the forges, and optionally from a Docker host, HTTP probes, F-Droid and a notes folder.

Project states

Every project is in one of six states. The overview lists them in this order.

State What it means
Active Commits in the last 3 weeks
Live Running and answering, no recent commits
On hold Parked or frozen on purpose (shown as Parked or Frozen)
Quiet Some commits in the last 4 months, nothing running
Dormant No commits for 4 months or more
Archived Retired or archived

Active, Live and On hold start open on the overview; the other three start folded.

The overview

  • Count tiles: Projects, Active, Live, Needs you, Open issues (with the open PR count) and Shipped in 30 days. Most tiles jump to their section, or to the ship log.
  • Commit strip: one bar per week for 53 weeks. It links to the ship log.
  • Needs you: up to 8 cards, the rest behind "Show N more". See Needs you.
  • Since you last looked: what changed in the last 7 days, grouped by project. With JavaScript it shows what is new since this viewer's last visit, up to 14 days back (a return within 30 minutes is the same visit; at most 12 show, then "Show all").
  • All projects: category filters, then one section per state. Each card shows up to 5 chips (such as running version, CI, issues and PRs) and a 12-week commit sparkline.

How projects form

  • Every tracked repo that the projects file does not claim or hide becomes a project.
  • A repo with the same name on two forges becomes one project: the first forge holds the primary (tags, releases, CI, plans), the second is a mirror (stars, its issues, its latest release).

Needs you

These rules feed the overview's Needs you list, and each project's "Waiting on you":

Verb When
Fix A project's main container is stopped, or one the projects file names is missing; a urls: probe from the projects file is down
Deploy The running container's version (or the F-Droid build's) is older than the newest version tag
Review An open PR, not a draft, with no update for 2 days; a PR that asks for your review (needs_you.review_requests)
Confirm A project on hold has commits since the hold began: still parked?
Decide An open issue or PR with a needs_you.labels label (needs-you, decision); one assigned to you (needs_you.assigned); a notes item
  • "You" on each forge is the token's user.
  • To flag something as waiting on you, with no notes at all, label it or assign it to yourself.
  • Failing CI shows on the project's card and page, not in the list.

Settings: needs_you.

Where it runs

Containers are optional. With a Docker source, "Where it runs" shows each project's containers, their state and running version, and the Deploy rule compares that version with the newest tag. Each probe shows there too, with its 24-hour uptime.

A container belongs to a project when:

  • the projects file lists it;
  • it is named like the project's slug; or
  • its org.opencontainers.image.source label is one of the project's repo pages.

How to connect Docker: Containers on the page.

Notes

Notes are optional (notes.type: none). Mount the folder read-only.

markdown

  • What it reads: any folder of .md files, such as an Obsidian vault.
  • Which project: a file belongs to a project by its name (<slug>.md, or the slug with - as _), by front matter project: <slug>, or by the projects file's notes: list.
  • Decide items: a list item with a marker (WAITING: or @me by default) is a Decide item.
  • The panel: the note's body shows in the project's Notes panel, and its age from front matter updated: or the file's time.

claude-memory

  • What it reads: a Claude Code memory folder: a MEMORY.md index and one file per note.
  • Decide items: a clause that waits on one of your names in site.you ("awaits Mark", "needs Mark", "Mark's decision") is a Decide item.
  • The panel is called "Claude's notes".

Most people want markdown or none. Settings: Notes folders.

Ideas

  • From issues: open issues labelled idea or enhancement (ideas.labels) are ideas, on the Ideas page and each project's page.
  • Kind and size come from kind/* and size/* labels.
  • From a file: an optional ideas file holds ideas that are not issues yet. Each has File as issue, a filled-in new-issue link whose last line is the ideas.marker and the idea's id, so once filed the idea links its issue.
  • When the page shows: the Ideas page and its link show when an ideas file is set up or any idea exists. Otherwise there is no link and the page answers 404.

On the page, filter by kind and size, pick a project, or press Surprise me for a random idea. Settings: ideas.

Plans and changelogs

  • Plans: Waymark reads dated plan files from each primary repo (plans.dirs, by default docs/plans and docs/superpowers/plans): Markdown files named 2026-10-28-new-editor.md, or dated folders with a plan.md.
  • Progress: a plan with some, but not all, of its checkboxes ticked shows under "Next up" as "3 of 7", for up to 120 days from its date; at most 3, newest first.
  • Changelog: a Keep a Changelog CHANGELOG.md adds its Unreleased items.

Settings: Plans and changelogs.

Ship log and map

  • Ship log: commits per day for 53 weeks, with the busiest day and the current streak, then every release of the last 18 months, by month. A deployed release has a running badge.
  • Map: every project as a star, grouped by category. Colour and the corner badge give the state, size gives the last 12 weeks of commits, and lines are relations. Hover or focus a star to light up its neighbours. A plain list by category sits under the map.

Search

Press Ctrl K (Cmd K on a Mac) or / to search projects, ideas, open issues and commands. Letters match in order, so a few are enough.

The commands: Overview, Ideas (when there are ideas), Ship log, Map, Toggle theme, Refresh now and Surprise me.

Live updates

  • No reload needed: cards and project panels change in place, and a short message names each new event.
  • Header status: it says Live, which source is failing, or Reconnecting. Click it to see every source and its age.

Home

Getting started

Using Waymark

Reference

Clone this wiki locally