Added RSS feed.

Author: jgebal

.github/workflows/build_pages.yml

@@ -21,5 +21,6 @@ jobs:
           pip install mkdocs-include-markdown-plugin
           pip install mike
           pip install mkdocs-git-committers-plugin-2
+          pip install mkdocs-rss-plugin
       - name: Build website
         run: mkdocs gh-deploy --verbose

README.md

@@ -63,6 +63,20 @@ Related configuration:
 The hook is plain Python run by MkDocs itself - no extra package needs to be installed.
 Note that it relies on MkDocs hooks and on internals of the Material blog plugin, so it needs to be revisited when upgrading Material or migrating to [Zensical](https://zensical.org/).
 
+## RSS feed
+
+Announcements are published as RSS and JSON feeds by the [mkdocs-rss-plugin](https://guts.github.io/mkdocs-rss-plugin/), configured under `rss:` in [mkdocs.yml](mkdocs.yml):
+
+- [feed_rss_created.xml](https://www.utplsql.org/feed_rss_created.xml) - newest posts first (the one to subscribe to),
+- [feed_rss_updated.xml](https://www.utplsql.org/feed_rss_updated.xml) - most recently updated posts first,
+- `feed_json_created.json` and `feed_json_updated.json` - the same as [JSON Feed](https://www.jsonfeed.org/).
+
+Only posts under `docs/announcements/posts/` are included (`match_path`), up to 20 newest.
+Dates come from `date.created` / `date.updated` in the post front matter (git history is used when `date.updated` is missing), and `categories` become RSS categories.
+The item description is the post `description:` or the summary generated by [hooks/latest_posts.py](hooks/latest_posts.py) - the same text as on the home page card.
+
+The feeds are linked from the home page, the Announcements page and the RSS icon in the footer, and Material adds `<link rel="alternate" type="application/rss+xml">` to every page, so feed readers find them automatically.
+
 ## Local setup
 
 If you want to generate and preview the website locally, you will need to have [python and pip installed](https://squidfunk.github.io/mkdocs-material/getting-started/))
@@ -73,6 +87,7 @@ pip install mkdocs-material
 pip install mkdocs-git-revision-date-localized-plugin
 pip install mkdocs-include-markdown-plugin
 pip install mkdocs-git-committers-plugin-2
+pip install mkdocs-rss-plugin
 pip install mike
 ```
 

docs/announcements/index.md

@@ -1 +1,3 @@
 # Announcements
+
+[:material-rss: Subscribe via RSS](/feed_rss_created.xml)

docs/index.md

@@ -14,7 +14,7 @@ Write and run tests directly in PL/SQL, integrate with your CI/CD pipeline, and
 
 <!-- latest-posts -->
 
-[All announcements :octicons-arrow-right-24:](announcements/index.md)
+[All announcements :octicons-arrow-right-24:](announcements/index.md) · [:material-rss: RSS feed](/feed_rss_created.xml)
 
 ---
 

hooks/latest_posts.py

@@ -11,7 +11,7 @@
   3. the list items (release notes), without author, PR and issue references.
 
 Posts without a `description:` also get the generated summary as their
-`<meta name="description">`.
+`<meta name="description">` and RSS feed item description.
 """
 import posixpath
 import re
@@ -51,6 +51,12 @@
 
 
 def on_page_markdown(markdown, page, config, files):
+    # Set before the page is rendered, so the RSS plugin picks it up as well
+    if isinstance(page, Post) and not page.meta.get("description"):
+        summary = _summary(page)
+        if summary:
+            page.meta["description"] = re.sub(r"`|\*\*", "", summary)
+            page.meta["description_generated"] = True
     if PLACEHOLDER not in markdown:
         return markdown
     blog = config.plugins["material/blog"].blog
@@ -61,15 +67,6 @@ def on_page_markdown(markdown, page, config, files):
     return markdown.replace(PLACEHOLDER, html)
 
 
-# Runs after Markdown of all pages is processed, so the cards are not affected
-def on_page_context(context, page, config, nav):
-    if isinstance(page, Post) and not page.meta.get("description"):
-        summary = _summary(page)
-        if summary:
-            page.meta["description"] = re.sub(r"`|\*\*", "", summary)
-    return context
-
-
 def _card(post, link):
     categories = post.config.categories
     icon = next((ICONS[c] for c in categories if c in ICONS), DEFAULT_ICON)
@@ -87,7 +84,8 @@ def _card(post, link):
 
 
 def _summary(post):
-    if post.meta.get("description"):
+    # A generated description is plain text - rebuild it, so cards keep code formatting
+    if post.meta.get("description") and not post.meta.get("description_generated"):
         return _truncate(_plain(post.meta["description"]))
     body = SETEXT_HEADING.sub("", post.markdown)
     first_item = LIST_ITEM.search(body)

mkdocs.yml

@@ -75,6 +75,9 @@ extra:
       link: https://github.com/utPLSQL
     - icon: fontawesome/solid/envelope
       link: mailto:utPLSQL@utPLSQL.org
+    - icon: fontawesome/solid/rss
+      link: https://www.utplsql.org/feed_rss_created.xml
+      name: Announcements RSS feed
   consent:
     title: Cookie consent
     description: >- 
@@ -126,6 +129,16 @@ plugins:
       post_url_format: "{slug}"     # keeps URLs clean
       archive: false
       categories: true
+  - rss:
+      match_path: "announcements/posts/.*"
+      feed_title: "utPLSQL Announcements"
+      feed_description: "Releases and news from the utPLSQL project"
+      image: https://www.utplsql.org/assets/icon-transparent.png
+      date_from_meta:
+        as_creation: date.created
+        as_update: date.updated
+      categories:
+        - categories
 nav:
   - Home: index.md
   - Announcements: