From: Silvio Rhatto Date: Sun, 23 Nov 2025 01:28:11 +0000 (-0300) Subject: Feat: ChangeLog output in RSS, Atom and Markdown X-Git-Tag: 0.5.0~3 X-Git-Url: https://gitweb.fluxo.info/?a=commitdiff_plain;h=56e076d4ff8b8fd65f16f5b9a647acf09a11f564;p=bookup.git Feat: ChangeLog output in RSS, Atom and Markdown --- diff --git a/ChangeLog.md b/ChangeLog.md index 4cec690..685efcb 100644 --- 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 acfb013..d691154 100644 --- 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 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 04ae785..8691321 100755 --- 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 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 index 0000000..9d4e380 --- /dev/null +++ b/content/notes/00-changelog/changelog.md @@ -0,0 +1,8 @@ +# Changelog {#changelog .unnumbered} + + + + +## 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 606ed1f..2f5aa08 100644 --- 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 263a764..fcc3150 100644 --- 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 e69de29..94b4620 100644 --- a/structure/book/en/00-header.html +++ b/structure/book/en/00-header.html @@ -0,0 +1,2 @@ + + diff --git a/structure/book/en/00-preamble.md b/structure/book/en/00-preamble.md index 9a21272..2db371a 100644 --- a/structure/book/en/00-preamble.md +++ b/structure/book/en/00-preamble.md @@ -25,6 +25,8 @@ if (knitr::is_html_output()) { cat('
') cat('Older versions available in the archive.') cat('
') + cat('Follow updates in this book: RSS / Atom.') + cat('
') cat('Notebook available here.') cat('

') cat(readLines('snippets/project.txt')) diff --git a/structure/book/pt-br/00-preamble.md b/structure/book/pt-br/00-preamble.md index ed9e341..6e92a1c 100644 --- 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('
') cat('Versões anteriores disponíveis no arquivo.') cat('
') + cat('Acompanhe as atualizações deste livro: RSS / Atom.') + cat('
') cat('Caderno de anotações disponível aqui.') cat('

') cat(readLines('snippets/project.txt')) diff --git a/templates/_changes.yml b/templates/_changes.yml new file mode 100644 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 index 0000000..c521bd9 --- /dev/null +++ b/templates/atom.xml @@ -0,0 +1,21 @@ + + + + $author$ + $email$ + + $title$ + $url$/ + + $updated$ + + $for(versions)$ + + $url$/archive/$versions.id$ + $version$ $versions.id$ + $versions.date_atom$ + + $versions.summary$ + + $endfor$ + diff --git a/templates/changelog.md b/templates/changelog.md new file mode 100644 index 0000000..61a09a3 --- /dev/null +++ b/templates/changelog.md @@ -0,0 +1,10 @@ +# $changelog$ {#changelog .unnumbered} + + + +$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 index 0000000..9c33d87 --- /dev/null +++ b/templates/rss.xml @@ -0,0 +1,21 @@ + + + + $title$ + $subtitle$ + $url$/ + + $updated$ + 1440 + + $for(versions)$ + + $version$ $versions.id$ + $versions.summary$ + $url$/archive/$versions.id$ + $url$/archive/$versions.id$ + $versions.date_rss$ + + $endfor$ + +