Merge pull request #373 from davep/copilot/add-calendar-view-for-posts

Add optional calendar view of full post history

Author: davep

ChangeLog.md

@@ -10,6 +10,13 @@
 - Added a `read_time_wpm` configuration option that lets users override the
   words-per-minute value used when calculating estimated reading time.
   ([#371](https://github.com/davep/blogmore/pull/371))
+- Added a calendar view page (`with_calendar` / `--with-calendar`) that
+  shows the full history of the blog as a year calendar.
+  ([#373](https://github.com/davep/blogmore/pull/373))
+- Added a `forward_calendar` configuration option that renders the calendar
+  in natural chronological order (oldest to newest) instead of the default
+  reverse-chronological order.
+  ([#373](https://github.com/davep/blogmore/pull/373))
 
 ## v2.10.0
 

README.md

@@ -54,6 +54,9 @@ here](https://github.com/davep/davep.github.com)).
 - **XML sitemap** — optional `sitemap.xml` for search engine indexing
 - **Blog statistics page** — optional stats page with histograms, word counts,
   reading times, lifespan, top linked domains, and more
+- **Calendar view** — optional full-history year calendar showing all posts,
+  with links to day, month, and year archives; responsive design adapts from
+  four months per row down to one
 - **SEO optimisation** — meta tags, Open Graph tags, and Twitter Card support
 - **Automatic organisation** — tag pages, category pages, and chronological
   archives generated automatically

blogmore.yaml.example

@@ -65,6 +65,21 @@ posts_per_feed: 20
 # navigation bar automatically.
 # with_stats: false
 
+# Optional: Generate a calendar view of all posts (default: false)
+# Generates a calendar.html page showing the full history of the blog as a
+# reverse-chronological year calendar. Days with posts link to the daily
+# archive, months link to the monthly archive, and years link to the yearly
+# archive. A Calendar link is added to the navigation bar automatically.
+# with_calendar: false
+
+# Optional: Use forward (oldest-to-newest) ordering in the calendar (default: false)
+# When true, the calendar runs in natural chronological order — oldest year at
+# the top, oldest month first within each year, and day numbers increasing left
+# to right (Monday first). When false (the default), everything is reversed so
+# the most recent content appears first. Configuration file only.
+# Only used when with_calendar is true.
+# forward_calendar: false
+
 # Optional: Show estimated reading time on posts (default: false)
 # Displays the approximate time to read each post based on the configured WPM.
 # with_read_time: false
@@ -138,6 +153,14 @@ posts_per_feed: 20
 # Only used when with_stats is true. Configuration file only.
 # stats_path: "stats.html"
 
+# Optional: Path for the calendar page relative to the output directory
+# (default: calendar.html). The full directory path is created automatically.
+# When clean_urls is enabled and the path ends in index.html, the
+# index.html portion is omitted in links to the page. Leading slashes are
+# stripped so both calendar.html and /calendar.html produce the same result.
+# Only used when with_calendar is true. Configuration file only.
+# calendar_path: "calendar.html"
+
 # Optional: Generate clean URLs for posts and pages (default: false)
 # When enabled, posts and pages whose URL ends with /index.html will use the
 # shorter trailing-slash form instead (e.g. /pages/about/ instead of

docs/command_line.md

@@ -205,6 +205,16 @@ Stats generation is **disabled by default**. Pass this flag to opt in.
 blogmore build posts/ --with-stats
 ```
 
+#### `--with-calendar`
+
+Generate a calendar view of all posts. When set, BlogMore generates a `calendar.html` page (path configurable via the `calendar_path` configuration option) displaying the full history of the blog as a reverse-chronological year calendar. Days with posts link to the daily archive, months link to the monthly archive, and years link to the yearly archive. A **Calendar** link is added to the navigation bar automatically.
+
+Calendar generation is **disabled by default**. Pass this flag to opt in.
+
+```bash
+blogmore build posts/ --with-calendar
+```
+
 #### `--with-read-time`
 
 Show estimated reading time on each post. When enabled, BlogMore calculates the approximate time to read each post (based on 200 words per minute) and displays it next to the post date on all post listings and individual post pages.

docs/configuration.md

@@ -318,6 +318,30 @@ Generate a blog statistics page. When `true`, BlogMore generates a `/stats.html`
 with_stats: true
 ```
 
+#### `with_calendar`
+
+Generate a calendar view of all posts. When `true`, BlogMore generates a `calendar.html` page (path configurable via [`calendar_path`](#calendar_path)) showing a full year-by-year calendar of the blog's history, from the date of the latest post back to the date of the first post. Days with posts link to the daily archive, months link to the monthly archive, and years link to the yearly archive. A **Calendar** link is automatically added to the navigation bar after **Stats** and before **RSS**.
+
+**Type:** Boolean  
+**Default:** `false`
+
+```yaml
+with_calendar: true
+```
+
+#### `forward_calendar`
+
+Control the ordering of the calendar generated by [`with_calendar`](#with_calendar).  When `false` (the default), the calendar is displayed in reverse chronological order — newest year at the top, newest month first within each year, and day numbers counting down from right to left within each row.  When `true`, the calendar runs in natural chronological order — oldest year at the top, oldest month first within each year, and day numbers increasing left to right (Monday first), like a traditional wall calendar.
+
+This is a **configuration file only** option — it cannot be set on the command line.  Only meaningful when [`with_calendar`](#with_calendar) is `true`.
+
+**Type:** Boolean  
+**Default:** `false`
+
+```yaml
+forward_calendar: true
+```
+
 #### `with_read_time`
 
 Show estimated reading time on each post. When enabled, BlogMore calculates the approximate time to read each post (based on the configured words-per-minute rate) and displays it next to the post date on all post listings and individual post pages.
@@ -691,6 +715,42 @@ clean_urls: true
 
 This makes the stats page accessible at `/stats/` rather than `/stats/index.html`.
 
+#### `calendar_path`
+
+Path (relative to the output directory) where the calendar page is generated.  This is a **configuration file only** option — it cannot be set on the command line.  Only used when [`with_calendar`](#with_calendar) is `true`.
+
+**Type:** String  
+**Default:** `calendar.html`
+
+```yaml
+calendar_path: "calendar.html"
+```
+
+##### How it works
+
+The path is joined onto the `output` directory.  Any intermediate subdirectories are created automatically.
+
+The path is always treated as relative to the output directory root — a leading `/` is stripped automatically.  So both `calendar/index.html` and `/calendar/index.html` produce the same output location.
+
+When `clean_urls` is enabled and the path ends in `index.html`, the `index.html` portion is omitted in any URL reference to the calendar page (navigation links, canonical URL, etc.), so the page is accessible at the clean trailing-slash URL.
+
+##### Examples
+
+Default — calendar page at the site root:
+
+```yaml
+calendar_path: "calendar.html"
+```
+
+Calendar page in its own subdirectory with clean URLs:
+
+```yaml
+calendar_path: "calendar/index.html"
+clean_urls: true
+```
+
+This makes the calendar page accessible at `/calendar/` rather than `/calendar/index.html`.
+
 #### `page_1_path`
 
 Output path template for the **first page** of any paginated listing (main index, year/month/day archives, tag pages, and category pages).  This is a **configuration file only** option — it cannot be set on the command line.

docs/index.md

@@ -30,6 +30,7 @@ BlogMore focuses on simplicity and efficiency in creating blog-focused websites.
 - **XML sitemap** - Optional `sitemap.xml` generation for search engine indexing (enable with `--with-sitemap`)
 - **Flexible URL scheme for posts** - Fully configurable post output paths and URLs via the `post_path` option; choose date-based paths, per-post directories, category-based layouts, and more
 - **Blog statistics page** — Optional stats page with histograms, word counts, reading times, lifespan, top linked domains, and more
+- **Calendar view** — Optional full-history year calendar view of all posts, with links to day, month, and year archives (enable with `--with-calendar`)
 
 ## Installation
 

docs/template-api.md

@@ -35,7 +35,13 @@ below lists all variables that are available in every template.
 | `search_css_url` | `str` | URL to the search-page stylesheet (with cache-bust query string). |
 | `stats_css_url` | `str` | URL to the stats-page stylesheet (with cache-bust query string). |
 | `archive_css_url` | `str` | URL to the archive-page stylesheet (with cache-bust query string). |
+| `calendar_css_url` | `str` | URL to the calendar-page stylesheet (with cache-bust query string). |
 | `tag_cloud_css_url` | `str` | URL to the tag/category-cloud stylesheet (with cache-bust query string). |
+| `with_stats` | `bool` | `True` when the statistics page is enabled. |
+| `stats_url` | `str` | URL to the statistics page (respects `stats_path` and `clean_urls`). |
+| `with_calendar` | `bool` | `True` when the calendar page is enabled. |
+| `forward_calendar` | `bool` | `True` when the calendar is in forward (oldest-to-newest) order. |
+| `calendar_url` | `str` | URL to the calendar page (respects `calendar_path` and `clean_urls`). |
 | `theme_js_url` | `str` | URL to `theme.js` (with cache-bust query string). |
 | `search_js_url` | `str` | URL to `search.js` (with cache-bust query string). |
 | `favicon_url` | `str \| None` | URL to the site favicon, if one exists. |
@@ -105,6 +111,8 @@ or `/tag/python/` when `clean_urls` is enabled.
 | `category.html` | `category`, `safe_category`, `all_posts`, `pages`, `prev_page_url`, `next_page_url`, `canonical_url`, `pagination_page_urls` |
 | `categories.html` | `categories` (dict of display name → post list), `pages`, `canonical_url` |
 | `search.html` | `pages`, `canonical_url` |
+| `stats.html` | `stats` (`BlogStats`), `pages`, `canonical_url` |
+| `calendar.html` | `calendar_years` (list of `CalendarYear`), `pages`, `canonical_url` |
 
 ## Post object
 
@@ -176,6 +184,39 @@ To override the draft title colour, set `--draft-title-color` (and
 | `url` | `str` (property) | URL path (e.g. `/about.html`). |
 | `description` | `str` (property) | Page description (from metadata or first paragraph). |
 
+## Calendar objects
+
+The `calendar.html` template receives a `calendar_years` variable containing a
+list of `CalendarYear` objects in reverse chronological order.
+
+### CalendarYear
+
+| Attribute | Type | Description |
+|---|---|---|
+| `year` | `int` | The calendar year. |
+| `year_url` | `str \| None` | URL to the yearly archive, or `None` when the year has no posts. |
+| `has_posts` | `bool` | `True` when at least one post was published in this year. |
+| `months` | `list[CalendarMonth]` | Months for this year in reverse chronological order (latest first). |
+
+### CalendarMonth
+
+| Attribute | Type | Description |
+|---|---|---|
+| `year` | `int` | The year this month belongs to. |
+| `month` | `int` | The month number (1–12). |
+| `month_name` | `str` | Full English month name (e.g. `"January"`). |
+| `month_url` | `str \| None` | URL to the monthly archive, or `None` when the month has no posts. |
+| `has_posts` | `bool` | `True` when at least one post was published in this month. |
+| `weeks` | `list[list[CalendarDay]]` | Calendar grid rows, each containing exactly 7 `CalendarDay` entries in Monday-to-Sunday order. |
+
+### CalendarDay
+
+| Attribute | Type | Description |
+|---|---|---|
+| `date` | `datetime.date \| None` | The calendar date for this cell. `None` for padding slots that do not belong to the current month. |
+| `post_count` | `int` | Number of posts published on this day (0 for non-post days and padding). |
+| `day_url` | `str \| None` | URL to the daily archive. Set only when `post_count > 0`; `None` otherwise. |
+
 ## Template inheritance
 
 All page templates extend `base.html`.  The inheritance chain is:
@@ -190,7 +231,9 @@ base.html
 ├── tags.html
 ├── category.html
 ├── categories.html
-└── search.html
+├── search.html
+├── stats.html
+└── calendar.html
 ```
 
 Partial templates included by the above:

src/blogmore/__main__.py

@@ -99,6 +99,7 @@ def main() -> int:
         with_search=args.with_search,
         with_sitemap=args.with_sitemap,
         with_stats=args.with_stats,
+        with_calendar=args.with_calendar,
         minify_css=args.minify_css,
         minify_js=args.minify_js,
         minify_html=args.minify_html,
@@ -257,6 +258,7 @@ def _extract_cli_overrides(args: argparse.Namespace) -> dict[str, Any]:
         "with_search": False,
         "with_sitemap": False,
         "with_stats": False,
+        "with_calendar": False,
         "minify_css": False,
         "minify_js": False,
         "minify_html": False,