Merge pull request #547 from davep/aria-dates

Add aria-label to date-based archive links

Author: davep

ChangeLog.md

@@ -10,6 +10,11 @@
 - Added an alternative relatedness graph view to the graph page when the
   related posts feature (`with_related`) is enabled.
   ([#546](https://github.com/davep/blogmore/pull/546))
+- Added `aria-label` attributes to year, month, and day archive links in the
+  archive list pages and calendar templates to improve accessibility for
+  screen reader users by preventing identical link text (e.g. "05" or "May")
+  with different destinations.
+  ([#547](https://github.com/davep/blogmore/pull/547))
 
 ## v2.30.0
 

src/blogmore/renderer.py

@@ -80,9 +80,9 @@ def __init__(
     def _format_date(date: dt.datetime | None) -> Markup:
         """Format a datetime object as HTML with archive links.
 
-        The date portion is rendered as
-        `<a href="/{year}/">{year}</a>-<a href="/{year}/{mm}/">{mm}</a>-<a href="/{year}/{mm}/{dd}/">{dd}</a>`
-        so each component links to the corresponding archive page.
+        The date portion is rendered as separate links for the year, month, and day
+        (separated by dashes), with each link containing an appropriate aria-label
+        pointing to the corresponding archive page.
 
         Args:
             date: The datetime to format.
@@ -97,9 +97,18 @@ def _format_date(date: dt.datetime | None) -> Markup:
         month = date.month
         day = date.day
 
-        year_link = Markup(f'<a href="/{year}/">{year}</a>')
-        month_link = Markup(f'<a href="/{year}/{month:02d}/">{month:02d}</a>')
-        day_link = Markup(f'<a href="/{year}/{month:02d}/{day:02d}/">{day:02d}</a>')
+        year_label = f"Archive for {year}"
+        month_name = date.strftime("%B")
+        month_label = f"Archive for {month_name} {year}"
+        day_label = f"Archive for {month_name} {day}, {year}"
+
+        year_link = Markup(f'<a href="/{year}/" aria-label="{year_label}">{year}</a>')
+        month_link = Markup(
+            f'<a href="/{year}/{month:02d}/" aria-label="{month_label}">{month:02d}</a>'
+        )
+        day_link = Markup(
+            f'<a href="/{year}/{month:02d}/{day:02d}/" aria-label="{day_label}">{day:02d}</a>'
+        )
 
         time_str = date.strftime("%H:%M:%S")
         formatted = Markup(f"{year_link}-{month_link}-{day_link} {time_str}")

src/blogmore/templates/archive.html

@@ -54,12 +54,12 @@ <h1>Archive <span class="archive-post-count">({{ total_post_count }} {{ 'post' i
 
         {% for year in ns.years.keys()|sort(reverse=True) %}
         <section class="archive-year" id="archive-{{ year }}">
-            <h2><a href="/{{ year }}/{{ pagination_page1_suffix }}">{{ year }}</a> <span class="archive-post-count">({{ year_counts[year] }} {{ 'post' if year_counts[year] == 1 else 'posts' }})</span></h2>
+            <h2><a href="/{{ year }}/{{ pagination_page1_suffix }}" aria-label="Archive for {{ year }}">{{ year }}</a> <span class="archive-post-count">({{ year_counts[year] }} {{ 'post' if year_counts[year] == 1 else 'posts' }})</span></h2>
 
             {% for month_key in ns.years[year].keys()|sort(reverse=True) %}
             {% set month_count = ns.years[year][month_key]['posts']|length %}
             <section class="archive-month" id="archive-{{ year }}-{{ month_key }}">
-                <h3><a href="/{{ year }}/{{ month_key }}/{{ pagination_page1_suffix }}">{{ ns.years[year][month_key]['name'] }}</a> <span class="archive-post-count">({{ month_count }} {{ 'post' if month_count == 1 else 'posts' }})</span></h3>
+                <h3><a href="/{{ year }}/{{ month_key }}/{{ pagination_page1_suffix }}" aria-label="Archive for {{ ns.years[year][month_key]['name'] }} {{ year }}">{{ ns.years[year][month_key]['name'] }}</a> <span class="archive-post-count">({{ month_count }} {{ 'post' if month_count == 1 else 'posts' }})</span></h3>
 
                 <ul class="archive-post-list">
                 {% for post in ns.years[year][month_key]['posts'] %}

src/blogmore/templates/calendar.html

@@ -22,7 +22,7 @@ <h1>Calendar</h1>
     <section class="calendar-year-section">
         <h2 class="calendar-year-label">
             {% if year_group.year_url %}
-            <a href="{{ year_group.year_url }}">{{ year_group.year }}</a>
+            <a href="{{ year_group.year_url }}" aria-label="Archive for {{ year_group.year }}">{{ year_group.year }}</a>
             {% else %}
             {{ year_group.year }}
             {% endif %}
@@ -33,7 +33,7 @@ <h2 class="calendar-year-label">
             <div class="calendar-month">
                 <h3 class="calendar-month-label">
                     {% if cal_month.month_url %}
-                    <a href="{{ cal_month.month_url }}">{{ cal_month.month_name }}</a>
+                    <a href="{{ cal_month.month_url }}" aria-label="Archive for {{ cal_month.month_name }} {{ year_group.year }}">{{ cal_month.month_name }}</a>
                     {% else %}
                     {{ cal_month.month_name }}
                     {% endif %}

tests/test_renderer.py

@@ -59,9 +59,15 @@ def test_format_date_links(self) -> None:
         """Test that format_date produces archive links for year, month and day."""
         date = dt.datetime(2026, 2, 20, 15, 46, 0, tzinfo=dt.UTC)
         formatted = TemplateRenderer._format_date(date)
-        assert '<a href="/2026/">2026</a>' in formatted
-        assert '<a href="/2026/02/">02</a>' in formatted
-        assert '<a href="/2026/02/20/">20</a>' in formatted
+        assert '<a href="/2026/" aria-label="Archive for 2026">2026</a>' in formatted
+        assert (
+            '<a href="/2026/02/" aria-label="Archive for February 2026">02</a>'
+            in formatted
+        )
+        assert (
+            '<a href="/2026/02/20/" aria-label="Archive for February 20, 2026">20</a>'
+            in formatted
+        )
         assert "15:46:00" in formatted
         assert "UTC" in formatted