~brettgilio/org-webring

Static RSS/ATOM webring generator for Org-mode

0b9eb73 Reverse ERR MSG and URL in ERROR-CONDITION

13 hours ago

60eecf2 Remove TODO for MELPA

a day ago

#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.

#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 is 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.

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.

  • Type: Integer
  • 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-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 that will be displayed when the post summary returns an empty string.

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

#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

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.>"

#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

Return a message to the echo area displaying the current version of org-webring.

#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.

#Roadmap

Here is a list of proposed implementations in a non-specific order to guide our release cycle.

#Version 2.0

  1. DONE Support ATOM Feeds.

  2. DONE Implement a more consistent, and strict sanitizer.

  3. TODO Implement a custom feed fetcher, possibly with async.

  4. DONE Support and test lexical bindings.

  5. TODO Add post pinning support.

  6. DONE Implement syndicate list. (Renamed “Planet”)

  7. TODO Validation for Planet HTML

  8. TODO Implement support for RDF parsing

#Other Proposed Changes

  1. TODO TEXINFO Documentation.

  2. TODO Fetch arXiv documents

  3. TODO Future-proofing

#Resources

Source code at ~brettgilio/org-webring.

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

Issue tracker here: ~brettgilio/org-webring.

#License

Org-webring is licensed under the GNU General Public License, version 3. See the LICENSE file for the details.