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)

Result schema

{
  "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)

Result schema

[
  {
    "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.