QuantEcon / QuantEcon/quantecon-book-theme

Per-page announcements (additive follow-up to the site-wide banner)

Open
#403 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.