Give every author their own page (issue #89)#141
Open
RichardLitt wants to merge 2 commits into
Open
Conversation
Introduce a central authors.yml at the repo root and a small mkdocs hook
(.config/hooks/authors.py) that, on every build:
- Loads authors.yml (slug -> {name, orcid, affiliation}).
- Walks pattern frontmatter for `authors:` (a list of slugs) and builds a
reverse slug -> [patterns] map; fails the build with a PluginError if a
pattern references a slug missing from authors.yml.
- Emits one generated File per author at authors/<slug>.md plus an
authors/index.md listing all authors alphabetically.
- In on_page_markdown, replaces the bullet list under
`## Contributors & Acknowledgement` with chips linking to the author
pages, preserving any prose that follows (e.g. AI-use disclaimers).
- Leaves patterns without an `authors:` frontmatter entry untouched so the
remaining ~46 patterns continue to render their handwritten lists during
gradual migration.
Config wiring:
- mkdocs.yml: register hooks/authors.py, add `Authors: authors/index.md`
to nav, and exclude /authors.yml from the docs tree.
Template + contributor docs:
- PATTERN-TEMPLATE.md: add commented `authors:` block in frontmatter and
rewrite the Contributors section to explain the new auto-generation.
- CONTRIBUTING.md: replace the "add your name and ORCID at the bottom"
instruction with the two-step authors.yml + frontmatter flow.
Example migrations (exercise both code paths in the hook):
- embed-wellbeing-into-student-hackathons.md: 6 authors, no trailing prose.
- onboarding-graduate-leads-for-open-source-internship-programs.md:
4 authors followed by an "A note on AI use" paragraph that the hook
must preserve.
Verified with `mkdocs build --strict --site-dir /tmp/patterns_site`:
clean build, all 9 author pages generated, both migrated patterns render
chips correctly, AI-use paragraph preserved, non-migrated pattern
unchanged, and a negative test with an unknown slug aborts the build
with a clear error message.
This was referenced May 23, 2026
The hook now generates only authors/index.md — a roster table plus one
anchored section per author with their patterns — instead of one page per
author. Pattern Contributors bullets link to authors/index.md#<slug>
anchors. Enables attr_list so { #slug } heading IDs are stable.
Member
Author
|
Update on the design — after another look, I've reworked this so there's one Authors page instead of a separate page per author. What's the same: What's different on the site:
The reasoning: most authors only have a pattern or two, so individual pages felt thin. A single page makes it easier to scan everyone at once, and you can still click a name on a pattern to jump straight to that person's entry. The PR description above still describes the old approach — please ignore that part and treat this comment as the current behaviour. (Will tidy the description before merge.) |
RichardLitt
added a commit
that referenced
this pull request
May 27, 2026
Convert all remaining patterns' Contributors sections to the authors.yml + frontmatter model introduced in #141. Adds 28 new authors to authors.yml (the 9 seeded in #141 stay unchanged) and populates the `authors:` frontmatter on 41 patterns. Migration was driven by a one-off Python script (not committed) that: - Parses each pattern's `## Contributors & Acknowledgement` / `Acknowledgements` section, skipping any "in alphabetical order" preamble. - Extracts (name, affiliation, orcid) from each bullet using regex-based ORCID detection and a name/affiliation parser that handles both `Name, Affiliation, <orcid>` and `Name (Affiliation), <orcid>` shapes. - Strips academic titles (Dr./Prof./etc.) before slug generation and before name-based deduplication, so "Dr. Angela Newell" maps to the existing `angela-newell` slug instead of creating a duplicate. - Folds diacritics for slug generation via unicodedata.normalize (NFKD + combining-character strip), so "David Pérez-Suárez" becomes `david-perez-suarez` rather than `david-p-rez-su-rez`. - Dedupes by ORCID first, then by case-insensitive name; backfills missing ORCID or affiliation on existing records when a later pattern provides one. - Preserves any trailing prose under the Contributors heading (e.g. AI-use disclaimers, "Special thanks to X for ..." notes). Skipped (no Contributors section, intentionally left untouched): framework-managing-university-oss.md, lunch-and-learn.md, open-research-community-accelerator.md, open-source-catalog.md, open-source-software-prize.md, open-source-survey.md, oss-tutorials-using-authoring-tools.md, summer-internship-program.md, integrating-oss-into-institutional-software-pathways.md. Verified: - `mkdocs build --strict --site-dir /tmp/patterns_site` clean. - All 37 author pages generate; each lists the patterns the author contributed to. - Preserved prose still renders on individual-consultations-office-hours.md (Duane O'Brien thanks), source-industry-mentors-for-the-icorps-program.md (Jeffrey Young thanks), project-rolodex.md (Megan Forbes thanks), and the several patterns with "A note on AI use" paragraphs. - `npm run lint` passes (one MD012 stray blank line in project-rolodex.md auto-fixed by `lint-fix`).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #89.
What this changes
Right now, contributors are listed as plain text bullets at the bottom of each pattern, and that's the only place their name appears on the website. If you've contributed to five patterns, your name lives in five different places — and there's no single page that shows everything you've worked on.
This PR adds a page for every author. Each author page shows their name, affiliation, ORCID, and the list of patterns they've contributed to. There's also a new Authors link in the top navigation that takes you to the full list of contributors.
What changes for someone writing or editing a pattern
Two small steps instead of one:
authors.ymlat the root of the repo. This is where your name, ORCID, and affiliation live — you only put them in once, no matter how many patterns you contribute to. A short slug likejane-doeidentifies you.authors:. That's it.You no longer type your name and ORCID at the bottom of each pattern — the site fills that section in for you.
CONTRIBUTING.mdhas been updated with the new instructions and an example.If you'd like to keep a note in the Contributors section (for example, the "A note on AI use" paragraph on the onboarding-graduate-leads pattern), you still can — anything written below the auto-generated author list is preserved.
What readers see that's new
/authors/ciara-flanagan/— listing their affiliation, ORCID, and every pattern they've worked on.What to click on the preview site to see it working
Two patterns have been migrated as examples — the rest stay exactly as they are for now:
/embed-wellbeing-into-student-hackathons/— scroll to the bottom; the six contributors are now clickable links to their author pages./onboarding-graduate-leads-for-open-source-internship-programs/— same idea, plus the existing "A note on AI use" paragraph still appears underneath, untouched./authors/— the new index of all authors./authors/ciara-flanagan/— example of a single author page. Ciara appears in both example patterns, so her page lists both./cohosting-student-events/) — unchanged; its hand-written contributor list still renders the way it always has.What's coming next
This PR only migrates two patterns as proof of concept. The remaining ~46 patterns will be migrated to the new format in a follow-up PR — nothing breaks for them in the meantime, they keep working exactly as before until they're migrated.
A separate follow-up PR will also add the official ORCID iD logo next to ORCID links on author pages, for visual polish.
🤖 Generated with Claude Code