jk_na/themes/hugo-atom-feed/README.org

*This is not a standalone theme. This is a Hugo theme component.*

To enable ATOM feeds for your site:

1. Clone this repo to ~<your-site-dir>/themes/hugo-atom-feed~ directory.
2. Add these your site's ~config.toml~:
   - Add "hugo-atom-feed" as the *left-most element* of the ~theme~
     list variable. For example:
     #+begin_src toml
     theme = ["hugo-atom-feed", "my-theme"]
     #+end_src
   - Add "ATOM" to all the Page Kinds for which you want to create
     ATOM feeds:
     #+begin_src toml
     [outputs]
       # <domain>/atom.xml
       home = ["HTML", "RSS", "ATOM"]     # default = ["HTML", "RSS"]
       # <domain>/posts/atom.xml
       section = ["HTML", "RSS", "ATOM"]  # default = ["HTML", "RSS"]
       # <domain>/tags/mytag/atom.xml, <domain>/categories/mycat/atom.xml
       taxonomy = ["HTML", "RSS", "ATOM"] # default = ["HTML", "RSS"]
     #+end_src

* Selectively excluding pages from the feed
For the pages that you would like to exclude from the feed, set the
~disable_feed~ parameter in its front-matter to ~true~.

#+begin_src toml
disable_feed = true
#+end_src

* Pay attention to web server MIME type
To fully comply with web standards, make sure your web server will
send the correct [[https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Type][/Content-Type/ HTTP response header]] for the feed file
name ~atom.xml~. The correct response header looks like this:

#+begin_example
Content-Type: application/atom+xml; charset=UTF-8
#+end_example

Note that even though the feed file extension is ~.xml~, the [[https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types][MIME type]]
here is slightly adjusted from ~application/xml~ to
~application/atom+xml~.

While this might not be important for many feed readers, it could
still be a source of error.  So it is a good idea to play safe.  How
you could achieve this depends on the type of web server software you
are running your website on.
** Specifying the correct ~Content-Type~ for Netlify
You can specify the /Content-Type/ of ~atom.*~ and ~*.atom~ files to
be ~application/atom+xml; charset=UTF-8~ using the below in your site's
~netlify.toml~:
#+begin_src toml
[[headers]]
  for = "atom.*"
  [headers.values]
    Content-Type = "application/atom+xml; charset=UTF-8"
[[headers]]
  for = "*.atom"
  [headers.values]
    Content-Type = "application/atom+xml; charset=UTF-8"
#+end_src
*** References
- [[https://www.netlify.com/docs/headers-and-basic-auth/]]
- [[https://www.netlify.com/blog/2017/10/17/introducing-structured-redirects-and-headers/]]
** Note about Google Chrome
Note that Google Chrome currently still [[https://bugs.chromium.org/p/chromium/issues/detail?id=84][features a bug]] for such MIME
types so that automatic XML rendering is not performed.  You may
decide what is more important for you: watching the rendered source in
your browser once in a while, or maximum feed reader compatibility 😉.