discoverBlogrolls

Discovers and validates OPML blogrolls from a webpage.

Signature

function discoverBlogrolls(
  input: DiscoverInput,
  options?: DiscoverOptions<BlogrollResult, 'html' | 'headers' | 'guess'>,
): Promise<Array<DiscoverResult<BlogrollResult>>>

Parameters

input

The URL to discover blogrolls from. Can be a string or an object:

// String - URL to fetch and scan
discoverBlogrolls('https://example.com', options)

// Object - provide existing content/headers
discoverBlogrolls({
  url: 'https://example.com',
  content: htmlContent,
  headers: responseHeaders,
}, options)

options

All options are optional. When not provided, sensible defaults are used.

Property	Type	Default	Description
methods	DiscoverMethodsConfig	['html', 'headers', 'guess']	Which methods to use
fetchFn	FetchFn	native fetch	Custom fetch function
extractFn	DiscoverExtractFn	feedsmith	Custom OPML extraction function
resolveUrlFn	DiscoverResolveUrlFn	resolve relative	Custom URL resolution function
resolveSiteUrlFn	DiscoverResolveSiteUrlFn	site link from feed	Resolves the site URL to scan when the input is a feed
stopOnFirstMethod	boolean	false	Stop after the first method that finds a valid result
stopOnFirstResult	boolean	false	Stop after first valid blogroll
concurrency	number	3	Max parallel validations
maxUris	number	50	Max total candidate URIs to fetch across all methods
includeInvalid	boolean	false	Include invalid results
onProgress	DiscoverOnProgressFn		Progress callback
onStep	DiscoverOnStepFn		Called when each stage of discovery starts and ends
onError	DiscoverOnErrorFn		Called when fetching the input or the site URL fails. DiscoverOnErrorFn lists everything it reports

Return Value

Returns a promise that resolves to an array of results:

// Valid result
{
  url: 'https://example.com/blogroll.opml',
  isValid: true,
  title: 'My Reading List',
  method: 'guess',
}

// Invalid result (when includeInvalid: true)
{
  url: 'https://example.com/not-opml.xml',
  isValid: false,
  error: Error, // Only set when the request or the extractor threw
  method: 'guess',
}

Each blogroll URL appears once. When several candidates lead to the same blogroll, for example /blogroll.opml and /links.opml both redirecting to one file, only the first is kept. The same applies to invalid results with includeInvalid.

Examples

Basic Usage

import { discoverBlogrolls } from 'feedscout'

// Simple usage - all methods enabled by default
const blogrolls = await discoverBlogrolls('https://example.com')

// Or specify which methods to use
const blogrolls = await discoverBlogrolls('https://example.com', {
  methods: ['html', 'guess'],
})

With Custom Options

import { urisComprehensive } from 'feedscout/blogrolls'

const blogrolls = await discoverBlogrolls('https://example.com', {
  methods: {
    html: {
      anchorLabels: ['blogroll', 'opml'],
    },
    guess: {
      uris: urisComprehensive,
    },
  },
})