readdown

https://github.com/zcag/readdown
Admin
readdown is an HTML-to-Markdown converter optimized for LLMs that extracts main content, strips...
Tokens:3,074
Snippets:24
Trust Score:9.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install readdown via JSR or npm

Source: https://github.com/zcag/readdown/blob/master/README.md

Install the package via JSR (recommended) or npm from GitHub. Use the JSR command for Deno/Node projects and the npm command for npm-based projects.

```bash
npx jsr add @zcag/readdown
```

```bash
npm install github:zcag/readdown
```

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

### Use the readdown CLI

Source: https://github.com/zcag/readdown/blob/master/README.md

Install the CLI globally, then convert a URL, pipe HTML from curl, or read from a file. The CLI accepts a URL argument or reads HTML from stdin.

```bash
npx jsr add -g @zcag/readdown
```

```bash
readdown https://example.com/article
```

```bash
curl -s https://example.com | readdown
```

```bash
cat page.html | readdown
```

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

### Import individual readdown functions

Source: https://github.com/zcag/readdown/blob/master/README.md

Import individual functions for custom pipelines: findMainContent, elementToMarkdown, extractMetadata, and estimateTokens.

```ts
import { findMainContent, elementToMarkdown, extractMetadata, estimateTokens } from 'readdown';
```

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

### Convert HTML to Markdown with readdown

Source: https://github.com/zcag/readdown/blob/master/README.md

Import the readdown function, fetch an HTML page, and convert it to Markdown. The result includes markdown, token count, and metadata. The url option resolves relative links.

```ts
import { readdown } from 'readdown';

const html = await fetch('https://example.com/article').then(r => r.text());
const result = readdown(html, { url: 'https://example.com/article' });

console.log(result.markdown);  // Clean markdown
console.log(result.tokens);    // ~1,250
console.log(result.metadata);  // { title, author, date, ... }
```

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

### Use readdown GitHub Action

Source: https://github.com/zcag/readdown/blob/master/README.md

Use the readdown GitHub Action in a workflow. Specify the URL to convert as an input.

```yaml
- uses: zcag/readdown@v0.2.0
  with:
    url: 'https://example.com/article'
```

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

### findMainContent(html)

Source: https://github.com/zcag/readdown/blob/master/README.md

Exported function for custom pipelines. Extracts the main content from an HTML document.

```APIDOC
## findMainContent(html)

### Description
Extracts the main content from an HTML document, stripping navigation, sidebars, footers, and ads.

### Method
Function

### Endpoint
findMainContent(html)

### Parameters
#### Parameters
- **html** (string) - Required - HTML string to process.

### Request Example
```ts
import { findMainContent } from 'readdown';
const main = findMainContent(html);
```

### Response
#### Success Response
Returns the main content as a string or DOM element (exact type not specified in source).
```

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

### readdown(html, options?)

Source: https://github.com/zcag/readdown/blob/master/README.md

The main function of the readdown library. Converts HTML to clean Markdown optimized for LLMs, with options for URL resolution, header inclusion, and raw conversion.

```APIDOC
## readdown(html, options?)

### Description
Converts HTML to clean Markdown optimized for LLMs. Extracts main content, converts to Markdown, and estimates token usage.

### Method
Function

### Endpoint
readdown(html, options?)

### Parameters
#### Parameters
- **html** (string) - Required - HTML string to convert.
- **options** (object) - Optional - Configuration options.
  - **url** (string) - Optional - Base URL for resolving relative links/images.
  - **includeHeader** (boolean) - Optional - Add title/source/author header to output. Default: `true`.
  - **raw** (boolean) - Optional - Skip content extraction, convert full body. Default: `false`.

### Request Example
```ts
import { readdown } from 'readdown';
const html = await fetch('https://example.com/article').then(r => r.text());
const result = readdown(html, { url: 'https://example.com/article' });
```

### Response
#### Success Response
Returns a `ReaddownResult` object:
- **markdown** (string) - Clean markdown output.
- **metadata** (object) - Extracted metadata with fields: `title` (string), `author?` (string), `date?` (string), `description?` (string), `siteName?` (string), `url?` (string), `image?` (string), `lang?` (string).
- **tokens** (number) - Approximate token count.
- **chars** (number) - Character count.
- **contextUsage** (object) - Percentage of context window used for models: `'gpt-4o'` (number), `'claude-4'` (number), `'gemini-2.5'` (number).

#### Response Example
```ts
{
  markdown: '# Title\n\nContent...',
  metadata: { title: 'Example', author: 'John Doe', date: '2026-03-01' },
  tokens: 1250,
  chars: 8000,
  contextUsage: { 'gpt-4o': 0.5, 'claude-4': 0.4, 'gemini-2.5': 0.6 }
}
```
```

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

### estimateTokens(text)

Source: https://github.com/zcag/readdown/blob/master/README.md

Exported function for custom pipelines. Estimates the approximate token count for a given text.

```APIDOC
## estimateTokens(text)

### Description
Estimates the approximate token count for a given text.

### Method
Function

### Endpoint
estimateTokens(text)

### Parameters
#### Parameters
- **text** (string) - Required - Text to estimate tokens for.

### Request Example
```ts
import { estimateTokens } from 'readdown';
const tokens = estimateTokens(markdown);
```

### Response
#### Success Response
Returns a number representing the approximate token count.
```

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

### elementToMarkdown(element)

Source: https://github.com/zcag/readdown/blob/master/README.md

Exported function for custom pipelines. Converts a DOM element to Markdown.

```APIDOC
## elementToMarkdown(element)

### Description
Converts a DOM element to Markdown.

### Method
Function

### Endpoint
elementToMarkdown(element)

### Parameters
#### Parameters
- **element** (HTMLElement) - Required - DOM element to convert.

### Request Example
```ts
import { elementToMarkdown } from 'readdown';
const markdown = elementToMarkdown(element);
```

### Response
#### Success Response
Returns a string of Markdown.
```

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

### extractMetadata(html)

Source: https://github.com/zcag/readdown/blob/master/README.md

Exported function for custom pipelines. Extracts metadata from HTML.

```APIDOC
## extractMetadata(html)

### Description
Extracts metadata (title, author, date, etc.) from meta tags, JSON-LD, and other sources.

### Method
Function

### Endpoint
extractMetadata(html)

### Parameters
#### Parameters
- **html** (string) - Required - HTML string to extract metadata from.

### Request Example
```ts
import { extractMetadata } from 'readdown';
const metadata = extractMetadata(html);
```

### Response
#### Success Response
Returns an object with fields: `title` (string), `author?` (string), `date?` (string), `description?` (string), `siteName?` (string), `url?` (string), `image?` (string), `lang?` (string).
```

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

### ReaddownResult type definition

Source: https://github.com/zcag/readdown/blob/master/README.md

The ReaddownResult type returned by readdown. Includes markdown string, metadata object, token count, character count, and context usage percentages for GPT-4o, Claude-4, and Gemini-2.5.

```ts
{
  markdown: string;       // Clean markdown output
  metadata: {             // Extracted from meta tags, JSON-LD, etc.
    title: string;
    author?: string;
    date?: string;
    description?: string;
    siteName?: string;
    url?: string;
    image?: string;
    lang?: string;
  };
  tokens: number;         // Approximate token count
  chars: number;          // Character count
  contextUsage: {         // % of context window used
    'gpt-4o': number;
    'claude-4': number;
    'gemini-2.5': number;
  };
}
```
Tokens:
Raw