QuantEcon / QuantEcon/quantecon-book-theme
Per-page announcements (additive follow-up to the site-wide banner)
Nobody has claimed this yet.
- Dominant language
- Jupyter Notebook
- Stars
- 56
- Forks
- 24
- Avg merge
- 4h 33m
- Merged PRs (30d)
- 4
Description
Background
The dismissible announcement banner shipped as site-wide only — a single announcement (plus optional announcement_expires) theme option rendered at the top of every page. See the Announcement Banner docs.
The renderer was deliberately built to be additive: the template loops over a list of notices, announcement.js evaluates each .qe-announcement row independently (its own content-hash dismissal + its own expiry), and the dismissed-set in localStorage already tracks multiple IDs. So the JS, persistence, and most of the CSS already support N rows. What's left for per-page is the config plumbing, a little stacking polish, and one design decision.
Goal
Let an individual page carry its own announcement that stacks additively with the global one: global on top, page-specific below. Example use case — flagging that a single lecture now uses a newer library version (pandas==3.0) while a site-wide notice (an Anaconda upgrade) stays visible.
Open decision: how should a per-page notice be authored?
| Mechanism | Pros | Cons |
|---|---|---|
Config keyed by docname (an announcements: map in html_theme_options) |
Everything in one place; easy to audit and remove stale notices; non-authors can add one without touching lecture files | Becomes public theme-option API (hard to change later); brittle to page renames; page content lives far from the page |
| MyST frontmatter on the page | Co-located with the content; survives renames; natural fit for "this lecture uses …" | Spread across many files; harder to get a site-wide overview |
My current lean is to re-evaluate frontmatter for per-page, since page-specific content arguably belongs with the page — but this is the thing to settle before building.
Settled design (for whichever mechanism wins)
- Additive: when both global and per-page are present, render two stacked rows (global first).
- Each row independent: its own expiry, its own
×dismiss, its own content-hash so editing one re-shows only that one. - When a page has only one of the two, show just that one; when all rows are dismissed/expired, the bar collapses.
Scope / priority
Demand-driven — open this when there's a concrete need. The site-wide banner already covers the primary case.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/user/announcements.md and the existing announcement.js behavior described in the issue, then inspect the template and theme-option plumbing. Resolve whether per-page notices use an announcements map or MyST frontmatter before implementation. Done means global and page notices stack in order, dismiss and expire independently, and the bar collapses when no rows remain.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter-notebook
- Domain
- documentation, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100