Add forward_calendar config option for chronological calendar order

Agent-Logs-Url: https://github.com/davep/blogmore/sessions/4348fed1-bb82-4069-a053-ffba2a6bd485

Co-authored-by: davep <28237+davep@users.noreply.github.com>

Author: Copilot

ChangeLog.md

@@ -13,6 +13,10 @@
 - 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
 

blogmore.yaml.example

@@ -72,6 +72,14 @@ posts_per_feed: 20
 # 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

docs/configuration.md

@@ -329,6 +329,19 @@ Generate a calendar view of all posts. When `true`, BlogMore generates a `calend
 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.

docs/template-api.md

@@ -40,6 +40,7 @@ below lists all variables that are available in every template.
 | `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). |

src/blogmore/calendar.py

@@ -62,8 +62,10 @@ class CalendarMonth:
     weeks: list[list[CalendarDay]]
     """Calendar grid rows.
 
-    Each row contains exactly seven :class:`CalendarDay` items in
-    Monday-to-Sunday order.
+    Each row contains exactly seven :class:`CalendarDay` items.  In
+    reverse-chronological mode (the default) the order is Sunday-to-Monday so
+    that day numbers count down left-to-right.  In forward mode the order is
+    Monday-to-Sunday, matching the usual calendar convention.
     """
 
 
@@ -84,28 +86,40 @@ class CalendarYear:
     """Whether any posts were published in this year."""
 
     months: list[CalendarMonth]
-    """Months for this year in reverse chronological order (latest first)."""
+    """Months for this year.
+
+    In reverse-chronological mode (the default) the list runs newest-first.
+    In forward mode the list runs oldest-first.
+    """
 
 
 def build_calendar(
     posts: list[Post],
     page1_suffix: str,
+    *,
+    forward: bool = False,
 ) -> list[CalendarYear]:
     """Build the calendar data structure from a list of posts.
 
-    Constructs a reverse-chronological list of :class:`CalendarYear` objects,
-    each containing months in reverse order, spanning from the date of the
-    first post to the date of the latest post.
+    Constructs a list of :class:`CalendarYear` objects spanning from the
+    date of the first post to the date of the latest post.
+
+    By default the list is in reverse chronological order (newest year
+    first, newest month first, day numbers counting down from left to right
+    within each row).  Pass ``forward=True`` to generate a natural
+    chronological calendar instead (oldest year first, Monday-to-Sunday
+    columns, day numbers increasing left to right).
 
     Args:
         posts: All published posts to include in the calendar.
         page1_suffix: The URL suffix for the first pagination page (e.g.
             ``"index.html"`` or ``""`` for clean URLs).
+        forward: When ``True``, generate the calendar in oldest-to-newest
+            order.  Defaults to ``False`` (reverse chronological).
 
     Returns:
-        A list of :class:`CalendarYear` objects in reverse chronological
-        order (most recent year first).  Returns an empty list when *posts*
-        is empty or no posts have a date.
+        A list of :class:`CalendarYear` objects.  Returns an empty list
+        when *posts* is empty or no posts have a date.
     """
     dated_posts = [p for p in posts if p.date is not None]
     if not dated_posts:
@@ -138,7 +152,14 @@ def build_calendar(
 
     years: list[CalendarYear] = []
 
-    for year in range(last_year, first_year - 1, -1):
+    # Choose iteration direction for years and months.
+    year_range = (
+        range(first_year, last_year + 1)
+        if forward
+        else range(last_year, first_year - 1, -1)
+    )
+
+    for year in year_range:
         # Determine the month range to include for this year.
         if year == last_year and year == first_year:
             year_last_month = last_month
@@ -158,24 +179,35 @@ def build_calendar(
 
         months: list[CalendarMonth] = []
 
-        for month in range(year_last_month, year_first_month - 1, -1):
+        month_range = (
+            range(year_first_month, year_last_month + 1)
+            if forward
+            else range(year_last_month, year_first_month - 1, -1)
+        )
+
+        for month in month_range:
             month_has_posts = (year, month) in months_with_posts
             month_name = dt.date(year, month, 1).strftime("%B")
             month_url: str | None = (
                 f"/{year}/{month:02d}/{page1_suffix}" if month_has_posts else None
             )
 
-            # Build the week grid.  ``monthdayscalendar`` returns weeks in
-            # forward order (Mon first); reverse both the week list and each
-            # week's day order so the most recent day appears first (top-left)
-            # throughout — consistent with the overall reverse-chronological
-            # ordering of the calendar.
-            raw_weeks = list(reversed(month_calendar.monthdayscalendar(year, month)))
+            # Build the week grid.  ``monthdayscalendar`` always returns
+            # weeks in forward order (Mon first).  For reverse-chronological
+            # mode, reverse both the week list and each week's day order so
+            # the most recent day appears first (top-left); for forward mode,
+            # keep them as-is so the grid reads like a normal calendar.
+            raw_weeks = month_calendar.monthdayscalendar(year, month)
             weeks: list[list[CalendarDay]] = []
 
-            for raw_week in raw_weeks:
+            ordered_weeks: list[list[int]] = (
+                raw_weeks if forward else list(reversed(raw_weeks))
+            )
+
+            for raw_week in ordered_weeks:
                 week: list[CalendarDay] = []
-                for day_num in reversed(raw_week):
+                day_iter = raw_week if forward else list(reversed(raw_week))
+                for day_num in day_iter:
                     if day_num == 0:
                         week.append(CalendarDay(date=None))
                     else:

src/blogmore/generator.py

@@ -417,6 +417,7 @@ def _get_global_context(self) -> dict[str, Any]:
             "with_stats": self.site_config.with_stats,
             "stats_url": self._get_stats_url(),
             "with_calendar": self.site_config.with_calendar,
+            "forward_calendar": self.site_config.forward_calendar,
             "calendar_url": self._get_calendar_url(),
             "with_read_time": self.site_config.with_read_time,
             "with_advert": self.site_config.with_advert,
@@ -1747,7 +1748,9 @@ def _generate_calendar_page(self, posts: list[Post], pages: list[Page]) -> None:
             context["canonical_url"] = self._canonical_url_for_path(output_path)
         # Determine page1_suffix for archive URL construction.
         page1_suffix = self.site_config.page_1_path.lstrip("/")
-        calendar_years: list[CalendarYear] = build_calendar(posts, page1_suffix)
+        calendar_years: list[CalendarYear] = build_calendar(
+            posts, page1_suffix, forward=self.site_config.forward_calendar
+        )
         html = self.renderer.render_calendar_page(
             calendar_years=calendar_years, **context
         )

src/blogmore/site_config.py

@@ -106,6 +106,21 @@ class SiteConfig:
     with_calendar: bool = False
     """Whether to generate a calendar view of all posts."""
 
+    forward_calendar: bool = False
+    """Whether to display the calendar in forward (oldest-to-newest) order.
+
+    When ``False`` (the default) the calendar is rendered in reverse
+    chronological order — newest year first, newest month first within each
+    year, and day numbers counting down from right to left within each row.
+
+    When ``True`` the calendar is rendered in natural chronological order —
+    oldest year first, oldest month first within each year, and day numbers
+    running left to right in normal calendar order (Monday first).
+
+    This is a **configuration file only** option — it cannot be set on the
+    command line.  Only meaningful when :attr:`with_calendar` is ``True``.
+    """
+
     minify_css: bool = False
     """Whether to minify the CSS, writing it as ``styles.min.css``."""
 

src/blogmore/templates/calendar.html

@@ -40,13 +40,23 @@ <h3 class="calendar-month-label">
                 </h3>
 
                 <div class="calendar-grid">
+                    {% if forward_calendar %}
+                    <div class="calendar-dow" aria-hidden="true">M</div>
+                    <div class="calendar-dow" aria-hidden="true">T</div>
+                    <div class="calendar-dow" aria-hidden="true">W</div>
+                    <div class="calendar-dow" aria-hidden="true">T</div>
+                    <div class="calendar-dow" aria-hidden="true">F</div>
+                    <div class="calendar-dow" aria-hidden="true">S</div>
+                    <div class="calendar-dow" aria-hidden="true">S</div>
+                    {% else %}
                     <div class="calendar-dow" aria-hidden="true">S</div>
                     <div class="calendar-dow" aria-hidden="true">S</div>
                     <div class="calendar-dow" aria-hidden="true">F</div>
                     <div class="calendar-dow" aria-hidden="true">T</div>
                     <div class="calendar-dow" aria-hidden="true">W</div>
                     <div class="calendar-dow" aria-hidden="true">T</div>
                     <div class="calendar-dow" aria-hidden="true">M</div>
+                    {% endif %}
 
                     {% for week in cal_month.weeks %}
                     {% for day in week %}

tests/test_calendar.py

@@ -336,3 +336,82 @@ def test_calendar_year_fields(self) -> None:
         assert year.year_url == "/2024/index.html"
         assert year.has_posts is True
         assert year.months == []
+
+
+class TestBuildCalendarForward:
+    """Tests for build_calendar with forward=True (chronological order)."""
+
+    def test_forward_year_order_is_oldest_first(self) -> None:
+        """Years are listed oldest-first when forward=True."""
+        posts = [_make_post(2022, 6, 1), _make_post(2024, 3, 15)]
+        result = build_calendar(posts, "index.html", forward=True)
+        years = [y.year for y in result]
+        assert years == sorted(years)
+
+    def test_forward_month_order_is_oldest_first(self) -> None:
+        """Months within a year are listed oldest-first when forward=True."""
+        posts = [_make_post(2024, 1, 10), _make_post(2024, 9, 5)]
+        result = build_calendar(posts, "index.html", forward=True)
+        months = [m.month for m in result[0].months]
+        assert months == sorted(months)
+
+    def test_forward_days_increase_left_to_right(self) -> None:
+        """Day numbers increase left-to-right within a row when forward=True.
+
+        January 2024 week containing the 8th: Monday the 8th is at column 0.
+        """
+        post = _make_post(2024, 1, 8)
+        result = build_calendar([post], "index.html", forward=True)
+        month = result[0].months[0]
+        # Find the week containing the 8th.
+        for week in month.weeks:
+            for cell in week:
+                if cell.date is not None and cell.date.day == 8:
+                    # Jan 8 2024 is a Monday — must be at column 0 (first).
+                    assert week.index(cell) == 0
+                    return
+        raise AssertionError("Day 8 not found in calendar")
+
+    def test_forward_monday_at_column_zero(self) -> None:
+        """Monday appears at column 0 when forward=True.
+
+        January 2024: the 1st is a Monday, so the first week row should
+        have January 1 at column index 0.
+        """
+        post = _make_post(2024, 1, 1)
+        result = build_calendar([post], "index.html", forward=True)
+        month = result[0].months[0]
+        first_week = month.weeks[0]
+        assert first_week[0].date is not None
+        assert first_week[0].date.day == 1
+
+    def test_forward_false_is_default(self) -> None:
+        """forward=False (the default) keeps reverse-chronological order."""
+        posts = [_make_post(2022, 6, 1), _make_post(2024, 3, 15)]
+        result_default = build_calendar(posts, "index.html")
+        result_explicit = build_calendar(posts, "index.html", forward=False)
+        assert [y.year for y in result_default] == [y.year for y in result_explicit]
+
+    def test_forward_preserves_post_count(self) -> None:
+        """Post counts are correct when forward=True."""
+        post = _make_post(2024, 6, 15)
+        result = build_calendar([post], "index.html", forward=True)
+        month = result[0].months[0]
+        for week in month.weeks:
+            for cell in week:
+                if cell.date is not None and cell.date.day == 15:
+                    assert cell.post_count == 1
+                    return
+        raise AssertionError("Day 15 not found in calendar")
+
+    def test_forward_year_url_present(self) -> None:
+        """Year URL is set when forward=True and the year has posts."""
+        post = _make_post(2024, 3, 10)
+        result = build_calendar([post], "index.html", forward=True)
+        assert result[0].year_url == "/2024/index.html"
+
+    def test_forward_month_url_present(self) -> None:
+        """Month URL is set when forward=True and the month has posts."""
+        post = _make_post(2024, 3, 10)
+        result = build_calendar([post], "index.html", forward=True)
+        assert result[0].months[0].month_url == "/2024/03/index.html"

tests/test_generator.py

@@ -5987,3 +5987,32 @@ def test_calendar_canonical_url_with_site_url(
             '<link rel="canonical" href="https://example.com/calendar.html">'
             in calendar_content
         )
+
+    def test_forward_calendar_default_is_false(self) -> None:
+        """forward_calendar defaults to False on SiteConfig."""
+        config = SiteConfig(output_dir=Path("output"))
+        assert config.forward_calendar is False
+
+    def test_forward_calendar_generates_monday_first_headers(
+        self, posts_dir: Path, temp_output_dir: Path
+    ) -> None:
+        """When forward_calendar=True the template renders M T W T F S S headers."""
+        generator = SiteGenerator(
+            site_config=SiteConfig(
+                content_dir=posts_dir,
+                output_dir=temp_output_dir,
+                with_calendar=True,
+                forward_calendar=True,
+            )
+        )
+        generator.generate()
+
+        calendar_content = (temp_output_dir / "calendar.html").read_text()
+        # The DOW header row for a forward calendar should start with M (Monday).
+        # We look for the sequential M T W T pattern (Monday-Tuesday-Wednesday-Thursday).
+        assert "calendar-dow" in calendar_content
+        # Find the section containing the day-of-week headers; Monday should appear
+        # before Sunday in forward mode.
+        first_m_pos = calendar_content.find(">M<")
+        first_s_pos = calendar_content.find(">S<")
+        assert first_m_pos < first_s_pos