nbff-parser/readme.md

A simple parser for the Netscape Bookmark file format

# nbff-parser

A simple parser for the Netscape Bookmark File Format (NBFF), commonly generated by browsers when exporting bookmarks.

It supports parsing bookmarks into various formats — including customizable structures — and converting the parsed data back into an HTML string.

Additionally, the parser can merge the contents of multiple bookmark files into a single, unified string.

## Features

- **Small**. Between 260 B and 2 kB (minified + Brotli compressed), with no dependencies.
- **Modern**. Supports ES modules and tree shaking.
- **TypeScript-ready**. Full type definitions included.

## Contents

- [Install](#install)
- [API](#api)
  - [parse](#parse)
  - [flatParse](#flatParse)
  - [customParse](#customParse)
  - [stringify](#stringify)
  - [flatStringify](#flatStringify)
  - [merge](#merge)
- [Attribute Handling](#attribute-handling)
- [CLI](#cli)
  - [exclude](#exclude)
  - [merge](#merge)
- [Acknowledgments](#acknowledgments)

## Install

```sh
npm i nbff-parser
```

## API

The parser expects HTML file content to be provided as a string.

### `parse`

[Type definition](./types/parse/parse.d.ts)

Parses bookmarks into a nested tree structure.

```js
import { parse } from 'nbff-parser'

const bookmarks = parse(html)
```

<details>
<summary>Result schema</summary>

```json
{
  "title": "Folder",
  "items": [
    {
      "title": "Bookmark"
    },
    {
      "title": "Nested Folder",
      "items": [
        {
          "title": "Another Bookmark"
        }
      ]
    }
  ]
}
```

</details>

<br/>

You can configure the output by activating options passed as the second argument.

| Option         | Type       | Description                                                                                 |
| -------------- | ---------- | ------------------------------------------------------------------------------------------- |
| `excludeAttrs` | `string[]` | Excludes specified attributes from output. See [attributes definition](./types/attrs.d.ts). |
| `withId`       | `boolean`  | Adds hierarchical identifiers `id` and `pid` to each item.                                  |

### `flatParse`

[Type definition](./types/parse/flat-parse.d.ts)

Parses bookmarks into a flat list, where each bookmark includes a folder stack representing its location path. Empty folders are omitted.

```js
import { flatParse } from 'nbff-parser'

const bookmarks = flatParse(html)
```

<details>
<summary>Result schema</summary>

```json
[
  {
    "title": "Bookmark",
    "folder": [
      {
        "title": "Folder"
      }
    ]
  },
  {
    "title": "Another Bookmark",
    "folder": [
      {
        "title": "Folder"
      },
      {
        "title": "Nested Folder"
      }
    ]
  }
]
```

</details>

<br/>

You can configure the output by activating options passed as the second argument.

| Option         | Type       | Description                                                                                 |
| -------------- | ---------- | ------------------------------------------------------------------------------------------- |
| `excludeAttrs` | `string[]` | Excludes specified attributes from output. See [attributes definition](./types/attrs.d.ts). |
| `withId`       | `boolean`  | Adds incremental numeric `id` to items.                                                     |

### `customParse`

[Type definition](./types/parse/custom-parse.d.ts)

Allows you to define handlers for elements during parsing.

Use this to build custom data structures or implement custom logic.

The methods described above rely on it internally.

```js
import { customParse } from 'nbff-parser'

const handlers = {
  addBookmark,
  describeBookmark,
  openFolder,
  closeFolder
}

const bookmarks = customParse(html, handlers)
```

### `stringify`

[Type definition](./types/stringify/stringify.d.ts)

Converts the parsed tree structure from `parse` back into an HTML string.

```js
import { parse, stringify } from 'nbff-parser'

const parsed = parse(html)
const stringified = stringify(parsed)
// `stringified` matches the original `html`
```

### `flatStringify`

[Type definition](./types/stringify/flat-stringify.d.ts)

Converts the flat list from `flatParse` back into an HTML string.

> It requires using `flatParse` with `{ withId: true }` to ensure unique item IDs.

```js
import { flatParse, flatStringify } from 'nbff-parser'

const parsed = flatParse(html, { withId: true })
const stringified = flatStringify(parsed)
// `stringified` matches the original `html`
```

### `merge`

[Type definition](./types/merge/merge.d.ts)

Merges the contents of multiple HTML files into a single HTML string.

## Attribute Handling

- Attribute names are returned lowercased.
- Attribute values may be slightly normalized.
- See detailed attribute types [here](./types/attrs.d.ts).

## CLI

Usage:

```sh
npx nbff-parser <command> [options]
```

### `exclude`

Removes specified attributes from the HTML file.

| Argument                | Description                                          | Status   |
| ----------------------- | ---------------------------------------------------- | -------- |
| `file=path/to/file`     | Path to the input HTML file                          | Required |
| `attrs=attr1,attr2,...` | Comma-separated list of attributes to exclude        | Required |
| `output=path/to/output` | Path to save the output file; defaults to input file | Optional |

If `output` is not provided, the changes will overwrite the original file.

Example:

```sh
npx nbff-parser exclude \
  file=index.html \
  attrs=add_date,icon \
  output=cleaned.html
```

### `merge`

Merges multiple files into a single output file.

| Arguments                | Description                                       | Status   |
| ------------------------ | ------------------------------------------------- | -------- |
| `files=path/to/file,...` | Comma-separated list of input file paths to merge | Required |
| `output=path/to/output ` | Path to save the merged output file               | Required |

Example:

```sh
npx nbff-parser merge \
  files=foo.html,bar.html \
  output=merged.html
```

## Acknowledgments

- [Netscape Bookmark File Format Wiki](https://github.com/FlyingWolFox/Netscape-Bookmarks-File-Parser/wiki/Netscape-Bookmarks-File-Format) for the collected info about NBFF.