Configuration

The top-level configuration fields are:

Name Type Description Default
name string The name of your planet "Planet"
url string The base URL of your planet ""
owner string Your name ""
email string Your email ""
feed_id string Unique ID to use for the Atom feed ""
cache string The path, relative to mercury.toml of the feed cache "./cache"
generate_feed boolean Should a feed be generated? true
timeout duration How long to wait when fetching a feed -
theme string The path, relative to mercury.toml of the theme to use use default theme
output string The path, relative to mercury.toml to which mercury should write the files it generates "./output"
items number The number of items to include per page 10
max_pages number The maximum number of pages to generate 5

Note that the theme, output, and cache paths are assumed to be relative to the directory in which the configuration file is found, not the current working directory. You can specify absolute paths in these fields, however.

A duration is a sequence of numbers followed by a unit, with ‘s’ being ‘second’, ‘m’ being ‘minute’, and ‘h’ being ‘hour’. Thus ‘5m30s’ would mean five minutes and thirty seconds.

The feed ID is a URI identifying the feed. I would recommend using a tag URI, or a UUID URN. In the latter case, use a UUID generator such as uuidgen to generate a UUID, prefix it with urn:uuid:, and use the result as the value of feed_id.

Each feed is introduced with [[feed]], and can contain the following fields:

Name Type Description
name string The name of the feed
feed string The URL of the feed. Note that this must be the URL of the feed itself and no attempt is made to do feed discovery if all that’s provided is the site’s homepage

Filters

Filters are defined by adding configuration sections named [[feed.filter]] subsequent to the corresponding [[feed]] entry. Filters are defined using Expr, and your filter is expected to take a feed entry and return true if the entry should be kept, or false if not.

Name Description
when An expression to determine whether the entry should be kept or skipped. This should evaluate to a boolean. Defaults to true

The entry is available in your filter’s environment in the variable entry. See the gofeed documentation on the Item type for details on the fields you can expect.

Here’s an example filter that only allows through an entry if its Title field contains the letter ‘e’:

[[feed.filter]]
when = "entry.Title contains 'e'"

Converting an OPML file into Mercury configuration

The tools/opml2config.py script can be used to take multiple OPML files. Taking blogs.opml as an example:

<?xml version="1.0" encoding="utf-8"?>
<opml>
  <head>
    <title>My Subscriptions</title>
  </head>
  <body>
    <outline text="Feeds">
      <outline type="rss" text="Keith Gaughan" xmlUrl="https://keith.gaughan.ie/feeds/all.xml"/>
      <outline type="rss" text="Inklings" xmlUrl="https://talideon.com/inklings/feed"/>
    </outline>
  </body>
</opml>

You can process it into Mercury configuration like so:

$ tools/opml2config.py blogs.opml
[[feed]]
name = "Keith Gaughan"
feed = "https://keith.gaughan.ie/feeds/all.xml"

[[feed]]
name = "Inklings"
feed = "https://talideon.com/inklings/feed"