Supermarkdown

https://supermarkdown.dev/docs
Admin
Supermarkdown is a fast, Rust-powered HTML to Markdown converter with full GFM support, available as...
Tokens:5,943
Snippets:83
Trust Score:2.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install supermarkdown-cli with cargo install

Source: https://supermarkdown.dev/docs/rust

Install the supermarkdown command-line tool via cargo install.

```bash
cargo install supermarkdown-cli

```

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

### Install supermarkdown with npm, yarn, or pnpm

Source: https://supermarkdown.dev/docs/getting-started

Install the package using your preferred package manager. Choose one of the three commands.

```bash
# npm
npm install @vakra-dev/supermarkdown

# yarn
yarn add @vakra-dev/supermarkdown

# pnpm
pnpm add @vakra-dev/supermarkdown
```

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

### Ordered List Start: HTML to Markdown

Source: https://supermarkdown.dev/docs/edge-cases

Demonstrates how the start attribute of an ordered list is preserved in the Markdown output. The HTML list starts at 5, and the Markdown output uses 5. and 6. to reflect the starting number.

```html
<ol start="5">
  <li>Five</li>
  <li>Six</li>
</ol>

```

```markdown
5. Five
6. Six

```

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

### Use supermarkdown CLI to convert files and stdin

Source: https://supermarkdown.dev/docs/rust

CLI usage examples: convert a file to Markdown, convert stdin, and use the --heading-style option. The comments explain each command.

```bash
# Convert file
supermarkdown input.html > output.md

# Convert stdin
cat page.html | supermarkdown

# With options
supermarkdown --heading-style setext input.html

```

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

### convert() usage example

Source: https://supermarkdown.dev/docs/api

Example usage of convert() with a simple HTML string. The output is shown in the comment as "# Hello\n\nWorld".

```typescript
import { convert } from '@vakra-dev/supermarkdown';

const markdown = convert('<h1>Hello</h1><p>World</p>');
// => "# Hello\n\nWorld"

```

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

### Convert HTML with options using convert_with_options

Source: https://supermarkdown.dev/docs/rust

Convert HTML to Markdown with custom options using convert_with_options. The example sets heading style to Setext, link style to Referenced, and bullet marker to '*'. The options are passed by reference.

```rust
use supermarkdown::{convert_with_options, Options, HeadingStyle, LinkStyle};

fn main() {
    let html = "<h1>Title</h1><p>Content</p>";

    let options = Options::new()
        .heading_style(HeadingStyle::Setext)
        .link_style(LinkStyle::Referenced)
        .bullet_marker('*');

    let markdown = convert_with_options(html, &options);

    println!("{}", markdown);
}

```

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

### baseUrl: Resolving relative links

Source: https://supermarkdown.dev/docs/options

Shows how to set baseUrl to resolve relative links. The example converts an anchor with a relative href and outputs an absolute link.

```javascript
convert('<a href="/page">Link</a>', {
  baseUrl: 'https://example.com'
});
// => [Link](https://example.com/page)

```

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

### convertAsync() usage example with excludeSelectors

Source: https://supermarkdown.dev/docs/api

Example usage of convertAsync() with an options object that excludes script, style, and nav elements. Useful for large documents to avoid blocking the main thread.

```typescript
import { convertAsync } from '@vakra-dev/supermarkdown';

const markdown = await convertAsync(largeHtmlDocument, {
  excludeSelectors: ['script', 'style', 'nav'],
});

```

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

### Build Options with heading, link, code fence, bullet, base URL, and selectors

Source: https://supermarkdown.dev/docs/rust

Build an Options instance with various settings: heading style, link style, code fence character, bullet marker, base URL, and CSS selectors to exclude or include. Comments show alternative values for each option.

```rust
use supermarkdown::Options;

let options = Options::new()
    .heading_style(HeadingStyle::Atx)      // or Setext
    .link_style(LinkStyle::Inline)          // or Referenced
    .code_fence('`')                        // or '~'
    .bullet_marker('-')                     // or '*' or '+'
    .base_url(Some("https://example.com".to_string()))
    .exclude_selectors(vec!["nav".to_string(), ".ads".to_string()])
    .include_selectors(vec![".content".to_string()]);

```

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

### convert()

Source: https://supermarkdown.dev/docs/api

Synchronous HTML to Markdown conversion. Takes an HTML string and optional ConvertOptions, returns the converted Markdown string.

```APIDOC
## convert()

### Description
Synchronous HTML to Markdown conversion.

### Method
function

### Endpoint
convert(html: string, options?: ConvertOptions): string

### Parameters
#### Path Parameters
- **html** (string) - Required - The HTML string to convert
- **options** (ConvertOptions) - Optional - Optional configuration

### Request Example
```typescript
import { convert } from '@vakra-dev/supermarkdown';

const markdown = convert('<h1>Hello</h1><p>World</p>');
// => "# Hello\n\nWorld"
```

### Response
#### Success Response
- **Returns** (string) - The converted Markdown

#### Response Example
```typescript
"# Hello\n\nWorld"
```
```

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

### ConvertOptions

Source: https://supermarkdown.dev/docs/api

Configuration options for conversion. Defines the interface for optional settings that can be passed to convert() and convertAsync().

```APIDOC
## ConvertOptions

### Description
Configuration options for conversion.

### Method
interface

### Endpoint
ConvertOptions

### Parameters
#### Path Parameters
- **headingStyle** ('atx' | 'setext') - Optional - Heading style
- **linkStyle** ('inline' | 'referenced') - Optional - Link style
- **codeFence** ('`' | '~') - Optional - Code fence style
- **bulletMarker** ('-' | '*' | '+') - Optional - Bullet marker
- **baseUrl** (string) - Optional - Base URL for relative links
- **excludeSelectors** (string[]) - Optional - Selectors to exclude from conversion
- **includeSelectors** (string[]) - Optional - Selectors to include in conversion

### Request Example
```typescript
interface ConvertOptions {
  headingStyle?: 'atx' | 'setext';
  linkStyle?: 'inline' | 'referenced';
  codeFence?: '`' | '~';
  bulletMarker?: '-' | '*' | '+';
  baseUrl?: string;
  excludeSelectors?: string[];
  includeSelectors?: string[];
}
```

### Response
#### Success Response
- **Returns** (ConvertOptions) - The configuration object

#### Response Example
```typescript
{
  headingStyle: 'atx',
  linkStyle: 'inline',
  codeFence: '`',
  bulletMarker: '-',
  baseUrl: 'https://example.com',
  excludeSelectors: ['script', 'style'],
  includeSelectors: ['main']
}
```
```

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

### headingStyle: ATX style (default)

Source: https://supermarkdown.dev/docs/options

Shows the default ATX heading style with # for h1, ## for h2, and ### for h3.

```markdown
# Heading 1
## Heading 2
### Heading 3

```

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

### codeFence: Tildes

Source: https://supermarkdown.dev/docs/options

Shows the code fence using tildes.

```markdown
~~~javascript
const x = 1;
~~~

```

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

### convertAsync()

Source: https://supermarkdown.dev/docs/api

Asynchronous conversion for large documents. Useful when you don't want to block the main thread. Takes an HTML string and optional ConvertOptions, returns a Promise that resolves to the converted Markdown string.

```APIDOC
## convertAsync()

### Description
Asynchronous conversion for large documents. Useful when you don't want to block the main thread.

### Method
function

### Endpoint
convertAsync(html: string, options?: ConvertOptions): Promise<string>

### Parameters
#### Path Parameters
- **html** (string) - Required - The HTML string to convert
- **options** (ConvertOptions) - Optional - Optional configuration

### Request Example
```typescript
import { convertAsync } from '@vakra-dev/supermarkdown';

const markdown = await convertAsync(largeHtmlDocument, {
  excludeSelectors: ['script', 'style', 'nav'],
});
```

### Response
#### Success Response
- **Returns** (Promise<string>) - The converted Markdown

#### Response Example
```typescript
"# Hello\n\nWorld"
```
```

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

### linkStyle: Inline style (default)

Source: https://supermarkdown.dev/docs/options

Shows the default inline link style with the URL in parentheses.

```markdown
Check out [this link](https://example.com) for more.

```

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

### Basic usage of convert function

Source: https://supermarkdown.dev/docs/getting-started

Imports the convert function and converts an HTML string to Markdown. The output is logged to the console.

```javascript
import { convert } from '@vakra-dev/supermarkdown';

const html = '<h1>Hello World</h1><p>This is a <strong>test</strong>.</p>';
const markdown = convert(html);

console.log(markdown);
// # Hello World
//
// This is a **test**.
```

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

### codeFence: Backticks (default)

Source: https://supermarkdown.dev/docs/options

Shows the default code fence using backticks.

```markdown
javascript
const x = 1;


```

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

### Customize conversion with options

Source: https://supermarkdown.dev/docs/getting-started

Passes an options object to the convert function to customize heading style, link style, and bullet marker.

```javascript
import { convert } from '@vakra-dev/supermarkdown';

const markdown = convert(html, {
  headingStyle: 'setext',
  linkStyle: 'referenced',
  bulletMarker: '*',
});
```

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

### TypeScript usage with ConvertOptions

Source: https://supermarkdown.dev/docs

Use TypeScript with the ConvertOptions type to configure conversion, including excluding selectors like nav and .sidebar.

```typescript
import { convert, ConvertOptions } from '@vakra-dev/supermarkdown';

const options: ConvertOptions = {
  headingStyle: 'atx',
  excludeSelectors: ['nav', '.sidebar'],
};

const markdown = convert(html, options);

```

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

### Add supermarkdown dependency to Cargo.toml

Source: https://supermarkdown.dev/docs/rust

Add the supermarkdown crate to your Cargo.toml dependencies to use it in a Rust project.

```toml
[dependencies]
supermarkdown = "0.0.5"

```

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

### headingStyle: Setext style

Source: https://supermarkdown.dev/docs/options

Shows the Setext heading style using underlines for h1 and h2. Deeper headings fall back to ATX.

```markdown
Heading 1
=========

Heading 2
---------

```

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

### includeSelectors: Force-include elements

Source: https://supermarkdown.dev/docs/options

Shows how to force-include elements that would otherwise be excluded by excludeSelectors.

```javascript
convert(html, {
  excludeSelectors: ['.sidebar'],
  includeSelectors: ['.sidebar .important']
});

```

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

### linkStyle: Referenced style

Source: https://supermarkdown.dev/docs/options

Shows the referenced link style using a reference definition at the bottom.

```markdown
Check out [this link][1] for more.

[1]: https://example.com

```

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

### bulletMarker: dash, asterisk, plus

Source: https://supermarkdown.dev/docs/options

Shows the three bullet marker options: dash (default), asterisk, and plus.

```markdown
- Item with dash (default)
* Item with asterisk
+ Item with plus

```

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

### convert() function signature

Source: https://supermarkdown.dev/docs/api

Signature for the synchronous HTML to Markdown conversion function. Takes an HTML string and optional ConvertOptions, returning the converted Markdown string.

```typescript
function convert(html: string, options?: ConvertOptions): string

```

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

### TypeScript usage with ConvertOptions

Source: https://supermarkdown.dev/docs/getting-started

Uses the ConvertOptions type to define options with headingStyle and excludeSelectors, then passes them to convert.

```typescript
import { convert, ConvertOptions } from '@vakra-dev/supermarkdown';

const options: ConvertOptions = {
  headingStyle: 'atx',
  excludeSelectors: ['nav', '.sidebar'],
};

const markdown = convert(html, options);
```

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

### Convert HTML to Markdown with supermarkdown::convert

Source: https://supermarkdown.dev/docs/rust

Convert a simple HTML string to Markdown using the convert function. The output is printed to stdout and shows the expected Markdown result.

```rust
use supermarkdown::convert;

fn main() {
    let html = "<h1>Hello</h1><p>World</p>";
    let markdown = convert(html);

    println!("{}", markdown);
    // # Hello
    //
    // World
}

```

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

### convertAsync() function signature

Source: https://supermarkdown.dev/docs/api

Signature for the asynchronous conversion function. Returns a Promise that resolves to the converted Markdown string.

```typescript
function convertAsync(html: string, options?: ConvertOptions): Promise<string>

```

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

### HTML table with alignment converts to GFM Markdown table

Source: https://supermarkdown.dev/docs/elements

Shows an HTML table with aligned columns and its GFM Markdown conversion. The HTML uses the align attribute on th elements; the Markdown output preserves alignment with colons in the separator row. Pipes in cells are escaped and missing cells are padded.

```html
<table>
  <thead>
    <tr>
      <th align="left">Left</th>
      <th align="center">Center</th>
      <th align="right">Right</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>A</td>
      <td>B</td>
      <td>C</td>
    </tr>
  </tbody>
</table>

```

```markdown
| Left | Center | Right |
|:-----|:------:|------:|
| A    | B      | C     |

```

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

### excludeSelectors: Excluding elements

Source: https://supermarkdown.dev/docs/options

Shows how to exclude elements from conversion using CSS selectors.

```javascript
convert(html, {
  excludeSelectors: ['nav', '.sidebar', '#ads', 'script', 'style']
});

```

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

### Backticks in Code: HTML to Markdown

Source: https://supermarkdown.dev/docs/edge-cases

Illustrates how backticks inside code are handled by using more backticks for the code fence. The HTML code element contains backticks, and the Markdown output uses triple backticks to wrap the code.

```html
<code>Use `template` literals</code>

```

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

### Nested Lists: HTML to Markdown

Source: https://supermarkdown.dev/docs/edge-cases

Shows how deeply nested lists are converted to Markdown. The HTML contains a nested unordered list inside a list item, and the Markdown output preserves the nesting structure.

```html
<ul>
  <li>Item
    <ul>
      <li>Nested
        <ol>
          <li>Deep</li>
        </ol>
      </li>
    </ul>
  </li>
</ul>

```

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

### Special Characters in URLs: HTML to Markdown

Source: https://supermarkdown.dev/docs/edge-cases

Demonstrates how URLs with spaces are percent-encoded in the Markdown output. The HTML href contains spaces, and the Markdown link uses %20 for spaces.

```html
<a href="https://example.com/path with spaces">Link</a>

```

```markdown
[Link](https://example.com/path%20with%20spaces)

```

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

### ConvertOptions interface definition

Source: https://supermarkdown.dev/docs/api

Definition of the ConvertOptions interface. All properties are optional and control various aspects of the conversion, such as heading style, link style, code fence character, bullet marker, base URL, and selectors to exclude or include.

```typescript
interface ConvertOptions {
  headingStyle?: 'atx' | 'setext';
  linkStyle?: 'inline' | 'referenced';
  codeFence?: '`' | '~';
  bulletMarker?: '-' | '*' | '+';
  baseUrl?: string;
  excludeSelectors?: string[];
  includeSelectors?: string[];
}

```

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

### Empty href Link: HTML to Markdown

Source: https://supermarkdown.dev/docs/edge-cases

Shows that links with an empty href attribute are converted to plain text. The HTML anchor has an empty href, and the Markdown output is just the link text without any link syntax.

```html
<a href="">Click here</a>

```

```markdown
Click here

```

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

### Autolink Email: HTML to Markdown

Source: https://supermarkdown.dev/docs/edge-cases

Shows how email addresses in links can become autolinks. The HTML anchor with a mailto: href is converted to a Markdown autolink using angle brackets.

```html
<a href="mailto:test@example.com">test@example.com</a>

```

```markdown
<test@example.com>

```

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

### Character Escaping: HTML to Markdown

Source: https://supermarkdown.dev/docs/edge-cases

Shows how special Markdown characters like asterisks and brackets are escaped in text. The HTML input contains literal asterisks and brackets, and the Markdown output escapes them with backslashes to prevent formatting.

```html
<p>5 * 3 = 15</p>
<p>See [section A] for details.</p>

```

```markdown
5 \* 3 = 15

See \[section A\] for details.

```
Tokens:
Raw