Merge pull request #371 from davep/copilot/add-read-time-wpm-configuration

Author: davep

ChangeLog.md

@@ -7,6 +7,9 @@
 - Added a table of longest posting streaks to the stats page, showing the
   top 10 consecutive-day posting streaks of two or more days.
   ([#369](https://github.com/davep/blogmore/pull/369))
+- 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))
 
 ## v2.10.0
 

blogmore.yaml.example

@@ -66,9 +66,13 @@ posts_per_feed: 20
 # with_stats: false
 
 # Optional: Show estimated reading time on posts (default: false)
-# Displays the approximate time to read each post based on 200 words per minute.
+# Displays the approximate time to read each post based on the configured WPM.
 # with_read_time: false
 
+# Optional: Words per minute used when calculating estimated reading time (default: 200)
+# Must be a positive integer. Configuration file only.
+# read_time_wpm: 200
+
 # Optional: Show "Generated with BlogMore" footer line (default: true)
 # Set to false to hide the footer attribution line.
 # with_advert: true

docs/configuration.md

@@ -320,7 +320,7 @@ with_stats: true
 
 #### `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.
+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.
 
 **Type:** Boolean  
 **Default:** `false`
@@ -329,6 +329,17 @@ Show estimated reading time on each post. When enabled, BlogMore calculates the
 with_read_time: true
 ```
 
+#### `read_time_wpm`
+
+Words per minute used when calculating estimated reading time.  Adjust this value to match the expected reading speed of your audience.  Must be a positive integer.  This is a **configuration file only** option — it cannot be set on the command line.
+
+**Type:** Integer  
+**Default:** `200`
+
+```yaml
+read_time_wpm: 250
+```
+
 #### `post_path`
 
 Format string that controls the output path (and therefore the URL) of every blog post.  This is a **configuration file only** option — it cannot be set on the command line.

src/blogmore/config.py

@@ -64,6 +64,7 @@
         "head",
         "light_mode_code_style",
         "dark_mode_code_style",
+        "read_time_wpm",
     }
 )
 
@@ -528,4 +529,24 @@ def parse_site_config_from_dict(
     else:
         kwargs["dark_mode_code_style"] = raw_dark_style
 
+    # --- read_time_wpm -------------------------------------------------------
+    if "read_time_wpm" in config:
+        raw_wpm = config["read_time_wpm"]
+        if not isinstance(raw_wpm, int) or isinstance(raw_wpm, bool):
+            errors.append(
+                "read_time_wpm in the configuration file must be an integer; "
+                "using the default"
+            )
+            kwargs["read_time_wpm"] = 200
+        elif raw_wpm <= 0:
+            errors.append(
+                "read_time_wpm in the configuration file must be a positive "
+                "integer; using the default"
+            )
+            kwargs["read_time_wpm"] = 200
+        else:
+            kwargs["read_time_wpm"] = raw_wpm
+    else:
+        kwargs["read_time_wpm"] = 200
+
     return kwargs, errors

src/blogmore/generator.py

@@ -569,6 +569,11 @@ def generate(self) -> None:
         )
         print(f"Found {len(posts)} posts")
 
+        # Apply configured reading-speed to every post so that reading_time
+        # reflects the user's read_time_wpm setting.
+        for post in posts:
+            post.words_per_minute = self.site_config.read_time_wpm
+
         # Apply default author to posts that don't have one
         if self.site_config.default_author:
             for post in posts:

src/blogmore/parser.py

@@ -134,6 +134,7 @@ class Post:
     draft: bool = False
     metadata: dict[str, Any] | None = None
     url_path: str | None = field(default=None, repr=False, compare=False)
+    words_per_minute: int = field(default=200, repr=False, compare=False)
 
     @property
     def slug(self) -> str:
@@ -206,7 +207,7 @@ def reading_time(self) -> int:
         Returns:
             Estimated reading time in minutes (minimum 1 minute)
         """
-        return calculate_reading_time(self.content)
+        return calculate_reading_time(self.content, self.words_per_minute)
 
     @property
     def modified_date(self) -> dt.datetime | None:

src/blogmore/site_config.py

@@ -117,6 +117,17 @@ class SiteConfig:
     with_read_time: bool = False
     """Whether to show estimated reading time on posts."""
 
+    read_time_wpm: int = 200
+    """Words per minute used when calculating estimated reading time.
+
+    Controls the reading speed assumption used by the reading-time estimator.
+    Must be a positive integer.  The default value of 200 WPM reflects a
+    widely-cited average adult reading speed.
+
+    This is a **configuration file only** option — it cannot be set on the
+    command line.  Defaults to ``200``.
+    """
+
     include_drafts: bool = False
     """Whether to include draft posts in generation."""
 

tests/test_config.py

@@ -1419,3 +1419,65 @@ def test_extra_stylesheets_cli_override_wins_over_config(
 
         assert errors == []
         assert kwargs["extra_stylesheets"] == ["cli.css"]
+
+    def test_read_time_wpm_valid_value(self, tmp_path: Path) -> None:
+        """A valid positive integer read_time_wpm is accepted."""
+        from blogmore.config import parse_site_config_from_dict
+
+        kwargs, errors = parse_site_config_from_dict({"read_time_wpm": 250}, tmp_path)
+
+        assert errors == []
+        assert kwargs["read_time_wpm"] == 250
+
+    def test_read_time_wpm_absent_resets_to_default(self, tmp_path: Path) -> None:
+        """When read_time_wpm is absent from config, it resets to the default (200)."""
+        from blogmore.config import parse_site_config_from_dict
+
+        kwargs, errors = parse_site_config_from_dict({}, tmp_path)
+
+        assert errors == []
+        assert kwargs["read_time_wpm"] == 200
+
+    def test_read_time_wpm_zero_produces_error(self, tmp_path: Path) -> None:
+        """A read_time_wpm of zero produces an error and uses the default."""
+        from blogmore.config import parse_site_config_from_dict
+
+        kwargs, errors = parse_site_config_from_dict({"read_time_wpm": 0}, tmp_path)
+
+        assert len(errors) == 1
+        assert "read_time_wpm" in errors[0]
+        assert kwargs["read_time_wpm"] == 200
+
+    def test_read_time_wpm_negative_produces_error(self, tmp_path: Path) -> None:
+        """A negative read_time_wpm produces an error and uses the default."""
+        from blogmore.config import parse_site_config_from_dict
+
+        kwargs, errors = parse_site_config_from_dict({"read_time_wpm": -50}, tmp_path)
+
+        assert len(errors) == 1
+        assert "read_time_wpm" in errors[0]
+        assert kwargs["read_time_wpm"] == 200
+
+    def test_read_time_wpm_non_integer_produces_error(self, tmp_path: Path) -> None:
+        """A non-integer read_time_wpm produces an error and uses the default."""
+        from blogmore.config import parse_site_config_from_dict
+
+        kwargs, errors = parse_site_config_from_dict(
+            {"read_time_wpm": "fast"}, tmp_path
+        )
+
+        assert len(errors) == 1
+        assert "read_time_wpm" in errors[0]
+        assert kwargs["read_time_wpm"] == 200
+
+    def test_read_time_wpm_bool_produces_error(self, tmp_path: Path) -> None:
+        """A boolean read_time_wpm produces an error (booleans are subclasses of int)."""
+        from blogmore.config import parse_site_config_from_dict
+
+        kwargs, errors = parse_site_config_from_dict(
+            {"read_time_wpm": True}, tmp_path
+        )
+
+        assert len(errors) == 1
+        assert "read_time_wpm" in errors[0]
+        assert kwargs["read_time_wpm"] == 200

tests/test_parser.py

@@ -437,6 +437,31 @@ def hello():
         # Reading time should be calculated from the actual text content
         assert post.reading_time >= 1
 
+    def test_reading_time_uses_words_per_minute_field(self) -> None:
+        """Test that reading_time uses the words_per_minute field."""
+        # 200 words at 100 WPM = 2 minutes; at 200 WPM (default) = 1 minute
+        content = " ".join(["word"] * 200)
+        post = Post(
+            path=Path("test.md"),
+            title="Test",
+            content=content,
+            html_content=f"<p>{content}</p>",
+            words_per_minute=100,
+        )
+        assert post.reading_time == 2
+
+    def test_reading_time_default_words_per_minute(self) -> None:
+        """Test that reading_time defaults to 200 WPM."""
+        # 200 words at 200 WPM (default) = 1 minute
+        content = " ".join(["word"] * 200)
+        post = Post(
+            path=Path("test.md"),
+            title="Test",
+            content=content,
+            html_content=f"<p>{content}</p>",
+        )
+        assert post.reading_time == 1
+
     def test_modified_date_none_when_no_metadata(self) -> None:
         """Test that modified_date returns None when metadata is None."""
         post = Post(