Benchmarks and race tags¶

The best way to know what kind of shape you’re in is to race! Sports science has turned race results into threshold estimates for decades. Tag a workout page as a race, and fitdocs can derive your equivalent threshold pace (run), threshold heart rate (run, ride), and FTP (ride).

1. Tag the effort on its page¶

Add these keys to the frontmatter of any workout page. Fitdocs doesn’t write these, so they’ll persist through a regen:

effort: race                  # race | test | hard
effort_distance_m: 21097.5    # official distance, in metres
effort_time_s: 4401           # official time, in seconds (1:13:21)
effort_event: "[[Lisbon Half 2025]]"   # optional; any text or a quoted wikilink

Kind	Use it for
`race`	A race result
`test`	A formal test, such as a time trial or FTP test
`hard`	A near-maximal effort that wasn't a race or a test

Use the official distance and time, not what your GPS measured. A course distance only counts together with its time. A timed test can have effort_time_s without a distance.

2. Derive¶

fitdocs derive-benchmarks --dry-run   # show what would be derived
fitdocs derive-benchmarks             # write it to athlete.toml

Here's what fitdocs derives, from which efforts:

Sport	Threshold	Derived from
Run	Threshold pace	Races, using Riegel's race-equivalence model to project your one-hour pace
Run, Ride	Threshold heart rate	Races, tests, or hard efforts, as the average heart rate over the effort
Ride	FTP	Races and tests of the right length, as the average power over the effort

Each result is written to athlete.toml as a dated benchmark, with a note saying which page it came from, which method was used, and which paper the method comes from.

3. Rescore¶

With dated benchmarks going back years, fill in the old pages:

fitdocs load
fitdocs history

Each activity is scored with the benchmark that applied on its date. Then the history page can draw your fitness over your whole archive.

With an LLM: "Go through my workouts from 2023–2025 and find the ones that look like races, based on titles, my notes, and pacing. List them with dates and distances and ask me to confirm official times. For each one I confirm, add the effort, effort_distance_m, effort_time_s, and effort_event frontmatter keys, and change nothing else on the page. Then run fitdocs derive-benchmarks --dry-run and walk me through the report."

More prompts like this are in Working with an LLM.