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
• API
  • parse
  • flatParse
  • customParse
  • stringify
  • flatStringify
  • merge
• Attribute Handling
• 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.

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"
        }
      ]
    }
  ]
}

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.
withId	boolean	Adds hierarchical identifiers id and pid to each item.

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"
      }
    ]
  }
]

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.
withId	boolean	Adds incremental numeric id to items.

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 = {
  addBookmark,
  describeBookmark,
  openFolder,
  closeFolder
}

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 item IDs.

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 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.

CLI

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

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

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.