Skip to content

Visual selection

Choose New feed, enter a source URL, then Choose elements visually. A feed name and selectors are not needed to load the page. The workspace keeps CSS/XPath inputs on the left and the page preview on the right; on narrow screens they stack vertically.

  1. Click a headline or repeating article card. The picker suggests its containing repeated card. Use Selection level to choose a larger or smaller container, or Select parent to move up one level.
  2. Choose a suggestion and check its match count. Matching cards are outlined immediately; changing the suggestion updates those outlines. Use selection sets the repeated-item selector.
  3. Select Title from the field menu and click a title inside any matched card. Apply the suggestion. Repeat for Link, Description, Image, and Date as needed.
  4. Edit selectors directly in the left pane to tune their matches. Focus a field to highlight its first matching element across the repeated items. Changes update the same loaded snapshot without fetching the site again. Invalid expressions show an error alongside the preview.
  5. To refine a CSS recipe in XPath, choose Convert to XPath, then edit the generated expressions. This converts the whole recipe, including the feed editor's article body selector and cleanup rules. Visual picking also works while XPath is selected. For example, a title can use .//h2 and a link can use .//a/@href.
  6. Choose Done to return to the feed form with your edits intact, then Preview items. This fetches the source again and runs the standard extractor. Check the results before saving.

Each field under Fine-tune selectors has a ? button with its purpose, blank/default behavior, and examples for the selected CSS or XPath syntax. Open a tip by click, tap, or keyboard; dismiss it with its close button, the same ?, or Escape.

Selector type changes how the existing text is interpreted; it does not rewrite or clear expressions. CSS left in an XPath selector, such as .summary, is refused when you save, because the extractor would read it as the whole card. Convert to XPath explicitly translates common CSS forms used by the picker, including tags, classes, IDs, attribute tests, descendant/child paths, and supported positional or :has() suggestions. Element and attribute names are written in lowercase, as the parsed page holds them: CSS matches DIV and [DATA-ID] in any case and XPath does not. Unsupported CSS reports an error and preserves the original recipe. Conversion is available from CSS to XPath; other expressions can be edited manually.

The selector type also governs two settings that the feed editor holds and this workspace does not show: the article body selector of full article content and the cleanup rules. Convert to XPath converts them with the rest. The article selector becomes an absolute path, as the repeated-item selector does: .entry-content becomes //*[contains(concat(' ', normalize-space(@class), ' '), ' entry-content ')]. Each rule becomes a path relative to the block it cleans, which XPath rules must be, so aside.related becomes .//aside[contains(concat(' ', normalize-space(@class), ' '), ' related ')]. A CSS rule may name the block itself in its first part, as article .share does for an article body, and keeps that meaning: it becomes ./self::article//*[contains(concat(' ', normalize-space(@class), ' '), ' share ')] | .//article//*[contains(concat(' ', normalize-space(@class), ' '), ' share ')]. The recipe is converted as a whole or not at all: if either holds CSS with no supported XPath form, such as a :containsOwn() rule, the message names it (Article body selector or Cleanup rule 2) and every selector stays CSS, so rewrite or remove that part in the feed editor first. An article selector that lists alternatives, such as .entry-content, article, is one of these. Only its first match is published; CSS takes the first in the page, whichever alternative it is, while the XPath library takes the matches of the first alternative first, so a converted list could publish a different block. Write it by hand as one path, which keeps page order: //*[self::article or contains(concat(' ', normalize-space(@class), ' '), ' entry-content ')]. A list is converted in a cleanup rule, where every match is removed. The message after a conversion says when it included them. Article pages are not loaded here, so those two are not highlighted; Preview items shows the article body the converted recipe extracts. Saving an existing feed then discards its stored article bodies, as any change to the article selector does: later refreshes fetch them again for the stories still on the list page, and older stories keep their list-page description. Changing Selector type by hand converts neither of them.

Applying a different repeated-item suggestion clears field selectors so paths for a previous card do not carry over. Reapplying the same suggestion keeps them. Typing a repeated-item selector also keeps the fields, making it possible to tune the card expression without rebuilding the recipe. Field suggestions are relative to each card; . means the card itself. XPath fields must start with . and are evaluated against isolated copies of the cards. Link selection moves to a containing anchor and suggests href; dates suggest datetime when present. Image fields retain the extractor's lazy-image detection.

The match badge counts repeated items or cards with a matching field. Attribute and text-node XPath results highlight their containing element. An empty field selector has no explicit highlight, even when the extractor supplies a default such as automatic image detection.

Page version controls the snapshot: Static HTML uses the HTTP fetcher, with the feed's User-Agent and Accept-Language when it has them, and decodes the page's declared encoding as refreshes do (see fetch modes); Rendered with Chromium uses the managed browser pool and the recipe's readiness/wait settings; FlareSolverr (Cloudflare) uses the configured external service with its own timeout. Local Chromium wait settings do not apply to FlareSolverr. Unconfigured browser options are disabled. Use Reload page to fetch a fresh snapshot or load a different page version. Editing, applying selectors, or choosing Done uses the successfully loaded version as the feed's fetch mode. An existing Auto setting is preserved unless you explicitly change the page version. Auto recipes initially show static HTML because a new recipe has no extraction selectors to decide whether fallback is needed. See FlareSolverr setup for challenge support and network limits.

Manual selectors and images

Selectors can also be entered directly. For a typical article card:

Field CSS XPath Attribute
Repeated items article.card //article —
Title h2 .//h2 blank for text
Link a .//a[1] href by default
Description .summary .//div[@class='summary'] blank for sanitized HTML
Image img .//img blank for automatic detection
Date time .//time blank for exact datetime, then text

Use . for the card itself. Enter CSS attributes in the separate attribute field, rather than writing a@href. XPath may select attributes directly, such as .//a/@href. A configured link selector must return a safe URL or that card is skipped. Leaving the link selector empty uses a title-based identity, so a later title change creates a new item.

A preview can match cards but reject every item. Its diagnostics show whether each match has an empty title or a missing/unsafe link. Keep the Title attribute blank to read text. If the repeated item is an <a> element, use . for Link with attribute href; if it contains the anchor, use a in CSS or .//a in XPath. A link outside the selected item requires choosing a larger repeated container. Missing dates, descriptions, or images do not cause items to be skipped.

Warnings distinguish a selector matching nothing from a selected element with an empty value or missing attribute. For an unexpected value, they show what the field expected and a short sample of what it received, such as Date expected a date or relative age but received "First story". A newly published post may temporarily have no image; this is an optional-field warning and the next refresh can fill it in. Open Preview diagnostics for HTTP status and per-attempt match counts, or the saved feed's Diagnostics for refresh history.

Automatic image detection reads the first matched image, or the card's first descendant image when the selector is empty. It tries data-src, data-lazy-src, usable src, then the last usable candidate in data-srcset or srcset. It does not evaluate viewport widths. If none gives an address, as when a lazy-loading script leaves an inline data: placeholder in src, it tries these attributes on an img element in order: data-original, data-orig-src, data-orig-file, data-original-src, data-lazy-original, data-wpfc-original-src, data-lazy, data-lazyload, data-flickity-lazyload, data-flickity-lazyload-src, data-echo, data-breeze, nitro-lazy-src, data-pagespeed-lazy-src, data-cfsrc, data-ezsrc, data-actualsrc, data-image, data-image-src, data-img, data-img-src, data-img-url, data-webp, data-avif, data-thumb, then the srcset lists data-lazy-srcset, data-original-srcset, data-original-set, data-flickity-lazyload-srcset, data-brsrcset and nitro-lazy-srcset. A value there is refused if it is a flag, a number, a list, a directory or a common video, audio or document type. Anything else shaped like an address is accepted, including an extensionless one, because it cannot be told apart from a CDN address. A placeholder file in src, such as blank.gif, counts as the image, because it cannot be told apart from a real one. For that case, or for any other attribute, set an image selector and name the attribute in the image attribute field, which overrides detection and reads only the first match. A later image in the card is never used on its own, because it is as likely to be an avatar or an icon; a narrower selector reaches it. Images inside a description read only the usual attributes. The story's image is shown above its description, unless the description already shows it as an img with exactly that address, as when the Description selector covers the whole card; a link to the image, or a different size of it, still gets the image shown above. Links and images become absolute using the effective page URL and a valid <base> URL. Extracted content is sanitized.

The item preview and RSS/Atom readers load images directly from their source. Hotlink protection, expired URLs, and HTTPS mixed-content restrictions can prevent display. See publication dates for exact timestamps, relative dates, and custom formats.

Preview boundary

The server parses a bounded fetched/rendered page and sends JSON containing text and selector metadata. It removes script and stylesheet content, event handlers, style/srcdoc attributes, script URL values, and active/embed subtrees. Useful attributes such as IDs, classes, data-*, aria-*, href, image URLs, and dates are retained only as plain values in an inert XML document used for matching. Text nodes preserve whitespace, and hidden subtree roots retain their original sibling positions without source attributes or children. An element whose name the preview cannot carry is kept the same way, as a hidden placeholder under one fixed name, so its own name, attributes and contents are never sent. That covers prefixed names such as Word's <o:p> and <st1:City> or a widget's <fb:like>, and text the page's markup turns into a tag, such as an address written as <editor@example.com>.

The visible preview is built separately using DOM creation and textContent. Source attributes, URLs, styles, and scripts are never applied to its HTML elements, and source resources are not loaded by the selection view. Images appear as labeled placeholders, so the layout differs from the original page. The extracted-item preview still shows normalized source images as before.

The selection surface is a local iframe with sandbox="allow-scripts", without allow-same-origin. Its separate response CSP has default-src 'none', permits only the app's nonce-authorized bridge and stylesheet, prohibits forms/base URLs, restricts ancestors to the app origin, and repeats the sandbox restriction. The shell is public but contains no source or session data. The authenticated parent sends the snapshot after checking the exact iframe WindowProxy and its opaque null origin. Subsequent messages must also match a fresh 128-bit channel token and bounded message schema. The bridge only accepts messages from its parent at the browser-facing app origin. No arbitrary script evaluation or source navigation is supported.

These isolation choices follow the HTML iframe sandbox specification and cross-document messaging specification.

Snapshots require a session, Origin validation, JSON, and CSRF. Fetching shares refresh slots and the selected fetcher's deadline and concurrency pool. A FlareSolverr load that finds every FlareSolverr slot in use reports FlareSolverr is busy at once instead of waiting. A Chromium load is never refused for want of a Chromium slot: it takes a free one, or waits for one inside its deadline. Static and local Chromium requests use the existing outbound policy; FlareSolverr checks initial/final source URLs locally and depends on the external service's network boundary for remote browser traffic. Requests are cancelled when the picker is closed or reloaded, although a remote browser may continue until its own timeout. Source and encoded snapshot limits are 4 MiB; preview trees are limited to 12,000 nodes and 100 levels. Each element retains at most 64 allowed attributes with XML-safe names of at most 128 bytes and values of at most 2,048 bytes. Oversized pages return an error and can use manual selectors. Snapshots live only in the current picker, with no server cache or database changes.

Limits

Suggestions are a starting point: repeated classes may include unrelated cards, and positional selectors can change when a site adds elements. Match counts describe the snapshot; a fresh page can differ. Live XPath matching uses the browser's standard XPath evaluation. Preview items verifies the recipe with the Go extractor used by scheduled refreshes. Differences between the browser and Go evaluators, omitted attributes/subtrees, and snapshot limits can affect matches, so use that final preview before saving.

The Go XPath library can also fail on values the browser handles. Comparing a non-number with a number, as @data-score > 1 does on data-score="n/a", and a substring() range that runs past the end of a short value both stop extraction. The preview or refresh then reports selector evaluation failed with the field's name, or a cleanup rule's number, and saved stories are kept; a failed article selector, or a cleanup rule failing on an article page, keeps the list-page description instead. Because these depend on the page, a recipe that previews cleanly can fail later. Write number(@data-score) > 1 for the comparison, and prefer starts-with() or contains() to a fixed-length substring().

The Go XPath library also stops reading at the first complete expression and ignores the text after it, where the browser, and so the live highlight, reports an invalid selector. A CSS class selector left in an XPath recipe is the usual case, because changing Selector type by hand keeps the text: .summary runs as ., so a description becomes the whole card, the article body selector .entry-content selects the whole article page, and the repeated-item selector .post makes the whole page one item. .//h2 h3 likewise runs as .//h2. Preview items shows a warning that names the selector, such as Description selector: XPath uses only its first complete expression and ignores the text after it, and never quotes it; the import review shows the same warning under the recipe, and each refresh that reads the page records it in Diagnostics. A refresh the source answers with 304 Not Modified extracts nothing and records none, so use Preview items, which always reads the page, to check a feed. Saving refuses such a selector when the save introduces it: in a new feed or a duplicate, when its text changed, or when the feed's selector type has just become XPath. A feed that an earlier release saved with one keeps refreshing and publishing what it did, and its other settings can still be edited; a recipe file holding one still imports. Write the selector as XPath, such as .//*[@class='summary'], or set the type back to CSS and use Convert to XPath. The check covers the repeated-item selector, the five fields and the article body selector; cleanup rules must start with ./ instead. A stray closing parenthesis is not detected, and .//p) x runs as .//p. CSS that is also a valid XPath name, such as article.card, is not detected either: it is read as an element name and matches nothing, so a preview reports zero matches for the repeated-item selector, and an article selector leaves each story its list-page description.

Repeated-item selectors must return elements, and XPath field selectors must return nodes rather than scalar values such as count(...). Live matching limits expressions to 1,000 characters and repeated items to 1,000 matches; broadly overlapping cards can also exceed the workspace's isolated-copy limit. Content inside discarded embeds, SVG, shadow roots, and interactive controls cannot be selected. Unusual CSS class/ID syntax is omitted from suggestions in favor of element/positional paths. A converted field looks only inside its card, so CSS whose first part names the card itself, or something around it, such as the title article h2 for article cards, matches nothing once converted; write it without that part (h2). The same holds inside a :has() argument, in a field or a cleanup rule. The simplified selection view omits source styles and image downloads.

A page that contains prefixed or otherwise unsupported element names, as most text pasted from Word does, still opens. Each such element keeps its place among its siblings, so the positional paths the picker suggests for the elements around it, and :nth-child, :nth-of-type or p[3] and *[5] typed by hand, match in the preview as they do in extraction. The element's own text is missing from the preview, and nothing inside it can be clicked or highlighted. A selector that matches the element itself by position, such as :nth-child(4), is counted and reported as not visible. One that names it or reaches inside it matches nothing in the live view but works in Preview items and in refreshes: write o\:p in CSS, or *[name()='o:p'] in XPath. An unknown element that the page never closes, such as <fb:like ... /> or an <o:p /> standing between two paragraphs, holds everything up to the end of its parent, so the preview leaves that out too and can show part of the page or none of it. Whenever such an element holds other elements, the instructions shown under Page version once the page has loaded end by saying that part of the page is inside elements the preview cannot show. For that part, type the selectors by hand and check them with Preview items: the live match count does not see it either.

The example recipes show every field, the CSS and XPath forms of the same feed, and filtering with full article content, plus a feed source that reads the demo site's own RSS feed without selectors. They target a demo site included in this repository, so you can import one and watch it work before pointing a recipe at a site you do not control.