### DiscoverInput as String Example

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-feeds.md

This example shows the simplest way to call discoverFeeds, providing only the URL as a string.

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

--------------------------------

### Install Feedscout with bun

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/quick-start.md

Install the Feedscout package using bun. This is a newer package manager option.

```bash
bun add feedscout
```

--------------------------------

### DiscoverInput as Object Example

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-feeds.md

This example demonstrates calling discoverFeeds with an object for the input, allowing you to provide the URL, existing HTML content, and HTTP headers.

```typescript
// Object - provide existing content/headers
discoverFeeds({
  url: 'https://example.com',
  content: htmlContent,     // Optional HTML content
  headers: responseHeaders, // Optional HTTP headers
}, options)
```

--------------------------------

### Install Feedscout with pnpm

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/quick-start.md

Install the Feedscout package using pnpm. This is another alternative package manager.

```bash
pnpm add feedscout
```

--------------------------------

### Install Feedscout with npm

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/quick-start.md

Install the Feedscout package using npm. This is the first step to using the library.

```bash
npm install feedscout
```

--------------------------------

### Discover Input as String

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-hubs.md

Example of providing the input URL as a simple string to discoverHubs.

```typescript
discoverHubs('https://example.com/feed.xml')
```

--------------------------------

### Install Feedscout with yarn

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/quick-start.md

Install the Feedscout package using yarn. This is an alternative to npm for package management.

```bash
yarn add feedscout
```

--------------------------------

### Discover Input as Object

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-hubs.md

Example of providing the input as an object with URL, content, and headers to discoverHubs.

```typescript
discoverHubs({
  url: 'https://example.com/feed.xml',
  content: feedContent,
  headers: responseHeaders,
})
```

--------------------------------

### Basic Feed Discovery

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds.md

Import and use the discoverFeeds function to find feeds from a given URL. This is the most straightforward way to start using the library.

```typescript
import { discoverFeeds } from 'feedscout'

const feeds = await discoverFeeds('https://example.com')
```

--------------------------------

### discoverBlogrolls Input Parameter - Object with Content and Headers

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-blogrolls.md

Example of using discoverBlogrolls with an object containing URL, content, and headers.

```typescript
discoverBlogrolls({
  url: 'https://example.com',
  content: htmlContent,
  headers: responseHeaders,
}, options)
```

--------------------------------

### Configure Link Selectors for Headers Method

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/headers.md

Customize which Link headers are matched by specifying selectors based on 'rel' and 'types'. This example shows how to configure selectors to find alternate feeds with specific MIME types.

```typescript
import { mimeTypes } from 'feedscout/feeds'

const feeds = await discoverFeeds(url, {
  methods: {
    headers: {
      linkSelectors: [
        { rel: 'alternate', types: mimeTypes },
        { rel: 'feed' },
      ],
    },
  },
})
```

--------------------------------

### discoverBlogrolls Input Parameter - String URL

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-blogrolls.md

Example of using discoverBlogrolls with a string URL as input.

```typescript
discoverBlogrolls('https://example.com', options)
```

--------------------------------

### Default URL Resolution Examples

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/customization/url-resolution.md

Illustrates how Feedscout resolves relative URLs against a base URL by default.

```typescript
// Base URL: https://example.com/blog/
// Discovered: /feed.xml
// Resolved: https://example.com/feed.xml

// Base URL: https://example.com/blog/
// Discovered: ../rss
// Resolved: https://example.com/rss
```

--------------------------------

### Link Elements for Feed Discovery

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/html.md

Examples of HTML <link> elements used to advertise feeds, including rel="alternate" with MIME types and rel="feed" as per WHATWG specs.

```html
<!-- rel="alternate" with feed MIME type -->
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />

<!-- rel="feed" (WHATWG spec) -->
<link rel="feed" href="/feed" />
```

--------------------------------

### Anchor Elements for Feed Discovery

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/html.md

Examples of HTML <a> tags that can be matched for feed links, either by URI patterns or by link text content.

```html
<!-- Matched by URI -->
<a href="/feed.xml">XML</a>

<!-- Matched by label -->
<a href="/subscribe">RSS Feed</a>
```

--------------------------------

### Valid Feed Result Structure

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-feeds.md

This example shows the structure of a valid feed result returned by discoverFeeds. It includes the feed URL, validity status, discovery method, format, title, description, and site URL.

```typescript
// Valid result
{
  url: 'https://example.com/feed.xml',
  isValid: true,
  method: 'guess',       // 'platform' | 'html' | 'headers' | 'guess'
  format: 'rss',         // 'rss' | 'atom' | 'json' | 'rdf'
  title: 'Example Blog',
  description: 'A blog about examples',
  siteUrl: 'https://example.com',
}
```

--------------------------------

### getWwwCounterpart

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference.md

Get www/non-www variant of a URL. This is a utility function.

```APIDOC
## getWwwCounterpart

### Description
Get www/non-www variant of a URL.

### Import
`feedscout/methods`
```

--------------------------------

### Using Existing Content and Headers

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds.md

Pass pre-fetched HTML content and headers to `discoverFeeds` to avoid redundant network requests. This is useful when content is obtained through other means.

```typescript
// Response fetched someplace else
const response = await fetch('https://example.com')

const feeds = await discoverFeeds(
  {
    url: 'https://example.com',
    content: await response.text(),
    headers: response.headers,
  },
  { methods: ['html', 'headers'] },
)
```

--------------------------------

### Import Default HTML Options

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/html.md

Import the default configuration options for HTML feed discovery, including comprehensive anchor URIs and common feed labels.

```typescript
import { defaultHtmlOptions } from 'feedscout/feeds'
```

```typescript
import {
  linkSelectors,
  anchorLabels,
  urisComprehensive,
  ignoredUris,
} from 'feedscout/feeds'
```

--------------------------------

### Comprehensive URI Set for Guess Method

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

Imports the comprehensive set of URI paths for the Guess method. This set includes paths for WordPress, Blogger, and many other patterns, expanding on the balanced set.

```typescript
import { urisComprehensive } from 'feedscout/feeds'

// urisBalanced + [
//   '/?feed=rss',
//   '/?feed=atom',
//   '/feeds/posts/default',
//   ...
// ]
```

--------------------------------

### Import Default Headers Options

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/headers.md

Import the default configuration options for the Headers method, including default link selectors.

```typescript
import { defaultHeadersOptions } from 'feedscout/feeds'
```

--------------------------------

### Basic discoverBlogrolls Usage

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-blogrolls.md

Demonstrates basic usage of discoverBlogrolls with default methods or specified methods.

```typescript
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'],
})
```

--------------------------------

### Discover Favicons Valid Result

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-favicons.md

An example of a valid favicon result object, including the URL, a boolean indicating validity, and the method used for discovery.

```typescript
{
  url: 'https://example.com/favicon.ico',
  isValid: true,
  method: 'html',
}
```

--------------------------------

### Specify Discovery Methods (Object Syntax)

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds.md

Configure individual discovery methods with specific options by using an object. Set a method to `true` to use its default options.

```typescript
const feeds = await discoverFeeds(url, {
  methods: {
    platform: true, // Use defaults
    html: {
      anchorLabels: ['rss', 'feed'],
      anchorUris: ['/feed', '/rss'],
    },
    headers: true, // Use defaults
    guess: {
      uris: ['/feed', '/rss.xml', '/atom.xml'],
    },
  },
})
```

--------------------------------

### Discover Favicons Invalid Result

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-favicons.md

An example of an invalid favicon result object, shown when `includeInvalid` is set to true. It includes the URL, validity status, method, and the error encountered.

```typescript
{
  url: 'https://example.com/missing.png',
  isValid: false,
  method: 'guess',
  error: Error,
}
```

--------------------------------

### Discover Feeds with a Custom HTTP Client

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-feeds.md

This snippet shows how to integrate a custom HTTP client, such as Axios or Got, with discoverFeeds by providing a custom `fetchFn`. This allows for advanced network configurations and error handling.

```typescript
import type { DiscoverFetchFn } from 'feedscout'

const myCustomFetch: DiscoverFetchFn = async (url, options) => {
  // Handle the request and return response here.
}

const feeds = await discoverFeeds('https://example.com', {
  methods: ['html', 'guess'],
  fetchFn: myCustomFetch,
})
```

--------------------------------

### Invalid Feed Result Structure

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-feeds.md

This example illustrates the structure of an invalid feed result, which is returned when `includeInvalid` is set to true. It includes the URL, validity status, discovery method, and any error encountered.

```typescript
// Invalid result (when includeInvalid: true)
{
  url: 'https://example.com/not-a-feed',
  isValid: false,
  method: 'guess',
  error: Error,
}
```

--------------------------------

### Discover Hubs with Custom Fetch Function

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-hubs.md

Integrate a custom HTTP client for fetching data when discovering hubs. Requires defining a DiscoverFetchFn.

```typescript
import type { DiscoverFetchFn } from 'feedscout'

const myCustomFetch: DiscoverFetchFn = async (url, options) => {
  // Handle the request and return response here.
}

const hubs = await discoverHubs('https://example.com/feed.xml', {
  methods: ['headers', 'feed'],
  fetchFn: myCustomFetch,
})
```

--------------------------------

### Get Subdomain Variants Utility Function

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

Illustrates the `getSubdomainVariants` utility function, which generates a list of URLs with specified subdomains appended to a base URL. This is useful for testing feeds on related domains.

```typescript
import { getSubdomainVariants } from 'feedscout/methods'

getSubdomainVariants('https://example.com', ['blog', 'feeds'])
// [
//   'https://blog.example.com',
//   'https://feeds.example.com',
// ]
```

--------------------------------

### Discover Favicons Basic Usage

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-favicons.md

Demonstrates basic usage of the discoverFavicons function. By default, all discovery methods are enabled. You can also specify a subset of methods to use.

```typescript
import { discoverFavicons } from 'feedscout'

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

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

--------------------------------

### Get WWW Counterpart Utility Function

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

Demonstrates the `getWwwCounterpart` utility function, which returns the www or non-www variant of a given URL. This is helpful for ensuring feed discovery across different domain variations.

```typescript
import { getWwwCounterpart } from 'feedscout/methods'

getWwwCounterpart('https://example.com')
// 'https://www.example.com'

getWwwCounterpart('https://www.example.com')
// 'https://example.com'
```

--------------------------------

### Specify Discovery Methods (Array Syntax)

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds.md

Customize which discovery methods are used by providing an array of method names. This allows for fine-grained control over the discovery process.

```typescript
const feeds = await discoverFeeds(url, {
  methods: ['platform', 'html', 'headers', 'guess'],
})
```

--------------------------------

### Discover Favicons With Custom Options

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-favicons.md

Shows how to use discoverFavicons with custom options, including specifying URIs for the 'guess' method and enabling `stopOnFirstResult` to halt discovery after the first valid favicon is found.

```typescript
const favicons = await discoverFavicons('https://example.com', {
  methods: {
    guess: {
      uris: ['/favicon.ico', '/icon.svg'],
    },
  },
  stopOnFirstResult: true,
})
```

--------------------------------

### Custom Feed Extractor Example

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/customization/data-extraction.md

Provides a custom extractor function to validate feeds and extract specific metadata like format, title, and item count. It uses Feedsmith for parsing and returns a CustomFeedResult object. This extractor can be passed to `discoverFeeds` to override the default behavior.

```typescript
import type { DiscoverExtractFn, DiscoverResult } from 'feedscout'
import { parseFeed } from 'feedsmith'

type CustomFeedResult = {
  format: string
  title?: string
  itemCount: number
}

const customExtractor: DiscoverExtractFn<CustomFeedResult> = async ({ url, content }) => {
  try {
    const { format, feed } = parseFeed(content)

    return {
      url,
      isValid: true,
      format,
      title: feed.title,
      itemCount: feed.items?.length ?? 0,
    }
  } catch (error) {
    return { url, isValid: false, error }
  }
}

const feeds = await discoverFeeds(url, {
  methods: ['html', 'guess'],
  extractFn: customExtractor,
})

// [{
//   url: 'https://example.com/feed.xml',
//   isValid: true,
//   method: 'guess',
//   format: 'rss',
//   title: 'Example Blog',
//   itemCount: 10,
// }]
```

--------------------------------

### Import Default Platform Options

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/platform.md

Import the default Platform options configuration object from the feedscout/platform module.

```typescript
import { defaultPlatformOptions } from 'feedscout/platform'
```

--------------------------------

### Combining URL Resolution with Other Options

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/customization/url-resolution.md

Demonstrates using `resolveUrlFn` alongside other options like `methods`, `extractFn`, and `concurrency` with `discoverFeeds` and `discoverHubs`.

```typescript
const feeds = await discoverFeeds(url, {
  methods: ['html', 'guess'],
  resolveUrlFn: customResolve,
  extractFn: customExtractor,
  concurrency: 3,
})

const hubs = await discoverHubs(url, {
  methods: ['headers', 'html'],
  resolveUrlFn: customResolve,
})
```

--------------------------------

### Discover Feeds with Default Methods

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-feeds.md

This snippet shows the basic usage of discoverFeeds with default methods enabled. It takes a URL and returns a promise that resolves to an array of discovered feeds.

```typescript
import { discoverFeeds } from 'feedscout'

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

--------------------------------

### Directly Using Guess Discovery Function

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

Demonstrates how to use the `discoverUrisFromGuess` function directly to generate a list of potential feed URIs based on a base URL and a specific set of URI paths. Note that this function only generates URLs, it does not validate their existence.

```typescript
import { discoverUrisFromGuess } from 'feedscout/methods'

const uris = discoverUrisFromGuess({
  baseUrl: 'https://example.com',
  uris: ['/feed', '/rss.xml'],
})

// [
//   'https://example.com/feed',
//   'https://example.com/rss.xml',
// ]
```

--------------------------------

### Configure HTML Discovery for Blogrolls

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/other/blogrolls.md

Customize the HTML discovery method by specifying `anchorLabels` to match specific text in anchor tags. This refines how OPML links are identified within HTML.

```typescript
import { urisComprehensive } from 'feedscout/blogrolls'

const blogrolls = await discoverBlogrolls(url, {
  methods: {
    html: {
      anchorLabels: ['blogroll', 'opml', 'subscriptions'],
    },
    guess: {
      uris: urisComprehensive,
    },
  },
})
```

--------------------------------

### Minimal URI Set for Guess Method

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

Imports the minimal set of URI paths for the Guess method. This set covers basic paths suitable for most modern websites.

```typescript
import { urisMinimal } from 'feedscout/feeds'

// [
//   '/feed',
//   '/rss',
//   '/atom.xml',
//   '/feed.xml',
//   '/rss.xml',
//   '/index.xml',
// ]
```

--------------------------------

### Combining Custom Handlers with Defaults

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/platform.md

Demonstrates how to integrate custom platform handlers with FeedScout's default handlers. This allows extending the built-in discovery logic with specific rules.

```typescript
import { defaultPlatformOptions } from 'feedscout/platform'

const feeds = await discoverFeeds(url, {
  methods: {
    platform: {
      handlers: [myHandler, ...defaultPlatformOptions.handlers],
    },
  },
})
```

--------------------------------

### Discover Feeds with Custom Options

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-feeds.md

This snippet illustrates how to use discoverFeeds with custom options, including specific configurations for 'html' and 'guess' methods, concurrency limits, and stopping on the first result found.

```typescript
const feeds = await discoverFeeds('https://example.com', {
  methods: {
    html: {
      anchorLabels: ['rss', 'feed'],
    },
    guess: {
      uris: ['/feed', '/rss.xml'],
    },
  },
  concurrency: 3,
  stopOnFirstResult: true,
})
```

--------------------------------

### Discover Feeds with Progress Tracking

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-feeds.md

This snippet demonstrates how to track the progress of the feed discovery process using the `onProgress` callback. It logs the number of tested URLs, total URLs, and found feeds during the operation.

```typescript
const feeds = await discoverFeeds('https://example.com', {
  methods: ['html', 'guess'],
  onProgress: ({ tested, total, found, current }) => {
    console.log(`[${tested}/${total}] ${current} (${found} found)`)
  },
})
```

--------------------------------

### Discover Hubs with Existing Content and Headers

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/other/hubs.md

If you already have the feed's content and headers (e.g., from a fetch response), you can pass them directly to discoverHubs to avoid redundant fetching. This is useful for optimizing performance.

```typescript
const response = await fetch('https://example.com/feed.xml')
const content = await response.text()

const hubs = await discoverHubs(
  {
    url: 'https://example.com/feed.xml',
    content: await response.text(),
    headers: response.headers,
  },
  {
    methods: ['headers', 'feed'],
  },
)
```

--------------------------------

### Discover Feeds with Specified Methods

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-feeds.md

This snippet demonstrates how to specify which discovery methods to use when calling discoverFeeds. This allows for more targeted feed discovery.

```typescript
// Or specify which methods to use
const feeds = await discoverFeeds('https://example.com', {
  methods: ['html', 'headers', 'guess'],
})
```

--------------------------------

### Discover Blogrolls from URL

Source: https://github.com/macieklamberski/feedscout/blob/main/README.md

Discover blogroll (OPML) files from a given URL. The result includes the blogroll URL, validity, and title.

```typescript
import { discoverBlogrolls } from 'feedscout'

const blogrolls = await discoverBlogrolls('https://example.com')

// [{
//   url: 'https://example.com/blogroll.opml',
//   isValid: true,
//   title: 'My Blogroll',
// }]
```

--------------------------------

### Using Guess Method as a Fallback

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

Illustrates configuring Feedscout to use the Guess method as a fallback in the discovery process, after attempting HTML and Headers methods. This ensures feeds are found even if not advertised via standard autodiscovery.

```typescript
const feeds = await discoverFeeds(url, {
  methods: ['html', 'headers', 'guess'],
})
```

--------------------------------

### discoverBlogrolls Usage with Custom Options

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-blogrolls.md

Shows how to use discoverBlogrolls with custom options for HTML and guess methods.

```typescript
import { urisComprehensive } from 'feedscout/blogrolls'

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

--------------------------------

### Import Individual Platform Handlers

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/platform.md

Import specific platform handlers for use in custom configurations or direct discovery.

```typescript
import {
  acastHandler,
  amebloHandler,
  applePodcastsHandler,
  arenaHandler,
  artstationHandler,
  audioboomHandler,
  bearblogHandler,
  behanceHandler,
  blogspotHandler,
  blueskyHandler,
  bookwyrmHandler,
  buttondownHandler,
  buzzsproutHandler,
  codebergHandler,
  csdnHandler,
  dailymotionHandler,
  deviantartHandler,
  devtoHandler,
  discourseHandler,
  doubanHandler,
  dreamwidthHandler,
  exblogHandler,
  firesideHandler,
  friendicaHandler,
  ghostHandler,
  githubHandler,
  githubGistHandler,
  gitlabHandler,
  goodreadsHandler,
  hackernewsHandler,
  hashnodeHandler,
  hatenablogHandler,
  hearthisHandler,
  heyWorldHandler,
  insanejournalHandler,
  itchioHandler,
  kickstarterHandler,
  letterboxdHandler,
  libsynHandler,
  listedHandler,
  livejournalHandler,
  lobstersHandler,
  mastodonHandler,
  mataroaHandler,
  mediumHandler,
  microblogHandler,
  misskeyHandler,
  myanimelistHandler,
  naverBlogHandler,
  nebulaHandler,
  noteHandler,
  observableHandler,
  odyseeHandler,
  pagecordHandler,
  paragraphHandler,
  pikaHandler,
  pixelfedHandler,
  pleromaHandler,
  podbeanHandler,
  podigeeHandler,
  posthavenHandler,
  producthuntHandler,
  proseHandler,
  qiitaHandler,
  redditHandler,
  rssComHandler,
  seesaaHandler,
  soundcloudHandler,
  sourceforgeHandler,
  spreakerHandler,
  stackExchangeHandler,
  steamHandler,
  substackHandler,
  tildesHandler,
  tistoryHandler,
  transistorHandler,
  tumblrHandler,
  v2exHandler,
  velogHandler,
  vimeoHandler,
  weblogLolHandler,
  weeblyHandler,
  wordpressHandler,
  wpengineHandler,
  writeasHandler,
  ximalayaHandler,
  youtubeHandler,
  zennHandler,
} from 'feedscout/platform'
```

--------------------------------

### Customize Blogroll Discovery Methods

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/other/blogrolls.md

Customize which discovery methods are used by passing an array of method names to the `methods` option. This allows for targeted discovery.

```typescript
const blogrolls = await discoverBlogrolls('https://example.com', {
  methods: ['html', 'headers'],
})
```

--------------------------------

### Method-Specific Discovery Options

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/typescript.md

Configure discovery methods like 'html' and 'guess' with inline options to refine the search for feed URLs and anchors.

```typescript
const feeds = await discoverFeeds(url, {
  methods: {
    html: {
      anchorLabels: ['rss', 'feed'],
      anchorUris: ['/feed', '/rss'],
    },
    guess: {
      uris: ['/feed', '/rss.xml'],
    },
  },
})
```

--------------------------------

### Discover Feeds from URL

Source: https://github.com/macieklamberski/feedscout/blob/main/README.md

Discover feeds from a given URL using default methods. The result includes feed URL, validity, format, title, description, and site URL.

```typescript
import { discoverFeeds } from 'feedscout'

const feeds = await discoverFeeds('https://example.com')

// [{
//   url: 'https://example.com/feed.xml',
//   isValid: true,
//   format: 'rss',
//   title: 'Example Blog',
//   description: 'A blog about examples',
//   siteUrl: 'https://example.com',
// }]
```

--------------------------------

### Discover Hubs with Specific Methods

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-hubs.md

Specify which discovery methods (headers, feed) to use when finding hubs.

```typescript
const hubs = await discoverHubs('https://example.com/feed.xml', {
  methods: ['headers', 'feed'],
})
```

--------------------------------

### Basic Platform Handler

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/platform.md

A handler that appends '/feed.xml' to any URL on a specific domain. It matches URLs based on the hostname and resolves to a fixed feed URI.

```typescript
import type { PlatformHandler } from 'feedscout/platform'

const myHandler: PlatformHandler = {
  match: (url) => {
    return new URL(url).hostname === 'example.com'
  },

  resolve: (url) => {
    const { origin } = new URL(url)

    return [{ uri: `${origin}/feed.xml` }]
  },
}
```

--------------------------------

### Comprehensive URI Set for Blogroll Discovery

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/other/blogrolls.md

The `urisComprehensive` set includes a wide range of less common patterns for blogroll discovery. Use this for maximum coverage when other sets are insufficient.

```typescript
import { urisComprehensive } from 'feedscout/blogrolls'

// urisBalanced + [
//   '/links.opml',
//   '/feeds.opml',
//   '/subscriptions.xml',
// ]
```

--------------------------------

### Import Link Selectors

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/headers.md

Import the default link selectors configuration specifically for the Headers method.

```typescript
import { linkSelectors } from 'feedscout/feeds'
```

--------------------------------

### Main Feedscout Exports

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference.md

Import the primary functions for discovering feeds, blogrolls, and hubs, along with common types.

```typescript
// Main exports
import { discoverFeeds, discoverBlogrolls, discoverHubs } from 'feedscout'
import type { DiscoverUriEntry, DiscoverUriHint, UriEntry } from 'feedscout'
```

--------------------------------

### Balanced URI Set for Guess Method

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

Imports the balanced set of URI paths for the Guess method. This set includes JSON Feed and common variations in addition to the minimal set.

```typescript
import { urisBalanced } from 'feedscout/feeds'

// urisMinimal + [
//   '/feed/',
//   '/index.atom',
//   '/index.rss',
//   '/feed.json',
// ]
```

--------------------------------

### Discover Favicons Input Types

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/discover-favicons.md

Illustrates the two ways to provide input to the discoverFavicons function: as a simple URL string or as an object containing the URL, content, and headers.

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

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

--------------------------------

### Configured Axios Instance Fetch Function

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/customization/data-fetching.md

Uses a pre-configured Axios instance to create a custom fetch function for Feedscout, allowing for shared configurations like timeouts and headers.

```typescript
const client = axios.create({
  timeout: 5000,
  headers: { 'User-Agent': 'MyApp/1.0' },
})

const axiosFetch: DiscoverFetchFn = async (url, options) => {
  const response = await client({
    url,
    method: options?.method ?? 'GET',
    headers: options?.headers,
    validateStatus: () => true,
  })

  return {
    headers: new Headers(response.headers.toJSON() as Record<string, string>),
    body: response.data,
    url: response.request?.res?.responseUrl ?? url,
    status: response.status,
    statusText: response.statusText,
  }
}
```

--------------------------------

### Customize Favicon Discovery Methods

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/other/favicons.md

Specify which discovery methods to use by passing an array of method names to the options. This allows for targeted favicon searching.

```typescript
const favicons = await discoverFavicons('https://example.com', {
  methods: ['html', 'headers', 'guess'],
})
```

--------------------------------

### Configure Platform Handler Order

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/platform.md

Customize the order in which platform handlers are checked. The first handler to match will generate the feeds.

```typescript
import { githubHandler, youtubeHandler } from 'feedscout/platform'

const feeds = await discoverFeeds(url, {
  methods: {
    platform: {
      handlers: [youtubeHandler, githubHandler, redditHandler],
    },
  },
})
```

--------------------------------

### Discover Feeds with Custom Methods

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/quick-start.md

Discover feeds from a URL, specifying only the 'html' and 'headers' discovery methods. This allows for more targeted discovery.

```typescript
const feeds = await discoverFeeds('https://example.com', {
  methods: ['html', 'headers'],
})
```

--------------------------------

### Discover Feeds from Existing HTTP Headers

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/quick-start.md

Discover feeds by providing HTTP headers directly, along with the URL, to avoid an extra fetch. This is useful when you already have the response headers.

```http
Link: </feed.xml>; rel="alternate"; type="application/rss+xml"
```

```typescript
const feeds = await discoverFeeds(
  { url: 'https://example.com', headers },
  { methods: ['headers'] },
)
```

--------------------------------

### Monitor Discovery Progress

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds.md

Implement a progress callback using the `onProgress` option to track the discovery process. The callback receives statistics about tested, total, found, and current items.

```typescript
const feeds = await discoverFeeds(url, {
  methods: ['html', 'guess'],
  onProgress: ({ tested, total, found, current }) => {
    console.log(`[${tested}/${total}] Testing: ${current}`)
    console.log(`Found so far: ${found}`)
  },
})
```

--------------------------------

### Discover Blogrolls from a URL

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/other/blogrolls.md

Use `discoverBlogrolls()` to find OPML files from a given URL. This is the primary function for blogroll discovery.

```typescript
import { discoverBlogrolls } from 'feedscout'

const blogrolls = await discoverBlogrolls('https://example.com')
```

--------------------------------

### Custom Fetch Function Implementation

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/typescript.md

Implement a custom fetch function that adheres to the `DiscoverFetchFn` type signature. This allows integrating Feedscout with custom HTTP clients or request logic.

```typescript
import type { DiscoverFetchFn } from 'feedscout'

const customFetch: DiscoverFetchFn = async (url, options) => {
  const response = await myClient.request(url, options)

  return {
    url: response.url,
    status: response.status,
    statusText: response.statusText,
    headers: new Headers(response.headers),
    body: response.data,
  }
}
```

--------------------------------

### Define DiscoverOptions Type

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/types.md

Defines the configuration options for discovery functions. Most fields are optional, allowing for simple usage. The TMethods parameter can restrict available discovery methods.

```typescript
type DiscoverOptions<TValid, TMethods extends DiscoverMethod = DiscoverMethod> = {
  methods?: DiscoverMethodsConfig<TMethods>
  fetchFn?: DiscoverFetchFn
  extractFn?: DiscoverExtractFn<TValid>
  resolveUrlFn?: DiscoverResolveUrlFn
  stopOnFirstMethod?: boolean
  stopOnFirstResult?: boolean
  concurrency?: number
  includeInvalid?: boolean
  onProgress?: DiscoverOnProgressFn
}
```

--------------------------------

### isHostOf

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference.md

Check if URL host matches any in list. This is a utility function.

```APIDOC
## isHostOf

### Description
Check if URL host matches any in list.

### Import
`feedscout/utils`
```

--------------------------------

### generateUrlCombinations

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference.md

Combine base URLs with URI paths. This is a utility function.

```APIDOC
## generateUrlCombinations

### Description
Combine base URLs with URI paths.

### Import
`feedscout/methods`
```

--------------------------------

### Discovery Method Exports

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference.md

Import functions for extracting URIs from various sources without validation.

```typescript
// Discovery method functions
import { discoverUrisFromPlatform, discoverUrisFromHtml } from 'feedscout/methods'
```

--------------------------------

### Configure Custom Guess Paths for Favicons

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/other/favicons.md

Customize the favicon discovery process by providing specific URIs for the 'guess' method. This allows you to define custom paths to check for favicons.

```typescript
const favicons = await discoverFavicons(url, {
  methods: {
    html: true,
    guess: {
      uris: ['/favicon.ico', '/icon.svg'],
    },
  },
})
```

--------------------------------

### Generate URL Combinations Utility Function

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

Shows how to use the `generateUrlCombinations` utility function to create a list of full URLs by combining base URLs with a set of URI paths. This function is fundamental for the Guess method's operation.

```typescript
import { generateUrlCombinations } from 'feedscout/methods'

generateUrlCombinations(['https://example.com'], ['/feed', '/rss'])
// [
//   'https://example.com/feed',
//   'https://example.com/rss',
// ]
```

--------------------------------

### Discover Feeds from a Platform

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/platform.md

Use the discoverFeeds function to find platform-specific feeds. Specify 'platform' in methods to enable platform discovery.

```typescript
import { discoverFeeds } from 'feedscout'

const feeds = await discoverFeeds('https://github.com/feedstand/feedstand', {
  methods: ['platform'],
})

// [
//   { url: 'https://github.com/feedstand/feedstand/releases.atom', ... },
//   { url: 'https://github.com/feedstand/feedstand/commits.atom', ... },
//   { url: 'https://github.com/feedstand/feedstand/tags.atom', ... },
// ]
```

--------------------------------

### Default Guess Paths for Favicon Discovery

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/other/favicons.md

Import and inspect the default array of paths that Feedscout checks when using the 'guess' method for favicon discovery.

```typescript
import { defaultGuessPaths } from 'feedscout/favicons'

// [
//   '/favicon.ico',
//   '/apple-touch-icon.png',
//   '/apple-touch-icon-precomposed.png',
//   '/favicon.png',
//   '/favicon.svg',
// ]
```

--------------------------------

### Generic DiscoverOptions with Custom Result Type

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/typescript.md

Demonstrates using generic `DiscoverOptions` with a custom result type (`CustomResult`) and a custom extractor function. This allows for flexible data extraction beyond the default `FeedResult`.

```typescript
// Default usage with FeedResult
const options: DiscoverOptions<FeedResult> = {
  methods: ['html', 'guess'],
}

// Custom extractor with different result type
type CustomResult = {
  customField: string
}

const options: DiscoverOptions<CustomResult> = {
  methods: ['html'],
  extractFn: async ({ url, content }) => {
    return {
      url,
      isValid: true,
      customField: 'value',
    }
  },
}
```

--------------------------------

### discoverUrisFromPlatform

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference.md

Generate feed URIs for known platforms. This is a discovery method function.

```APIDOC
## discoverUrisFromPlatform

### Description
Generate feed URIs for known platforms.

### Import
`feedscout/methods`
```

--------------------------------

### Define DiscoverHubsOptions Type

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/types.md

Defines the options for the discoverHubs function, including method configuration and a custom fetch function.

```typescript
type DiscoverHubsOptions = {
  methods?: DiscoverHubsMethodsConfig
  fetchFn?: DiscoverFetchFn
}

type DiscoverHubsMethodsConfig = Array<'headers' | 'html' | 'feed'>
```

--------------------------------

### Platform Handler with URL Patterns

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/platform.md

A handler that extracts a username from the URL path to construct a feed URI. It matches URLs with a specific path prefix and uses regex to capture parts of the path.

```typescript
const profileHandler: PlatformHandler = {
  match: (url) => {
    const { hostname, pathname } = new URL(url)

    return hostname === 'example.com' && pathname.startsWith('/users/')
  },

  resolve: (url) => {
    const { origin, pathname } = new URL(url)
    const match = pathname.match(/^\/users\/([^/]+)/)

    if (match?.[1]) {
      return [{ uri: `${origin}/users/${match[1]}/feed.rss` }]
    }

    return []
  },
}
```

--------------------------------

### Stop URI Collection After First Method

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds.md

Enable `stopOnFirstMethod` to halt URI collection once the first discovery method yields results. This optimizes performance by avoiding unnecessary checks, especially for platforms where early methods are most effective.

```typescript
const feeds = await discoverFeeds(url, {
  methods: ['platform', 'html', 'headers', 'guess'],
  stopOnFirstMethod: true,
})
// Only URIs from the first successful method are validated
```

--------------------------------

### Discover Feeds from HTML Content

Source: https://github.com/macieklamberski/feedscout/blob/main/README.md

Discover feeds by providing existing HTML content. This method specifically uses the 'html' discovery method.

```html
<html>
  <head>
    <link rel="alternate" type="application/rss+xml" href="/feed.xml" />
  </head>
  <body>
    <a href="/rss">RSS Feed</a>
  </body>
</html>
```

```typescript
const feeds = await discoverFeeds(
  { url: 'https://example.com', content: html },
  { methods: ['html'] },
)

// [
//   {
//     url: 'https://example.com/feed.xml',
//     isValid: true,
//     format: 'rss',
//     title: 'Example Blog',
//     description: 'A blog about examples',
//     siteUrl: 'https://example.com',
//   },
//   {
//     url: 'https://example.com/rss',
//     isValid: true,
//     format: 'rss',
//     title: 'Example Blog',
//     description: 'A blog about examples',
//     siteUrl: 'https://example.com',
//   },
// ]
```

--------------------------------

### Discover Feeds from HTTP Headers

Source: https://github.com/macieklamberski/feedscout/blob/main/README.md

Discover feeds by parsing provided HTTP headers. This method specifically uses the 'headers' discovery method.

```http
Link: </feed.xml>; rel="alternate"; type="application/rss+xml"
```

```typescript
const feeds = await discoverFeeds(
  { url: 'https://example.com', headers },
  { methods: ['headers'] },
)

// [{
//   url: 'https://example.com/feed.xml',
//   isValid: true,
//   format: 'rss',
//   title: 'Example Blog',
//   description: 'A blog about examples',
//   siteUrl: 'https://example.com',
// }]
```

--------------------------------

### Discover Favicons from URL

Source: https://github.com/macieklamberski/feedscout/blob/main/README.md

Discover favicons from a given URL. The result includes the favicon URL and its validity.

```typescript
import { discoverFavicons } from 'feedscout'

const favicons = await discoverFavicons('https://example.com')

// [{
//   url: 'https://example.com/apple-touch-icon.png',
//   isValid: true,
// }]
```

--------------------------------

### Progress Callback Function

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/typescript.md

Define a progress callback function that accepts `DiscoverProgress` to monitor the discovery process. This is useful for providing user feedback on the number of URLs tested versus the total.

```typescript
import type { DiscoverOnProgressFn, DiscoverProgress } from 'feedscout'

const onProgress: DiscoverOnProgressFn = (progress: DiscoverProgress) => {
  console.log(`${progress.tested}/${progress.total}`)
}
```

--------------------------------

### Define DiscoverMethodsConfig Type

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/types.md

Defines the configuration structure for discovery methods. It can be an array of method names or a specific configuration object for each method.

```typescript
type DiscoverMethodsConfig<TMethods extends DiscoverMethod = DiscoverMethod> =
  | Array<TMethods>
  | Pick<
      {
        platform?: true | Partial<PlatformMethodOptions>
        feed?: true | Partial<FeedMethodOptions>
        html?: true | Partial<Omit<HtmlMethodOptions, 'baseUrl'>>
        headers?: true | Partial<Omit<HeadersMethodOptions, 'baseUrl'>>
        guess?: true | Partial<Omit<GuessMethodOptions, 'baseUrl'>>
      },
      TMethods
    >
```

--------------------------------

### Import Core Types

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference/types.md

Imports essential types for discovery functions from the main feedscout package.

```typescript
import type {
  DiscoverInput,
  DiscoverMethod,
  DiscoverOptions,
  DiscoverResult,
  DiscoverProgress,
  DiscoverFetchFn,
  DiscoverResolveUrlFn,
  DiscoverUriEntry,
  DiscoverUriHint,
  UriEntry,
} from 'feedscout'

import type { HubResult, DiscoverHubsOptions } from 'feedscout/hubs'
```

--------------------------------

### Configuring Additional Base URLs for Guess Method

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

Extends the Guess method's scope by specifying additional base URLs, such as www counterparts or subdomains, to test feed paths against. This is useful for sites with multiple entry points.

```typescript
import { getWwwCounterpart, getSubdomainVariants } from 'feedscout/methods'

const feeds = await discoverFeeds('https://example.com', {
  methods: {
    guess: {
      uris: ['/feed', '/rss.xml'],
      additionalBaseUrls: [
        getWwwCounterpart('https://example.com'),
        ...getSubdomainVariants('https://example.com', ['blog', 'feeds']),
      ],
    },
  },
})
```

--------------------------------

### Discover Feeds from Existing HTML Content

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/quick-start.md

Discover feeds by providing the HTML content directly, along with the URL, to avoid an extra fetch. This is useful when you already have the page content.

```html
<html>
  <head>
    <link rel="alternate" type="application/rss+xml" href="/feed.xml" />
  </head>
  <body>
    <a href="/rss">RSS Feed</a>
  </body>
</html>
```

```typescript
const feeds = await discoverFeeds(
  { url: 'https://example.com', content: html },
  { methods: ['html'] },
)
```

--------------------------------

### Discover WebSub Hubs from Feed URL

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/quick-start.md

Discover WebSub hubs for a given feed URL. This is useful for setting up real-time notifications.

```typescript
import { discoverHubs } from 'feedscout'

const hubs = await discoverHubs('https://example.com/feed.xml')
```

--------------------------------

### Configure Link Selectors for HTML Feeds

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/html.md

Customize which <link> elements are matched during HTML feed discovery by specifying rel attributes and MIME types.

```typescript
import { mimeTypes } from 'feedscout/feeds'

const feeds = await discoverFeeds(url, {
  methods: {
    html: {
      linkSelectors: [
        { rel: 'alternate', types: mimeTypes },
        { rel: 'feed' },
      ],
    },
  },
})
```

--------------------------------

### Platform-Specific Exports

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference.md

Import handlers and types for platform-specific feed discovery.

```typescript
// Platform-specific handlers and types
import { youtubeHandler, defaultPlatformOptions } from 'feedscout/platform'
import type { PlatformHandler } from 'feedscout/platform'
```

--------------------------------

### Discover WebSub Hubs for a Feed

Source: https://github.com/macieklamberski/feedscout/blob/main/README.md

Discover WebSub hubs for a given feed URL. The result includes the hub URL and the topic URL.

```typescript
import { discoverHubs } from 'feedscout'

const hubs = await discoverHubs('https://example.com/feed.xml')

// [{
//   hub: 'https://pubsubhubbub.appspot.com',
//   topic: 'https://example.com/feed.xml',
// }]
```

--------------------------------

### Utility Function Exports

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/reference.md

Import utility functions for URL manipulation and string checking.

```typescript
// Utility functions
import { isSubdomainOf, isHostOf } from 'feedscout/utils'
```

--------------------------------

### Discover URIs Directly from Platform Content

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/platform.md

Use discoverUrisFromPlatform to extract URIs without validation, useful for parsing specific content with a chosen handler.

```typescript
import { discoverUrisFromPlatform } from 'feedscout/platform'

const uris = discoverUrisFromPlatform(htmlContent, {
  baseUrl: 'https://www.youtube.com/@mkbhd',
  handlers: [youtubeHandler],
})

// [
//   {
//     uri: [
//       'https://www.youtube.com/feeds/videos.xml?channel_id=UCBJycsmduvYEL83R_U4JriQ',
//       'https://www.youtube.com/feeds/videos.xml?playlist_id=UUBJycsmduvYEL83R_U4JriQ',
//     ],
//     hint: { key: 'youtube:all', label: 'All uploads' },
//   },
//   {
//     uri: 'https://www.youtube.com/feeds/videos.xml?playlist_id=UULFBJycsmduvYEL83R_U4JriQ',
//     hint: { key: 'youtube:videos', label: 'Videos only' },
//   },
//   {
//     uri: 'https://www.youtube.com/feeds/videos.xml?playlist_id=UUSHBJycsmduvYEL83R_U4JriQ',
//     hint: { key: 'youtube:shorts', label: 'Shorts only' },
//   },
//   {
//     uri: 'https://www.youtube.com/feeds/videos.xml?playlist_id=UULVBJycsmduvYEL83R_U4JriQ',
//     hint: { key: 'youtube:live', label: 'Live streams only' },
//   },
// ]
```

--------------------------------

### Common Feed Paths for Guess Method

Source: https://github.com/macieklamberski/feedscout/blob/main/docs/feeds/guess.md

These are the default paths tested by the Guess method when no specific URIs are provided. They represent common locations for RSS, Atom, and other feed formats.

```text
/feed
/rss
/atom.xml
/feed.xml
/rss.xml
/index.xml
```