Eventuate

Extracts information from parkrun event result pages for inclusion in reports. It's not a run report generator, but will help you write a weekly report for an event.

Introduction

I wrote this while volunteering as a Run Director at the beautiful Brimbank parkrun, to make it easy to celebrate our community's achievements on the Brimbank parkrun Facebook page. I am sharing it so that you get to enjoy it too.

I initially wrote this as a Firefox Add-On, as the developer tooling is pretty good in this space and Firefox Browser Add-Ons are pretty easy to distribute. However, once I worked out I could generate a userscript as part of the automated release process and run it in any browser with a userscript manager, including iOS and iPadOS devices, I switched to using that!

Description

If you volunteer at parkrun and produce an event report to celebrate achievements, this addon will make your life easier!

As soon as the latest results page loads for an event, you'll see a bunch of useful text before the results table is displayed, including:

• Weekly event summary
• New milestone club members
• Kudos for new parkrunners
• Welcome for first-time visitors
• Celebrating personal bests
• Acknowledgement of walking and running groups
• Link to the full results
• Gratitude to volunteers
• Invitation to volunteer with a link to the roster
• Reminder to bring a barcode
• Reminder about junior supervision policy for 5km events
• Overall event summary facts and figures

Internationalisation

Eventuate automatically detects your browser's language and displays reports in the appropriate language. Currently supported languages:

• English 🇬🇧 (default)
• German 🇩🇪 (Deutsch)

You can easily switch between languages using the flag buttons that appear at the top of the Eventuate output. Your language preference is saved and will be remembered across browser sessions.

Adding a New Language

We welcome contributions to add support for additional languages! Here's how to add a new language:

1. Create a new translation file:

   # Copy the English template
   cp src/translations/en.ts src/translations/[language-code].ts

2. Translate all strings in the new file. Each translation file contains:

   • Language metadata (flag emoji and language name)
   • Event summaries and introductions
   • Milestone celebration messages
   • Volunteer acknowledgments
   • Personal best celebrations
   • Loading messages and fallback text
   • Milestone club names (e.g., "10 club", "25 club", etc.)

3. Register the new language in src/translations/index.ts:

   import { [language-code] } from './[language-code]';
   
   export const translations: Record<string, TranslationKeys> = {
     en,
     de,
     [language-code], // Add your new language here
   };

4. Test your translation:

   mise run test
   mise run build

5. Submit a pull request with your translation.

Translation Guidelines

• Use British English spelling conventions (e.g., "colour" not "color")
• Maintain the friendly, celebratory tone of parkrun reports
• Keep milestone club names consistent with parkrun terminology
• Test with real parkrun data to ensure translations work correctly
• Consider cultural differences in how achievements are celebrated

Supported parkrun Countries

Eventuate works with parkrun results pages from all countries. Adding translations helps make the tool more accessible to parkrun communities worldwide.

Development status

I wrote this for myself in an afternoon to see if I could do it and figured it may be useful to others. I then spent a while over-engineering it in TypeScript and adding some unit tests using jest.

Building locally

Quickstart

This project uses mise as the single entry point for tools and tasks. aube manages Node dependencies with paranoid mode enabled.

# Prerequisites: mise (https://mise.jdx.dev)
curl https://mise.run | sh

mise install          # node, aube, ruby, hk (from mise.toml)
mise trust            # first time only
mise run setup        # install dependencies
mise run test         # lint + unit tests
mise tasks            # discover all available tasks

Git hooks (format, lint, unit tests, commitlint, and conditional pre-push checks) are managed by hk and installed automatically when you run mise install. Bypass hooks for a single command with HK=0 git commit. Run a hook manually with hk run pre-commit.

Task reference

Task	Description
mise run setup	First-time project bootstrap
mise run bootstrap	Install Node and Ruby dependencies
mise run update	Refresh dependencies after pulling
mise run build	Build extension, userscript, and bookmarklet
mise run watch	Build bundles in watch mode for local development
mise run test	Lint and unit tests
mise run test:lint	ESLint and Prettier format check
mise run test:format	Prettier format check only
mise run test:units	Jest unit tests
mise run cibuild	All CI checks locally (includes audit)
mise run package	Package Firefox, Chromium, userscript, bookmarklet
mise run docs:build	Build Jekyll documentation site
mise run docs:serve	Serve documentation at localhost:4000
mise run lighthouse	Build docs and run Lighthouse audits
mise run screenshots	Regenerate Chrome Web Store screenshots
mise run server	Run the extension in Firefox
mise run approve-builds	Approve dependency build scripts in paranoid mode
mise run release:dry-run	Dry-run semantic-release (requires GITHUB_TOKEN)

Prerequisites

Tool versions are defined in mise.toml:

• Node.js (latest via mise)
• aube 1.25.1
• Ruby 3.4.7 (for Jekyll documentation builds)
• hk 1.48.0 (git hooks)

Security overrides and build-script approvals live in aube-workspace.yaml (paranoid: true, overrides, allowBuilds).

Building the Extension

Once set up:

mise run package          # lint, build, and package for Firefox and Chromium

Or if Docker's more your thing:

docker buildx build . -o target

Building the Userscript and Bookmarklet

The userscript and bookmarklet are built automatically as part of mise run package. They will be generated in:

• Userscript: target/eventuate.user.js
• Bookmarklet: docs/bookmarklet/index.md

To build them individually:

mise run build

The userscript can be installed in browsers that support userscript managers like Tampermonkey, Userscripts, or Greasemonkey. The bookmarklet can be used in any browser, including Safari on iOS devices, by creating a bookmark with the generated JavaScript code.

Building the Documentation

The project includes Jekyll-based documentation that can be built locally:

mise run docs:build
mise run docs:serve

The documentation will be available at http://localhost:4000/eventuate/ and includes:

• Project overview and features
• Installation instructions
• Internationalisation support
• Development guidelines

Troubleshooting

mise command not found

Install mise from https://mise.jdx.dev and activate it in your shell:

curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc

Dependency build scripts blocked

Dependency lifecycle scripts require explicit approval in paranoid mode. After adding dependencies, run mise run approve-builds and commit the updated allowBuilds entries in aube-workspace.yaml.

Running locally

First, build the TypeScript in watch mode:

mise run watch

In another terminal, start Firefox with the extension loaded:

mise run server

Installing in a browser from source

1. Download this repository to a suitable location on your computer.
2. In Firefox, navigate to "about:debugging#/runtime/this-firefox"
3. Use the "Load Temporary Add-on..." button.
4. Browse to and open the file manifest.json from the location where it was saved.
5. The add-on will now appear in the add-on manager’s list of installed add-ons and be ready to use
6. Navigate to a results page such as:
   • English: https://www.parkrun.com.au/timboon/results/latestresults/
   • German: https://www.parkrun.com.de/priessnitzgrund/results/latestresults/

Observe the additional details between the title and the event table.

Requirements

This was built with Firefox in mind but also works in Chromium-based browsers, using the chromium artefacts. Enjoy!

Contributing

Bug reports and pull requests are welcome on GitHub. Everyone interacting in the eventuate project's codebases, issue trackers, etcetera is expected to follow the code of conduct.

We use semantic commits in this project. Please see our contibution guidelines for more information about the preferred commit message format.

Releasing

This project uses semantic-release to automate version management and package releases. The release process is triggered automatically when changes are pushed to the main branch.

The process will:

1. Analyze commits to determine the next version number
2. Update the CHANGELOG.md
3. Create a new GitHub release
4. Build and attach extension packages:
   • Firefox extension (.zip)
   • Chrome extension (.zip)
   • Userscript (.user.js)
   • Bookmarklet installation page (.html)

To test the release process locally:

GITHUB_TOKEN=your-token mise run release:dry-run

The version number will be automatically incremented based on your commits:

• fix: → patch (0.0.x)
• feat: → minor (0.x.0)
• BREAKING CHANGE: → major (x.0.0)

License

The addon is available as open source under the terms of the MIT License.