First version of replacing hugo-atom-feed (issue #714)

[kreczko]

Fixes #714

RFC 4287 implementation of a Atom hugo template

The in-tree Atom template follows RFC 4287 by providing:

• Required feed metadata: title, id, updated, and author.
• Required entry metadata: title, id, and updated.
• Optional metadata: subtitle, generator, published, categories, language, HTML content, and self/alternate links.
• Valid empty feeds, stable timestamps, feed-size limits, and HTML feed discovery.

Tests cover XML validity, required element cardinality, metadata values, entry ordering and limits, RFC 3339 dates, HTML escaping, categories, author fallback, empty feeds, and discovery links.

AI assistance

AI tools were used to:

• help interpret the requirements of RFC 4287;
• help design tests for specific RFC 4287 requirements and edge cases;
• assist with debugging template-rendering and test failures.
• to make my notes readable for this PR

The resulting implementation and generated output were reviewed and validated through the repository’s test suite.

Other notes

This is intentionally a basic implementation, focused on the core requirements of RFC 4287 and the features currently used by the Scientific Python blog feed.

Additional behaviour such as per-entry authors, related-post links, tracking parameters, or multilingual links can be added in response to concrete use cases and review feedback.

Pixi was introduced to provide a reproducible, pinned Hugo and Dart Sass environment for these tests. It also avoids installation-specific behaviour such as Snap confinement (my dev machine) and could be reused by other theme tests and development tasks. It proved convenient here, but the change is not essential to the Atom implementation and can be removed if maintainers would prefer to keep the existing tooling.

[netlify]

✅ Deploy Preview for scientific-python-hugo-theme ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	06262b9
🔍 Latest deploy log	https://app.netlify.com/projects/scientific-python-hugo-theme/deploys/6a7c45be57b0d70008b1418a
😎 Deploy Preview	https://deploy-preview-715--scientific-python-hugo-theme.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 94 Accessibility: 97 Best Practices: 100 SEO: 91 PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[agriyakhetarpal]

Wow, thanks @kreczko! I think it is great to have our own RFC 4287 support. The Pixi integration is also nice, which we've discussed on a few occasions before, but I haven't gotten around to implementing it.

However, in my humble opinion, I don't believe this repository is the best place to introduce this code, as such. Rather, it would be better if this could be hosted on your GitHub account or elsewhere. We could then rely on your work by adding it as a submodule in the repository, just like the current means of integration of hugo-atom-feed. I think it will be fine to mention there that the Atom feed provided only works for features desired by the https://github.com/scientific-python/scientific-python-hugo-theme repository, and that you can consider adding more features provided there is interest and provided you are willing to maintain it going forward.

The reason is that this is a lot of code, and it will be something that will be tricky for us to maintain going forward, if we were to add it. I know this layout is unlikely to change often, but the premise of these extra tests and related test scaffolding to run just for the sake of Atom feed support does not give me confidence that we will be able to maintain them.

Similarly, adding Pixi and a lockfile is also desirable, but it needs to be its own PR instead, as you suggest.

[kreczko]

However, in my humble opinion, I don't believe this repository is the best place to introduce this code, as such. Rather, it would be better if this could be hosted on your GitHub account or elsewhere.

Understood. Since I am only using the scipy hugo template for FAST-HEP, would it be OK to move this code to https://github.com/FAST-HEP/ ?
Then this PR would only contain the submodule change.

The Pixi integration is also nice, which we've discussed on a few occasions before, but I haven't gotten around to implementing it.
...
Similarly, adding Pixi and a lockfile is also desirable, but it needs to be its own PR instead, as you suggest.
If that's desirable, I can move that to a separate PR - do you have a link to the discussion or a summary as to what is expected?
Do you envision a partial or full replacement of the Makefiles? e.g.

[tasks.doc-build]
cmd = "hugo --themesDir=../.."
cwd = "doc"

[tasks.doc-serve]
cmd = "hugo --printI18nWarnings serve --themesDir=../.. --disableFastRender --poll 1000ms"
cwd = "doc"

Also, what about the change to baseof.html?

   {{- range .AlternativeOutputFormats }}
    <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink }}">
    {{- end }}

This is to advertise the additional output formats - it would be blank if they are not defined.

Finally, while working on this I came across some updates for newer Hugo versions:
The _default folder is removed

Everything in layouts/_default needs to move to layouts - if I don't forget, I will create a new issue for this.

[agriyakhetarpal]

However, in my humble opinion, I don't believe this repository is the best place to introduce this code, as such. Rather, it would be better if this could be hosted on your GitHub account or elsewhere.

Understood. Since I am only using the scipy hugo template for FAST-HEP, would it be OK to move this code to @FAST-HEP ? Then this PR would only contain the submodule change.

Yes, that would be great; thank you!

The Pixi integration is also nice, which we've discussed on a few occasions before, but I haven't gotten around to implementing it.
...
Similarly, adding Pixi and a lockfile is also desirable, but it needs to be its own PR instead, as you suggest.
If that's desirable, I can move that to a separate PR - do you have a link to the discussion or a summary as to what is expected?
Do you envision a partial or full replacement of the Makefiles? e.g.

[tasks.doc-build]
cmd = "hugo --themesDir=../.."
cwd = "doc"

[tasks.doc-serve]
cmd = "hugo --printI18nWarnings serve --themesDir=../.. --disableFastRender --poll 1000ms"
cwd = "doc"

I don't think we've ever gotten around to creating a discussion/summary issue, unfortunately. However, we are on the same page – we should fully replace the Makefiles, since the steps are all one-liners and are not complicated. We can probably share the same environment across all tasks with a shared Hugo installation, so we don't waste much space (which I think is the default behaviour?).

Going a little further, our overall discussion with Pixi integration was also to do so for the websites this theme caters for. This way, it would be easier to build them using commands via Pixi package definitions in their repositories. This way, it would make for a nicer developer experience.

Also, what about the change to baseof.html?

   {{- range .AlternativeOutputFormats }}
    <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink }}">
    {{- end }}

This is to advertise the additional output formats - it would be blank if they are not defined.

Finally, while working on this I came across some updates for newer Hugo versions: The _default folder is removed

Everything in layouts/_default needs to move to layouts - if I don't forget, I will create a new issue for this.

I'd say the change in baseof.html is useful to keep here, and so is moving the files in layouts/_default to layouts. I think it would be easier if we migrate the theme according to newer Hugo versions one-by-one – we can have a PR that adds your Atom feed integrator as a submodule and updates to 0.156.0, thereby fixing #714, and then we already have #712, so we can probably put the layouts change in there and update to Hugo 0.164.0.

[kreczko]

I have moved the changes to https://github.com/FAST-HEP/hugo-atom-layout and reduced the PR to

• a submodule change
• config update (theme)
• Hugo version update to 1.58.0 (netlify)

Note: The baseof.html change is now in layouts/partials/head.html which scipy theme uses.

[kreczko]

Note: I had to update to 0.158.0 for the compatibility of site.Language.Locale - the old languageCode is ignored.

[agriyakhetarpal]

Thank you, @kreczko! I am testing the Atom feed generated from the deployment preview of this PR here: https://deploy-preview-715--scientific-python-hugo-theme.netlify.app/blog/atom.xml, versus the one here: https://blog.scientific-python.org/atom.xml

I use NetNewsWire (https://netnewswire.com) as my feed reader. I wonder if you could discuss those with me here and answer my possibly stupid questions about the two differences I found, considering you have experience in this field:

1. The original Atom feed also adds a ?utm_source=atom_feed to the links, while the Fast-HEP implementation does not. While I'm not usually a fan of tracking parameters, I think they were added for a reason, and we should remain compatible with what has existed before. Could we add it?
2. The original Atom feed adds a blockquote preamble for each blog post: , i.e., "mplhep is a Scikit-HEP package that turns matplotlib into [...]", while Fast-HEP's does not:
   
   Could we make it grab the summary from each page and add it to the feed in the same way as before?

The rest of it looks all great now, and I can confirm that no output is lost anywhere – I compared quite a few blogs with text and images to check! I will be happy to approve this PR once these comments are resolved, and we can get this rolling 🚀

[kreczko]

Thanks for the feedback.

• utm_source added in FAST-HEP/hugo-atom-layout@4bd91da
• blockquote added in FAST-HEP/hugo-atom-layout@e645ff1

[agriyakhetarpal]

Awesome, thanks a lot for your work @kreczko!

@stefanv, could you please skim through the discussion in #714 and here, and if you're happy with this, can we land it and unblock new Hugo releases? I would have merged this, but I thought I should ask you too – in my view, https://github.com/FAST-HEP/hugo-atom-layout here is functionally the same as https://github.com/kaushalmodi/hugo-atom-feed. Even with the AI assistance that @kreczko sought to complete this work, the much-reduced scope of the Fast-HEP implementation versus the latter (as I found when comparing the depth of list.atom.xml for both) makes me personally have no qualms in stating that this is fine enough in terms of licensing and should not incur a violation of the GPL. There simply isn't a significant difference that can be made across implementations when it comes to RFC 4287.

This layout is also beneficial in the sense that it's more tailored to our use case, and considering that @kreczko and Fast-HEP are aligned towards using our theme for their project's website—and also open to contributing towards other parts of our project, as was the case with adding Pixi on earlier iterations of this PR—it alleviates my concerns about maintainability for the medium term (and we've never needed a lot of maintenance for the Atom side of things anyway – it is only very recently, when it started breaking).