fork/rsspls

git clone https://git.julia.blue/fork/rsspls

Wesley MooreAdd tests for processing local filesf6b8b93

0.10.0
30.6 KiB545 linesraw
1<!DOCTYPE html>
2<html lang="en">
3
4<head>
5    <meta charset="UTF-8">
6    <title>Documentation - RSS Please </title>
7    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
8    
9<link rel="icon" href="https://rsspls.7bit.org/feed-icon.svg">
10
11    <style>
12    :root {
13        /* Primary theme color */
14        --primary-color: #50BDB6;
15        /* Primary theme text color */
16        --primary-text-color: #0C4A4C;
17        --primary-text-color-over: #282B2B;
18        /* Primary theme link color */
19        --primary-link-color: #1F827B;
20        /* Secondary color: the background body color */
21        --secondary-color: #fff;
22        --secondary-text-color: #1F827B;
23        /* Highlight text color of table of content */
24        --toc-highlight-text-color: #282B2B;
25        --toc-background-color: #fff;
26        --code-color: initial;
27        --code-background-color: initial;
28        --shadow-color: #ddd;
29        /* Font used for headers (h1 & h2) */
30        --header-font-family: Firava, "Fira Sans", sans-serif;
31        /* Font used for text */
32        --text-font-family: Firava, "Fira Sans", sans-serif;
33        --button-color: #000;
34        --button-hover-color: #282B2B;
35        --button-text-color: #fff;
36        --content-text-color: #282B2B;
37        --content-heading-text-color: #282B2B;
38        --footer-background-color: #FACD69;
39        --footer-text-color: #282B2B;
40    }
41</style>
42
43    
44
45    <link rel="stylesheet" href="/normalize.css">
46    <link rel="stylesheet" href="https://rsspls.7bit.org/juice.css">
47    
48    <link rel="stylesheet" href="https://rsspls.7bit.org/home.css?v=2">
49    <link rel="stylesheet" href="https://rsspls.7bit.org/syntax.css">
50    <link rel="alternate" type="application/rss+xml" title="RSS" href="https://rsspls.7bit.org/index.xml">
51
52    
53    <meta property="og:url" content="https:&#x2F;&#x2F;rsspls.7bit.org&#x2F;documentation&#x2F;" />
54    <meta property="og:title" content="Documentation - RSS Please" />
55    <meta property="og:description" content="" />
56    <meta property="og:type" content="article" />
57    <meta property="og:locale" content="en_AU" />
58    <meta name="twitter:card" content="summary" />
59    <meta name="twitter:creator" content="@wezm" />
60
61</head>
62
63<body>
64    
65<header class="box-shadow">
66    
67
68<a href="https://rsspls.7bit.org/">
69    <div class="logo">
70        <img src="https://rsspls.7bit.org/feed-icon.svg" alt="logo">
71        RSS Please
72    </div>
73</a>
74
75<nav>
76    
77    
78    
79    <a class="nav-item subtitle-text" href="https://rsspls.7bit.org/install/">Install</a>
80    
81    
82    
83    
84    <a class="nav-item subtitle-text" href="https://rsspls.7bit.org/documentation/">Documentation</a>
85    
86    
87    
88        
89        <a class="nav-item subtitle-text" href="/news/">News</a>
90        
91        <a class="nav-item subtitle-text" href="https://github.com/sponsors/wezm">Sponsor</a>
92        
93        <a class="nav-item subtitle-text" href="https://github.com/wezm/rsspls">GitHub</a>
94        
95    
96</nav>
97
98</header>
99
100
101    <main>
102        
103        
104        
105        
106        
107        <div class="toc">
108            <div class="toc-sticky">
109                
110                <div class="toc-item">
111                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#how-it-works">How it Works</a>
112                </div>
113                
114                
115                <div class="toc-item">
116                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#supported-platforms">Supported Platforms</a>
117                </div>
118                
119                
120                <div class="toc-item">
121                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#usage">Usage</a>
122                </div>
123                
124                
125                <div class="toc-item">
126                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#configuration">Configuration</a>
127                </div>
128                
129                
130                <div class="toc-item-child">
131                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#annotated-sample-configuration"><small>- Annotated Sample Configuration</small></a>
132                </div>
133                
134                <div class="toc-item-child">
135                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#output"><small>- output</small></a>
136                </div>
137                
138                <div class="toc-item-child">
139                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#proxy"><small>- proxy</small></a>
140                </div>
141                
142                <div class="toc-item-child">
143                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#feed-title"><small>- feed.title</small></a>
144                </div>
145                
146                <div class="toc-item-child">
147                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#feed-filename"><small>- feed.filename</small></a>
148                </div>
149                
150                <div class="toc-item-child">
151                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#feed-config-url"><small>- feed.config.url</small></a>
152                </div>
153                
154                <div class="toc-item-child">
155                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#feed-config-item"><small>- feed.config.item</small></a>
156                </div>
157                
158                <div class="toc-item-child">
159                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#feed-config-heading"><small>- feed.config.heading</small></a>
160                </div>
161                
162                <div class="toc-item-child">
163                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#feed-config-link"><small>- feed.config.link</small></a>
164                </div>
165                
166                <div class="toc-item-child">
167                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#feed-config-summary"><small>- feed.config.summary</small></a>
168                </div>
169                
170                <div class="toc-item-child">
171                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#feed-config-date"><small>- feed.config.date</small></a>
172                </div>
173                
174                <div class="toc-item-child">
175                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#feed-config-media"><small>- feed.config.media</small></a>
176                </div>
177                
178                
179                
180                <div class="toc-item">
181                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#hosting-updating-and-subscribing">Hosting, Updating, and Subscribing</a>
182                </div>
183                
184                
185                <div class="toc-item">
186                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#logging">Logging</a>
187                </div>
188                
189                
190                <div class="toc-item">
191                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#caveats-error-handling">Caveats &amp; Error Handling</a>
192                </div>
193                
194                
195                <div class="toc-item">
196                    <a class="subtext" href="https://rsspls.7bit.org/documentation/#caching">Caching</a>
197                </div>
198                
199                
200            </div>
201        </div>
202        
203        
204
205        <div class="content text">
206            
207
208<h1 class="heading-text">Documentation</h1>
209
210
211
212<h2 id="how-it-works">How it Works</h2>
213<p><code>rsspls</code> fetches each page specified by the configuration and extracts elements
214from the page using <a href="https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors">CSS selectors</a>. For example elements are matched
215to determine the title and content of the feed entry. The generated feeds are
216written to an output directory. HTTP caching is used to only update the feed
217when the source page changes.</p>
218<h2 id="supported-platforms">Supported Platforms</h2>
219<p><code>rsspls</code> should work on all <a href="https://doc.rust-lang.org/stable/rustc/platform-support.html">platforms supported by the Rust compiler</a>
220including Linux, macOS, Windows, and BSD. Pre-compiled binaries are available
221for common platforms. See <a href="https://rsspls.7bit.org/install/">the install page</a> for details.</p>
222<h2 id="usage">Usage</h2>
223<pre style="background-color:#fafafa;color:#383a42;"><code><span>rsspls [OPTIONS] -o OUTPUT_DIR
224</span><span>
225</span><span>OPTIONS:
226</span><span>    -h, --help
227</span><span>            Prints this help information
228</span><span>
229</span><span>    -c, --config
230</span><span>            Specify the path to the configuration file.
231</span><span>            $XDG_CONFIG_HOME/rsspls/feeds.toml is used if not supplied.
232</span><span>
233</span><span>    -o, --output
234</span><span>            Directory to write generated feeds to.
235</span><span>
236</span><span>    -V, --version
237</span><span>            Prints version information
238</span><span>
239</span><span>FILES:
240</span><span>     ~/$XDG_CONFIG_HOME/rsspls/feeds.toml    rsspls configuration file.
241</span><span>     ~/$XDG_CONFIG_HOME/rsspls               Configuration directory.
242</span><span>     ~/XDG_CACHE_HOME/rsspls                 Cache directory.
243</span><span>
244</span><span>     Note: XDG_CONFIG_HOME defaults to ~/.config, XDG_CACHE_HOME
245</span><span>     defaults to ~/.cache.
246</span></code></pre>
247<h2 id="configuration">Configuration</h2>
248<p>Unless specified via the <code>--config</code> command line option <code>rsspls</code> reads its
249configuration from one of the following paths:</p>
250<ul>
251<li>UNIX-like systems:
252<ul>
253<li><code>$XDG_CONFIG_HOME/rsspls/feeds.toml</code></li>
254<li><code>~/.config/rsspls/feeds.toml</code> if <code>XDG_CONFIG_HOME</code> is unset.</li>
255</ul>
256</li>
257<li>Windows:
258<ul>
259<li><code>C:\Users\You\AppData\Roaming\rsspls\feeds.toml</code></li>
260</ul>
261</li>
262</ul>
263<p>The configuration file is in <a href="https://toml.io/">TOML</a> format.</p>
264<p>The parts of the page to extract for the feed are specified using <a href="https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors">CSS
265selectors</a>.</p>
266<h3 id="annotated-sample-configuration">Annotated Sample Configuration</h3>
267<p>The sample file below demonstrates all the parts of the configuration.</p>
268<pre data-lang="toml" style="background-color:#fafafa;color:#383a42;" class="language-toml "><code class="language-toml" data-lang="toml"><span style="color:#a0a1a7;"># The configuration must start with the [rsspls] section
269</span><span>[rsspls]
270</span><span style="color:#a0a1a7;"># Optional output directory to write the feeds to. If not specified it must be supplied via
271</span><span style="color:#a0a1a7;"># the --output command line option.
272</span><span style="color:#e45649;">output </span><span>= </span><span style="color:#50a14f;">&quot;/tmp&quot;
273</span><span style="color:#a0a1a7;"># Optional proxy address. If specified, all requests will be routed through it.
274</span><span style="color:#a0a1a7;"># The address needs to be in the format: protocol://ip_address:port
275</span><span style="color:#a0a1a7;"># The supported protocols are: http, https, socks and socks5h.
276</span><span style="color:#a0a1a7;"># It can also be specified as environment variable `http_proxy` or `HTTPS_PROXY`.
277</span><span style="color:#a0a1a7;"># The config file takes precedence, then the env vars in the above order.
278</span><span style="color:#a0a1a7;"># proxy = socks5://10.64.0.1:1080
279</span><span>
280</span><span style="color:#a0a1a7;"># Next is the array of feeds, each one starts with [[feed]]
281</span><span>[[feed]]
282</span><span style="color:#a0a1a7;"># The title of the channel in the feed
283</span><span style="color:#e45649;">title </span><span>= </span><span style="color:#50a14f;">&quot;My Great RSS Feed&quot;
284</span><span>
285</span><span style="color:#a0a1a7;"># The output filename without the output directory to write this feed to.
286</span><span style="color:#a0a1a7;"># Note: this is a filename only, not a path. It should not contain slashes.
287</span><span style="color:#e45649;">filename </span><span>= </span><span style="color:#50a14f;">&quot;wezm.rss&quot;
288</span><span>
289</span><span style="color:#a0a1a7;"># Optional User-Agent header to be set for the HTTP request.
290</span><span style="color:#a0a1a7;"># user_agent = &quot;Mozilla/5.0&quot;
291</span><span>
292</span><span style="color:#a0a1a7;"># The configuration for the feed
293</span><span>[feed.config]
294</span><span style="color:#a0a1a7;"># The URL of the web page to generate the feed from.
295</span><span style="color:#e45649;">url </span><span>= </span><span style="color:#50a14f;">&quot;https://www.wezm.net/&quot;
296</span><span>
297</span><span style="color:#a0a1a7;"># A CSS selector to select elements on the page that represent items in the feed.
298</span><span style="color:#e45649;">item </span><span>= </span><span style="color:#50a14f;">&quot;article&quot;
299</span><span>
300</span><span style="color:#a0a1a7;"># A CSS selector relative to `item` to an element that will supply the title for the item.
301</span><span style="color:#e45649;">heading </span><span>= </span><span style="color:#50a14f;">&quot;h3&quot;
302</span><span>
303</span><span style="color:#a0a1a7;"># A CSS selector relative to `item` to an element that will supply the link for the item.
304</span><span style="color:#a0a1a7;"># Note: This element must have a `href` attribute.
305</span><span style="color:#a0a1a7;"># Note: If not supplied rsspls will attempt to use the heading selector for link for backwards
306</span><span style="color:#a0a1a7;">#       compatibility with earlier versions. A message will be emitted in this case.
307</span><span style="color:#e45649;">link </span><span>= </span><span style="color:#50a14f;">&quot;h3 a&quot;
308</span><span>
309</span><span style="color:#a0a1a7;"># Optional CSS selector relative to `item` that will supply the content of the RSS item.
310</span><span style="color:#e45649;">summary </span><span>= </span><span style="color:#50a14f;">&quot;.post-body&quot;
311</span><span>
312</span><span style="color:#a0a1a7;"># Optional CSS selector relative to `item` that supplies media content (audio, video, image)
313</span><span style="color:#a0a1a7;"># to be added as an RSS enclosure.
314</span><span style="color:#a0a1a7;"># Note: The media URL must be given by the `src` or `href` attribute of the selected element.
315</span><span style="color:#a0a1a7;"># Note: Currently if the item does not match the media selector then it will be skipped.
316</span><span style="color:#a0a1a7;"># media = &quot;figure img&quot;
317</span><span>
318</span><span style="color:#a0a1a7;"># Optional CSS selector relative to `item` that supples the publication date of the RSS item.
319</span><span style="color:#e45649;">date </span><span>= </span><span style="color:#50a14f;">&quot;time&quot;
320</span><span>
321</span><span style="color:#a0a1a7;"># Alternatively for more control `date` can be specified as a table:
322</span><span style="color:#a0a1a7;"># [feed.config.date]
323</span><span style="color:#a0a1a7;"># selector = &quot;time&quot;
324</span><span style="color:#a0a1a7;"># # Optional type of value being parsed.
325</span><span style="color:#a0a1a7;"># # Defaults to DateTime, can also be Date if you&#39;re parsing a value without a time.
326</span><span style="color:#a0a1a7;"># type = &quot;Date&quot; 
327</span><span style="color:#a0a1a7;"># # format of the date to parse. See the following for the syntax
328</span><span style="color:#a0a1a7;"># # https://time-rs.github.io/book/api/format-description.html
329</span><span style="color:#a0a1a7;"># format = &quot;[day padding:none]/[month padding:none]/[year]&quot; # will parse 1/2/1934 style dates
330</span><span>
331</span><span style="color:#a0a1a7;"># A second example feed
332</span><span>[[feed]]
333</span><span style="color:#e45649;">title </span><span>= </span><span style="color:#50a14f;">&quot;Example Site&quot;
334</span><span style="color:#e45649;">filename </span><span>= </span><span style="color:#50a14f;">&quot;example.rss&quot;
335</span><span>
336</span><span>[feed.config]
337</span><span style="color:#e45649;">url </span><span>= </span><span style="color:#50a14f;">&quot;https://example.com/&quot;
338</span><span style="color:#e45649;">item </span><span>= </span><span style="color:#50a14f;">&quot;div&quot;
339</span><span style="color:#e45649;">heading </span><span>= </span><span style="color:#50a14f;">&quot;a&quot;
340</span></code></pre>
341<p>The first example above (for my blog WezM.net) matches HTML that looks like this:</p>
342<pre data-lang="html" style="background-color:#fafafa;color:#383a42;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#e45649;">section </span><span style="color:#c18401;">class</span><span>=</span><span style="color:#50a14f;">&quot;posts-section&quot;</span><span>&gt;
343</span><span>  &lt;</span><span style="color:#e45649;">h2</span><span>&gt;Recent Posts&lt;/</span><span style="color:#e45649;">h2</span><span>&gt;
344</span><span>
345</span><span>  &lt;</span><span style="color:#e45649;">article </span><span style="color:#c18401;">id</span><span>=</span><span style="color:#50a14f;">&quot;garage-door-monitor&quot;</span><span>&gt;
346</span><span>    &lt;</span><span style="color:#e45649;">h3</span><span>&gt;&lt;</span><span style="color:#e45649;">a </span><span style="color:#c18401;">href</span><span>=</span><span style="color:#50a14f;">&quot;https://www.wezm.net/v2/posts/2022/garage-door-monitor/&quot;</span><span>&gt;Monitoring My Garage Door With a Raspberry Pi, Rust, and a 13Mb Linux System&lt;/</span><span style="color:#e45649;">a</span><span>&gt;&lt;/</span><span style="color:#e45649;">h3</span><span>&gt;
347</span><span>    &lt;</span><span style="color:#e45649;">div </span><span style="color:#c18401;">class</span><span>=</span><span style="color:#50a14f;">&quot;post-metadata&quot;</span><span>&gt;
348</span><span>      &lt;</span><span style="color:#e45649;">div </span><span style="color:#c18401;">class</span><span>=</span><span style="color:#50a14f;">&quot;date-published&quot;</span><span>&gt;
349</span><span>        &lt;</span><span style="color:#e45649;">time </span><span style="color:#c18401;">datetime</span><span>=</span><span style="color:#50a14f;">&quot;2022-04-20T06:38:27+10:00&quot;</span><span>&gt;20 April 2022&lt;/</span><span style="color:#e45649;">time</span><span>&gt;
350</span><span>      &lt;/</span><span style="color:#e45649;">div</span><span>&gt;
351</span><span>    &lt;/</span><span style="color:#e45649;">div</span><span>&gt;
352</span><span>
353</span><span>    &lt;</span><span style="color:#e45649;">div </span><span style="color:#c18401;">class</span><span>=</span><span style="color:#50a14f;">&quot;post-body&quot;</span><span>&gt;
354</span><span>      &lt;</span><span style="color:#e45649;">p</span><span>&gt;I’ve accidentally left our garage door open a few times. To combat this I built
355</span><span>        a monitor that sends an alert via Mattermost when the door has been left open
356</span><span>        for more than 5 minutes. This turned out to be a super fun project. I used
357</span><span>        parts on hand as much as possible, implemented the monitoring application in
358</span><span>        Rust, and then built a stripped down Linux image to run it.
359</span><span>      &lt;/</span><span style="color:#e45649;">p</span><span>&gt;
360</span><span>    &lt;/</span><span style="color:#e45649;">div</span><span>&gt;
361</span><span>
362</span><span>    &lt;</span><span style="color:#e45649;">a </span><span style="color:#c18401;">href</span><span>=</span><span style="color:#50a14f;">&quot;https://www.wezm.net/v2/posts/2022/garage-door-monitor/&quot;</span><span>&gt;Continue Reading →&lt;/</span><span style="color:#e45649;">a</span><span>&gt;
363</span><span>  &lt;/</span><span style="color:#e45649;">article</span><span>&gt;
364</span><span>
365</span><span>  &lt;</span><span style="color:#e45649;">article </span><span style="color:#c18401;">id</span><span>=</span><span style="color:#50a14f;">&quot;monospace-kobo-ereader&quot;</span><span>&gt;
366</span><span>    </span><span style="color:#a0a1a7;">&lt;!-- another article --&gt;
367</span><span>  &lt;/</span><span style="color:#e45649;">article</span><span>&gt;
368</span><span>
369</span><span>  </span><span style="color:#a0a1a7;">&lt;!-- more articles --&gt;
370</span><span>
371</span><span>  &lt;</span><span style="color:#e45649;">a </span><span style="color:#c18401;">href</span><span>=</span><span style="color:#50a14f;">&quot;https://www.wezm.net/v2/posts/&quot;</span><span>&gt;View more posts →&lt;/</span><span style="color:#e45649;">a</span><span>&gt;
372</span><span>&lt;/</span><span style="color:#e45649;">section</span><span>&gt;
373</span></code></pre>
374<h3 id="output">output</h3>
375<p>Optional output directory to write the feeds to. If not specified it must be
376supplied via the <code>--output</code> command line option. Directory will be created if
377it does not exist.</p>
378<p>Tilde expansion is performed on the path in the config file. This allows you to
379refer to the home directory of the user running <code>rsspls</code>. For example,
380<code>~/Documents/rsspls</code> could be used to place the output in your <code>Documents</code>
381folder.</p>
382<h3 id="proxy">proxy</h3>
383<p>Optional proxy address. If specified, all requests will be routed through it.
384The address needs to be in the format: <code>protocol://ip_address:port</code>
385The supported protocols are: http, https, socks and socks5h.</p>
386<p>The proxy for http and https requests can also be specified with the
387environment variables <code>http_proxy</code> and <code>HTTPS_PROXY</code> respectively.
388The config file takes precedence over environment variables.</p>
389<h3 id="feed-title">feed.title</h3>
390<p>The title of the channel in the generated feed.</p>
391<h3 id="feed-filename">feed.filename</h3>
392<p>The output filename to write this feed to. Note: this is a filename only, not a
393path. It should not contain slashes. It will be written to the <a href="https://rsspls.7bit.org/documentation/#output">output</a>
394directory.</p>
395<h3 id="feed-config-url">feed.config.url</h3>
396<p>The URL of the web page to generate the feed from. The page at this address
397will be fetched processed to turn it into a feed.</p>
398<h3 id="feed-config-item">feed.config.item</h3>
399<p>A CSS selector to select elements on the page that represent items in the feed.
400The other CSS selectors match elements inside the elements that this selector
401matches.</p>
402<h3 id="feed-config-heading">feed.config.heading</h3>
403<p>A CSS selector relative to <code>item</code> to an element that will supply the title for
404the item in the feed.</p>
405<h3 id="feed-config-link">feed.config.link</h3>
406<p>CSS selector relative to <code>item</code> to an element that will supply the
407link for the item in the feed.</p>
408<p><strong>Note:</strong> This element must have a <code>href</code> attribute.</p>
409<p><strong>Note:</strong> If not supplied <code>rsspls</code> will attempt to use the
410<code>feed.config.heading</code> selector as the <code>link</code> element for backwards compatibility
411with earlier versions. A warning message will be emitted in this case. It is
412recommended to specify the <code>link</code> selector explicitly.</p>
413<h3 id="feed-config-summary">feed.config.summary</h3>
414<p>Optional CSS selector relative to <code>item</code> that will supply the content of the
415RSS item. This value may be a single CSS selector, or an array of CSS
416selectors.</p>
417<p>The CSS selectors may also include a comma separated list of elements to match.
418For example: <code>summary = "p, blockquote"</code> will match <code>p</code> or <code>blockquote</code>
419elements, adding them to the RSS feed in the order then are encountered in the
420HTML document.</p>
421<p>The array form of <code>summary</code> allows the order of the matched elements to be
422controlled, enabling elements to be added to the feed in a different order to
423the source HTML document. For example, <code>summary = ["p", "blockquote"]</code> causes
424<code>rsspls</code> to make a pass over the source HTML document, adding <code>p</code> elements to
425the feed, followed by a pass adding <code>blockquote</code> elements to the feed.</p>
426<h3 id="feed-config-date">feed.config.date</h3>
427<p>The optional <code>date</code> key in the configuration can be a string  or a table. If it’s a
428string then it’s used as CSS selector relative to <code>item</code> to find the element
429containing the date and <code>rsspls</code> will attempt to automatically parse the value.</p>
430<p>If automatic parsing fails you can manually specify the format using the table
431form of <code>date</code>, which looks like this:</p>
432<pre data-lang="toml" style="background-color:#fafafa;color:#383a42;" class="language-toml "><code class="language-toml" data-lang="toml"><span>[feed.config.date]
433</span><span style="color:#e45649;">selector </span><span>= </span><span style="color:#50a14f;">&quot;time&quot; </span><span style="color:#a0a1a7;"># required
434</span><span style="color:#e45649;">type </span><span>= </span><span style="color:#50a14f;">&quot;Date&quot;
435</span><span style="color:#e45649;">format </span><span>= </span><span style="color:#50a14f;">&quot;[day padding:none]/[month padding:none]/[year]&quot; </span><span style="color:#a0a1a7;"># will parse 1/2/1934 style dates
436</span></code></pre>
437<p>If the element matched by the <code>date</code> selector is a <code>&lt;time&gt;</code> element then
438<code>rsspls</code> will first try to parse the value in the <code>datetime</code> attribute if
439present. If the attribute is missing or the element is not a <code>time</code> element
440then <code>rsspls</code> will use the supplied format or attempt automatic parsing of the
441text content of the element.</p>
442<h4 id="feed-config-date-selector">feed.config.date.selector</h4>
443<p>CSS selector relative to <code>item</code> that supples the publication date of
444the RSS item.</p>
445<h4 id="feed-config-date-type">feed.config.date.type</h4>
446<p>Optional type of value being parsed. Either <code>Date</code> or <code>DateTime</code>.</p>
447<p><code>type</code> is <code>Date</code> when you want to parse just a date. Use <code>DateTime</code> if you’re
448parsing a date and time with the format. Defaults to <code>DateTime</code>.</p>
449<h4 id="feed-config-date-format">feed.config.date.format</h4>
450<p>Format description using the syntax described on this page:
451<a href="https://time-rs.github.io/book/api/format-description.html">https://time-rs.github.io/book/api/format-description.html</a>
452of how to parse the date.</p>
453<h3 id="feed-config-media">feed.config.media</h3>
454<p>Optional CSS selector relative to <code>item</code> that supplies media content (audio,
455video, image) to be added as an RSS enclosure.</p>
456<p><strong>Note:</strong> The media URL must be given by the <code>src</code> or <code>href</code> attribute of the
457selected element.</p>
458<p><strong>Note:</strong> Currently if the item does not match the media selector then it will
459be skipped.</p>
460<h2 id="hosting-updating-and-subscribing">Hosting, Updating, and Subscribing</h2>
461<p>In order to have the feeds update you will need to arrange for
462<code>rsspls</code> to be run periodically. You might do this with <a href="https://en.wikipedia.org/wiki/Cron">cron</a>, <a href="https://wiki.archlinux.org/title/Systemd/Timers">systemd
463timers</a>, or the Windows equivalent.</p>
464<p>To subscribe to feeds you can run <code>rsspls</code> locally and use a feed reader that
465supports local file feeds. Or, more likely it is expected that <code>rsspls</code> will be
466run on a web server that is serving the directory the feeds are written to.</p>
467<h2 id="logging">Logging</h2>
468<p><code>rsspls</code> logs messages to <code>stderr</code>. Logging can be controlled by the
469<code>RSSPLS_LOG</code> environment variable. Log level and target module can controlled
470according to the <a href="https://docs.rs/env_logger/latest/env_logger/#enabling-logging">env_logger documentation</a>. For example, to enable
471debug logging for <code>rsspls</code> you would use:</p>
472<p><code>RSSPLS_LOG=rsspls=debug</code></p>
473<p>The supported log levels are:</p>
474<ul>
475<li><code>error</code></li>
476<li><code>warn</code></li>
477<li><code>info</code></li>
478<li><code>debug</code></li>
479<li><code>trace</code></li>
480<li><code>off</code> (disable logging)</li>
481</ul>
482<p>The default log level is <code>info</code>.</p>
483<h2 id="caveats-error-handling">Caveats &amp; Error Handling</h2>
484<p><code>rsspls</code> just fetches and parses the HTML of the web page you specify. It does
485not run JavaScript. If the website is entirely generated by JavaScript (such as
486Twitter) then <code>rsspls</code> will not work.</p>
487<p>If errors are encountered processing the page due to invalid selectors, or
488missing elements an error message will be logged. If the error is non-recoverable
489<code>rsspls</code> will exit with a non-zero exit status.</p>
490<p>If an error is encountered processing an item for the feed a warning will by
491logged and processing will continue with the next item. <code>rsspls</code> will still
492exit with success (0) in this case.</p>
493<h2 id="caching">Caching</h2>
494<p>When websites respond with cache headers <code>rsspls</code> will make a conditional
495request on subsequent runs and will not regenerate the feed if the server
496responds with 304 Not Modified. Cache data is stored in
497<code>$XDG_CACHE_HOME/rsspls</code>, which defaults to <code>~/.cache/rsspls</code> on UNIX-like
498systems or <code>C:\Users\You\AppData\Local\rsspls</code> on Windows.</p>
499
500
501        </div>
502
503        
504        
505    </main>
506
507    
508    <footer>
509        <small class="subtext">
510            Copyright ©  2024
511            <a href="https:&#x2F;&#x2F;www.wezm.net&#x2F;">Wesley Moore</a>
512            ⬩ <a href="https://forge.wezm.net/wezm/rsspls.7bit.org">Website Source</a>
513            ⬩ <a href="https://github.com/sponsors/wezm">Sponsor on GitHub</a>
514        </small>
515    </footer>
516    <script src="https://rsspls.7bit.org/home.js" type="text/javascript"></script>
517    <script data-goatcounter="https://rsspls.goatcounter.com/count" async src="//gc.zgo.at/count.js"></script>
518
519</body>
520<script>
521    const scrollHandler = entries => {
522        // Find the first entry which intersecting and ratio > 0.9 to highlight.
523        let entry = entries.find(entry => {
524            return entry.isIntersecting && entry.intersectionRatio > 0.9;
525        });
526        if (!entry) return;
527
528        document.querySelectorAll(".toc a").forEach((item) => {
529            item.classList.remove("active");
530        });
531
532        // let url = new URL(`#${entry.target.id}`);
533        let link = document.querySelector(`.toc a[href$="${decodeURIComponent(`#${entry.target.id}`)}"]`)
534        if (link) {
535            link.classList.add("active");
536            link.scrollIntoView({ behavior: "auto", block: "nearest" });
537        }
538    };
539    // Set -100px root margin to improve highlight experience.
540    const observer = new IntersectionObserver(scrollHandler, { threshold: 1 });
541    let items = document.querySelectorAll('h1,h2,h3,h4,h5,h6');
542    items.forEach(item => observer.observe(item));
543</script>
544
545</html>