Feat: ChangeLog output in RSS, Atom and Markdown

diff --git a/ChangeLog.md b/ChangeLog.md
index 4cec6908355e40a04c0c5b174b636440c0ed8f90..685efcb6fb9385a1fa8b56eb701aa651d712583f 100644 (file)
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -1,5 +1,19 @@
 # ChangeLog
 
+## v0.5.0 - 2025-11-22
+
+* [x] Changelog support:
+  * [~] Build the recent changes section through a `snippets/changes.md` file?
+      This is partially implemented, but commented.
+      As an alternative (or meanwhile), the notebook can be used.
+  * [x] Alternativelly, build the recent changes using a `snippets/changes.yml`
+        or just `_changes.yml` that gets compilet into a `snippets/changes.md`
+        and into RSS and Atom files that goes in the build.
+  * [x] Add RSS/Atom `rel` elements in the HTML head.
+  * [x] Validate the generated feeds (RSS and Atom).
+  * [x] Add a regular link like "Follow updates in this book".
+  * [x] Document the feature.
+
 ## v0.4.1 - 2025-11-20
 
 * [x] Add anchors in the notebook HTML preamble.

diff --git a/TODO.md b/TODO.md
index acfb013a205b7f1bc2628233ddd25d0aea7215cf..d69115463534132848a6901a63716d42d6dec318 100644 (file)
--- a/TODO.md
+++ b/TODO.md
@@ -35,15 +35,6 @@
   * [ ] Add the corresponding BibTeX entry.
   * [ ] How to cite, by using ~~`@projectName`~~ an example in the PDF
         frontmatter.
-* [ ] Recent changes:
-  * [ ] Build the recent changes section through a `snippets/changes.md` file?
-      This is partially implemented, but commented.
-      As an alternative (or meanwhile), the notebook can be used.
-  * [ ] Alternativelly, build the recent changes using a `snippets/changes.yml`
-        or just `_changes.yml` that gets compilet into a `snippets/changes.md`
-        and into a RSS file that goes in the build.
-        This RSS them can be linked as a `rel` element in the HTML, along with
-        a regular link like "Follow updates in this book".
 * [ ] Localization:
   * [ ] Make sure to properly localized the build date string.
   * [ ] Setup a PO-file workflow for translating the structure and templates?

diff --git a/_changes.yml b/_changes.yml
new file mode 100644 (file)
index 0000000..4b3f3e1
--- /dev/null
+++ b/_changes.yml
@@ -0,0 +1,11 @@
+---
+# Each entry should have the date all supported formats (Atom, RSS and Markdown)
+changelog: Changelog
+version: Version
+versions:
+  - id: 0.5.0
+    date_atom: 2025-11-22T21:30:00-03:00
+    date_rss: 22 Sep 2025 21:30:00 -0300
+    date_markdown: 2025-11-22
+    summary: |
+      * RSS/Atom feed support.

diff --git a/bin/assemble b/bin/assemble
index 04ae7855ab726409ad9771a8db7e599641b3f98b..86913211c06ef55211bc0a24aba6971368b6a980 100755 (executable)
--- a/bin/assemble
+++ b/bin/assemble
@@ -32,3 +32,16 @@ fi
 if [ -e "$NOTEBOOK" ]; then
   mv $NOTEBOOK $BUILD/notes
 fi
+
+# Build changelog
+$DIRNAME/compile-changelog
+
+# Move Atom feed
+if [ -e "$BASEDIR/atom.xml" ]; then
+  mv $BASEDIR/atom.xml $BUILD
+fi
+
+# Move RSS feed
+if [ -e "$BASEDIR/rss.xml" ]; then
+  mv $BASEDIR/rss.xml $BUILD
+fi

diff --git a/bin/compile-changelog b/bin/compile-changelog
new file mode 100755 (executable)
index 0000000..c72a0a4
--- /dev/null
+++ b/bin/compile-changelog
@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Feed compiler
+# Based on https://recursewithless.net/projects/pandoc-feeds.html
+#
+
+# Parameters
+BASENAME="`basename $0 | sed -e 's/\(.\)/\U\1/'`"
+DIRNAME="`dirname $0`"
+BASEDIR="$DIRNAME/.."
+CHANGES="$BASEDIR/_changes.yml"
+CHANGELOG="$BASEDIR/content/notes/00-changelog/changelog.md"
+BOOK="$BASEDIR/_book.yml"
+COMMON="$BASEDIR/_common.yml"
+META="$BASEDIR/.metadata/feed.yml"
+RSS_TMPL="$BASEDIR/templates/rss.xml"
+ATOM_TMPL="$BASEDIR/templates/atom.xml"
+CHANGELOG_TMPL="$BASEDIR/templates/changelog.md"
+CHANGES_TMPL="$BASEDIR/templates/_changes.yml"
+URL="$BASEDIR/snippets/url.txt"
+CONTACT="$BASEDIR/snippets/contact.txt"
+
+# Ensure the changes file exists
+if [ ! -e "$CHANGES" ]; then
+  # Create sample $CHANGES file
+  cp $CHANGES_TMPL $CHANGES
+fi
+
+# Create .metadata/feed.yaml with the needed metadata
+mkdir -p "`dirname $META`"
+echo '---' > $META
+echo "url: $(cat $URL)"       >> $META
+echo "email: $(cat $CONTACT)" >> $META
+
+# Generate the Atom feed
+pandoc -M updated="$(LC_ALL=C date --iso-8601='seconds')" \
+    --metadata-file=$META                                 \
+    --metadata-file=$CHANGES                              \
+    --metadata-file=$BOOK                                 \
+    --metadata-file=$COMMON                               \
+    --template=$ATOM_TMPL                                 \
+    -t plain \
+    -o atom.xml < /dev/null
+
+# Generate the RSS feed
+pandoc -M updated="$(LC_ALL=C date '+%d %b %Y %T %z')" \
+    --metadata-file=$META                              \
+    --metadata-file=$CHANGES                           \
+    --metadata-file=$BOOK                              \
+    --metadata-file=$COMMON                            \
+    --template=$RSS_TMPL                               \
+    -t plain \
+    -o rss.xml < /dev/null
+
+# Generate changelog.md
+mkdir -p "`dirname $CHANGELOG`"
+pandoc                          \
+    --metadata-file=$META       \
+    --metadata-file=$CHANGES    \
+    --metadata-file=$BOOK       \
+    --metadata-file=$COMMON     \
+    --template=$CHANGELOG_TMPL  \
+    -t plain \
+    -o $CHANGELOG < /dev/null
+
+# Fix list formatting in the Markdown output
+sed -i -e 's/-   /* /' $CHANGELOG

diff --git a/content/notes/00-changelog/changelog.md b/content/notes/00-changelog/changelog.md
new file mode 100644 (file)
index 0000000..9d4e380
--- /dev/null
+++ b/content/notes/00-changelog/changelog.md
@@ -0,0 +1,8 @@
+# Changelog {#changelog .unnumbered}
+
+<!-- DO NOT manually edit this file: it's generated from _changes.yml -->
+<!-- Any updates here will be overwritten -->
+
+## Version 0.5.0 - 2025-11-22
+
+* RSS/Atom feed support.

diff --git a/content/sections/02-features/features.md b/content/sections/02-features/features.md
index 606ed1fbe2d9450381014a9098cab17fa09c74db..2f5aa08d7ea7dbdca9743b9c872940dd62fea83d 100644 (file)
--- a/content/sections/02-features/features.md
+++ b/content/sections/02-features/features.md
@@ -17,6 +17,9 @@ Main Bookup features:
 
 * Adds the compilation metadata:
   * Version based on Git tag or commit.
+
   * Compilation date.
 
 * Localization support: templates can be easily translated to other languages.
+
+* RSS, Atom and Markdown changelogs.

diff --git a/content/sections/10-structure/structure.md b/content/sections/10-structure/structure.md
index 263a764668f6865a96e713c5dbe18beffc5852e8..fcc315011c7d89fba281cf5d0e9fada081040dac 100644 (file)
--- a/content/sections/10-structure/structure.md
+++ b/content/sections/10-structure/structure.md
@@ -21,3 +21,5 @@ A Bookup project folder structure looks like this:
 * `vendor/bookup`: where the Bookup codebase actually resides:
   * `content`: Bookup documentation.
   * `vendor/{Fuse.js,}`: dependencies.
+* `_changes.yml`: to track changes in your book, used to build RSS and Atom
+  feeds, as well as a ChangeLog in Markdown format.

diff --git a/structure/book/en/00-header.html b/structure/book/en/00-header.html
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..94b4620ff10f52126fa436337c6a9ebe70536b76 100644 (file)
--- a/structure/book/en/00-header.html
+++ b/structure/book/en/00-header.html
@@ -0,0 +1,2 @@
+<link rel="alternate" type="application/atom+xml" href="/atom.xml" />
+<link rel="alternate" type="application/rss+xml" href="/rss.xml" />

diff --git a/structure/book/en/00-preamble.md b/structure/book/en/00-preamble.md
index 9a21272e4af2930e8909f56c215e60a7ad964189..2db371a6c087892c8a087fc499bf28ace05b539a 100644 (file)
--- a/structure/book/en/00-preamble.md
+++ b/structure/book/en/00-preamble.md
@@ -25,6 +25,8 @@ if (knitr::is_html_output()) {
   cat('<br/>')
   cat('Older versions available in the <a href="/archive">archive</a>.')
   cat('<br/>')
+  cat('Follow updates in this book: <a href="/rss.xml">RSS</a> / <a href="/atom.xml">Atom</a>.')
+  cat('<br/>')
   cat('Notebook available <a href="/notes">here</a>.')
   cat('<br/><br/>')
   cat(readLines('snippets/project.txt'))

diff --git a/structure/book/pt-br/00-preamble.md b/structure/book/pt-br/00-preamble.md
index ed9e341248a887c565b6653cfffb9002246737ae..6e92a1cf7b790a4ddfa44e50afa5953629a21ef5 100644 (file)
--- a/structure/book/pt-br/00-preamble.md
+++ b/structure/book/pt-br/00-preamble.md
@@ -25,6 +25,8 @@ if (knitr::is_html_output()) {
   cat('<br/>')
   cat('Versões anteriores disponíveis no <a href="/archive">arquivo</a>.')
   cat('<br/>')
+  cat('Acompanhe as atualizações deste livro: <a href="/rss.xml">RSS</a> / <a href="/atom.xml">Atom</a>.')
+  cat('<br/>')
   cat('Caderno de anotações disponível <a href="/notes">aqui</a>.')
   cat('<br/><br/>')
   cat(readLines('snippets/project.txt'))

diff --git a/templates/_changes.yml b/templates/_changes.yml
new file mode 100644 (file)
index 0000000..7c93b35
--- /dev/null
+++ b/templates/_changes.yml
@@ -0,0 +1,18 @@
+---
+# Each entry should have the date all supported formats (Atom, RSS and Markdown)
+changelog: Changelog
+version: version
+versions:
+  - id: 
+    date_atom: 
+    date_rss: 
+    date_markdown: 
+    summary: 
+
+  # Example
+  #- id: 0.1.0
+  #  date_atom: 2025-11-22T21:30:00-03:00
+  #  date_rss: 22 Sep 2025 21:30:00 -0300
+  #  date_markdown: 2025-11-22
+  #  summary: |
+  #    * Initial version.

diff --git a/templates/atom.xml b/templates/atom.xml
new file mode 100644 (file)
index 0000000..c521bd9
--- /dev/null
+++ b/templates/atom.xml
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <author>
+    <name>$author$</name>
+    <email>$email$</email>
+  </author>
+  <title>$title$</title>
+  <id>$url$/</id>
+  <link rel="self" href="//$url$/atom.xml" />
+  <updated>$updated$</updated>
+
+  $for(versions)$
+  <entry>
+    <id>$url$/archive/$versions.id$</id>
+    <title>$version$ $versions.id$</title>
+    <updated>$versions.date_atom$</updated>
+    <link href="$url$/archive/$versions.id$" />
+    <summary>$versions.summary$</summary>
+  </entry>
+  $endfor$
+</feed>

diff --git a/templates/changelog.md b/templates/changelog.md
new file mode 100644 (file)
index 0000000..61a09a3
--- /dev/null
+++ b/templates/changelog.md
@@ -0,0 +1,10 @@
+# $changelog$ {#changelog .unnumbered}
+
+<!-- DO NOT manually edit this file: it's generated from _changes.yml -->
+<!-- Any updates here will be overwritten -->
+$for(versions)$
+
+## $version$ $versions.id$ - $versions.date_markdown$
+
+$versions.summary$
+$endfor$

diff --git a/templates/rss.xml b/templates/rss.xml
new file mode 100644 (file)
index 0000000..9c33d87
--- /dev/null
+++ b/templates/rss.xml
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+<channel>
+ <title>$title$</title>
+ <description>$subtitle$</description>
+ <link>$url$/</link>
+ <atom:link href="//$url$/rss.xml" rel="self" type="application/rss+xml" />
+ <lastBuildDate>$updated$</lastBuildDate>
+ <ttl>1440</ttl>
+
+ $for(versions)$
+ <item>
+  <title>$version$ $versions.id$</title>
+  <description>$versions.summary$</description>
+  <link>$url$/archive/$versions.id$</link>
+  <guid>$url$/archive/$versions.id$</guid>
+  <pubDate>$versions.date_rss$</pubDate>
+ </item>
+ $endfor$
+</channel>
+</rss>