~brettgilio/org-webring

Static RSS/ATOM webring generator for Org-mode
Mention EmacsConf in README
v -> 1.9.8-rc4

clone

read-only
https://git.sr.ht/~brettgilio/org-webring
read/write
git@git.sr.ht:~brettgilio/org-webring

You can also use your local clone with git send-email.

#org-webring

Static RSS/ATOM webring generator for org-mode

org-webring is an alternative implementation of a feed-based webring, taking inspiration from openring by Drew DeVault. Intended to integrate with Org-based websites and blogs (either directly, or indirectly, as in ox-hugo), it will fetch a given list of web-feed files and correctly parse and format the elements to be displayed for sharing.

This project was featured at EmacsConf 2020! You may watch the recorded presentation at https://brettgilio.com/posts/2020-10-18-emacsconf-2020.html

#Usage & Documentation

The CSS file org-webring.css needs to be loaded by your website, and your browser must be able to render flex boxes. This file provides stylization support for both the webring and planet functionality.

The files ring.org and planet.org are templates. Copy one or both of them into a specified directory from where your website is generated. Add all relevant web-feed URLs to org-webring-urls for fetching, and adjust variables as desired.

To include the results of ring.org into an Org file export of your choosing, simply add: “#+INCLUDE: ./ring.org”, taking care to modify the path appropriately. When you regenerate your Org-based (or Hugo, using ox-hugo) website, the function org-webring-generate-webring will be evaluated and the result will be displayed.

The file reply.org is a mock demonstration, utilizing post-pinning, to emulate a scenario where you would emphasize another blogger’s post and supplement it with a response of your own.

Additionally, if you are using the planet.org file, simply have the org-publish functionality of your choosing convert the file to HTML and serve it as you would any other page. This page is designated standalone, and probably should not be included in other Org-mode files. The result is produced by the org-webring-generate-planet function.

#Variable: org-webring-items-total

The total number of items displayed on the webring.

  • Type: Integer
  • Default Value: 3

#Variable: org-webring-items-per-source

The number of entries extracted from each source.

  • Type: Integer
  • Default Value: 1

#Variable: org-webring-header

The default text displayed in the header.

  • Type: String
  • Default Value: "Posts from other blogs I follow..."

#Variable: org-webring-display-header

Display the result of org-webring-header.

When set to non-NIL, the generator will display the value set for the header.

  • Type: Bool
  • Default Value: t

#Variable: org-webring-urls

The source URLs which are scraped for feeds.

  • Type: List-of-strings
  • Default Value: '()

#Variable: org-webring-summary-max-length

The maximum number of characters displayed in the summary field.

When NIL, no summary will be displayed.

  • Type: Sexp
  • Default Value: 512

#Variable: org-webring-timestamp-feed-format

The string format used for the publication dates of feed items.

This variable uses the same ’%’-sequences as format-time-string.

  • Type: String
  • Default Value: "%a, %d %b %Y"

#Variable: org-webring-timestamp-generate-format

The string format used for the generation of the webring or planet.

This variable uses the same ’%’-sequences as format-time-string.

  • Type: String
  • Default Value: "%a, %d %b %Y — %R"

#Variable: org-webring-display-generation-time

Display the result of org-webring-timestamp-generate-format.

When set to non-NIL, the generator will display the most recent generation time of org-webring.

  • Type: Bool
  • Default Value: t

#Variable: org-webring-display-attribution

Display the software attribution under the webring or planet.

When set to non-NIL, the generator will display the name of the program used to generate the webring or planet.

  • Type: Bool
  • Default Value: t

#Variable: org-webring-attribution-prefix

Text which will be displayed before the attribution.

  • Type: String
  • Default Value: Generated with

#Variable: org-webring-display-version

Display the current version of org-webring.

When set to non-NIL, the generator will display the current version of org-webring.

  • Type: Bool
  • Default Value: t

#Variable: org-webring-empty-summary

Text which will replace a summary with an empty string.

  • Type: String
  • Default Value: "No summary available."

#Variable: org-webring-pinned-posts

A list of feed item URLs that should be pinned.

This is not supported by planet.

  • Type: List-of-strings
  • Default Value: '()

#Variable: org-webring-pin-symbol

The symbol used to denote a pinned item.

  • Type: String
  • Default Value: 🖈

#Variable: org-webring-filtered-posts

A list of feed item URLs that should be filtered.

This is supported by both webring and planet.

  • Type: List-of-strings
  • Default Value: '()

#Variable: org-webring-planet-items-total

The total number of items generated by the planet.

  • Type: Integer
  • Default Value: 50

#Variable: org-webring-planet-display-description

Display the planet description.

When set to non-NIL, the generator will display the value set for the planet description.

  • Type: Bool
  • Default Value: t

#Variable: org-webring-planet-description

Text of the planet description.

  • Type: String
  • Default Value: "Default planet description."

#Variable: org-webring-planet-syndicate-length

The maximum length of all syndicate titles.

  • Type: String
  • Default Value: 25

#Variable: org-webring-override-time-locale

A convenient way to override the time encoding.

Your selected locale must be available on your machine, otherwise no effect will be witnessed.

  • Type: String
  • Default Value: env LANG

#Function: org-webring-generate-webring

Generate the entire webring and return it as HTML.

#Function: org-webring-generate-planet

Generate the entire planet with syndicates list and return it as HTML.

#Function: org-webring-version

Display the current version of org-webring in the echo area.

#Installation

  • You may checkout the git repository and add the directory to your GNU Emacs loadpath.

or

  • You may use GNU Guix, either from the repository or by using the script available in our /etc directory.

#Resources

Source code at ~brettgilio/org-webring.

Send patches and questions to ~brettgilio/org-webring@lists.sr.ht.

Issue tracker at ~brettgilio/org-webring.

#License

org-webring is licensed under the GNU General Public License, version 3 or any later version. See LICENSE for more details.

GPL