nbff-parser

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

Parses NBFF into structured data (with customizable formats), serializes structured data to NBFF, and merges multiple NBFF files.

Features

• Small. From 280 B (minified + Brotli compressed), with no dependencies.
• Modern. ES modules and tree shaking support.
• TypeScript-ready. Full type definitions included.

Contents

• Install
• API
  • parse
  • flatParse
  • customParse
  • stringify
  • flatStringify
  • merge
• CLI
  • exclude
  • merge
• Acknowledgments

Install

# npm
npm install nbff-parser

# pnpm
pnpm add nbff-parser

# yarn
yarn add nbff-parser

API

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

Returns bookmark attributes with lowercase names and normalized values. See definition.

parse

Type definition

Parses bookmarks into a nested tree structure.

import { parse } from 'nbff-parser'

const bookmarks = parse(html)

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

Options:

| Option | Type | Description | | -------------- | -------------------- | ---------------------------------------------------------- | | excludeAttrs | AllAttrKeys[] | Excludes specified attributes from output. | | withId | boolean | Adds hierarchical identifiers id and pid to each item. | | transform | (x: Bookmark) => T | Transforms bookmarks, omitting falsy returns. | | noEmpty | boolean | Skips empty folders in the result. |

flatParse

Type definition

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

import { flatParse } from 'nbff-parser'

const bookmarks = flatParse(html)

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

Options:

| Option | Type | Description | | -------------- | ------------------------ | --------------------------------------------- | | excludeAttrs | AllAttrKeys[] | Excludes specified attributes from output. | | withId | boolean | Adds incremental numeric id to items. | | transform | (x: FlatBookmark) => T | Transforms bookmarks, omitting falsy returns. |

customParse

Type definition

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.

import { customParse } from 'nbff-parser'

const handlers = {
  openFolder, // <H1>, <H3>
  addBookmark, // <A>
  describeBookmark, // <DD>
  closeFolder // </DL>
}

const bookmarks = customParse(html, handlers)

stringify

Type definition

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

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

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

flatStringify

Type definition

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

It requires using flatParse with { withId: true } to ensure unique items.

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

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

merge

Type definition

Merges parsed files into a single HTML string.

import { merge } from 'nbff-parser'

const merged = merge(html1, html2, ...)

CLI

CLI methods work with actual files.

Usage:

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 |

Example:

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:

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

Acknowledgments

• Netscape Bookmark File Format Wiki for the collected info about NBFF.