Docs first, as CLAUDE.md requires; the code follows in this branch. - 08: the manifest per target (two packages from one source, MV3 for both); Firefox's gecko id, data-collection declaration, floor 140 and source-code submission; Edge takes the Chrome package unchanged. - 02 §4, 03 §1/§3, 04, 05 §10: Firefox's GUID roots and fourth root, the Bookmarks Menu (`root: "menu"`, unmarked entries routed into it on Firefox); separators recognised by type, kept out of the file model and shown as untouchable lines in #edit; the move index sent by each browser's own rule and checked against the reply; addresses Firefox refuses dropped before planning; separators a file holds counted. - 06/07: the About link follows the install; three strings that blamed Chrome for what every browser does are reworded; new keys listed. - 11: a Firefox flavour of the fake, and a manual pass on real Firefox and Edge (including Edge signed in with sync) before the first submissions. - 12/13: three store jobs, each in its own environment with only its own secrets and a four-package install; CWS API v2 (v1.1 died 2026-10-15); AMO and Edge runbooks for the first, manual uploads. - 09/14 and legal/: three stores named; a clarification, not a LEGAL_VERSION bump. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
23 KiB
04 — File Formats
Six formats. HTML is the interoperability workhorse; BM JSON is our lossless
round-trip format; CSV is for spreadsheets; Markdown is share/export-only; and
since v1.1.0 two browser files are read directly — Chrome's profile Bookmarks
file and Firefox's JSON backup.
| Format | Import | Export | Lossless | Purpose |
|---|---|---|---|---|
| Netscape HTML | ✔ | ✔ | structure+dates | Universal browser exchange (Chrome, Edge, Brave, Firefox, Safari, Vivaldi, Opera all read/write it) |
| BM JSON v1 | ✔ | ✔ | ✔ | Backups, round-trip, safety backup before Replace |
Chrome Bookmarks (§2a) |
✔ | ✖ | structure+dates | The profile file itself — the copy left when the browser no longer starts; keeps Other and Mobile |
| Firefox JSON backup (§2b) | ✔ | ✖ | structure+dates | bookmarks-YYYY-MM-DD.json from Library → Backup…; keeps Mobile, which Firefox's HTML export drops |
| CSV (RFC 4180) | ✔ | ✔ | flattened | Spreadsheet review/editing |
| Markdown | ✖ | ✔ | — | Human-readable sharing (blog posts, Discord, README) |
Sniffing (detect-format.ts, called only through parse-file.ts's
parseBookmarkFile) reads content and never the extension — Chrome's file has
none — after stripping a BOM:
- Text whose first non-blank character is
{or[is JSON. It is parsed exactly once and routed by shape:format: "bookmarkmagic"→ BM JSON; an objectrootsholdingbookmark_bar,otherorsynced→ Chrome;type: "text/x-moz-place-container"(orroot: "placesRoot") with achildrenarray → Firefox. Valid JSON matching none →NOT_BM_JSON(meaning, since v1.1.0, "JSON, but no bookmark file we know"); invalid JSON →MALFORMED_JSON. JSON is tested first so a title quoting the doctype can never make a JSON file look like HTML. <!DOCTYPE NETSCAPE-Bookmark-file-1(case-insensitive) as the first thing in the file after whitespace and comments → HTML. Anchored since v1.1.0: the old probe accepted the marker anywhere in the first 512 bytes, including inside a CSV title.- The §3 header row → CSV.
- Any
<DL→ HTML (the parser decides whether it is usable); elseUNKNOWN_FORMAT.
The file picker has no accept filter for the same reason: a filter on
.html,.json,.csv hid Chrome's Bookmarks file.
1. Netscape Bookmark HTML
De-facto standard since Netscape Navigator; intentionally not well-formed
HTML. DOMParser('text/html') normalizes it fine.
1.1 Emitted skeleton (export)
<!DOCTYPE NETSCAPE-Bookmark-file-1>
<!-- This is an automatically generated file. It will be read and overwritten. DO NOT EDIT! -->
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
<TITLE>Bookmarks</TITLE>
<H1>Bookmarks</H1>
<DL><p>
<DT><H3 ADD_DATE="1751500000" LAST_MODIFIED="1751500000" PERSONAL_TOOLBAR_FOLDER="true">Bookmarks bar</H3>
<DL><p>
<DT><A HREF="https://example.com/" ADD_DATE="1751500000">Example</A>
<DT><H3 ADD_DATE="1751500000">Dev tools</H3>
<DL><p>
<DT><A HREF="https://github.com/" ADD_DATE="1751500000">GitHub</A>
</DL><p>
</DL><p>
</DL><p>
Export rules: 4-space indent per depth (matches Chrome), attributes only when
values exist, one root marker on each folder that stands for a browser root
(below), HTML-escape & < > " in titles and hrefs — and \r as . The last
one is not a markup hazard but a round-trip one: the HTML tokenizer normalizes
CR and CRLF to LF during input-stream preprocessing, so an unescaped \r in a
title comes back as \n. A numeric reference survives, because character
references are decoded after that normalization. \r reaches us from BM JSON
and from quoted CSV fields, so this is reachable, not theoretical.
Root markers (since v1.1.0). Our own export and the Replace safety backup
write the browser roots as top-level folders; without a marker, re-importing
them nested a folder named "Other bookmarks" inside Other Bookmarks, one more
level on every restore (03 §1). Exactly one attribute per folder, the toolbar
winning:
| Root | Attribute | Who reads it |
|---|---|---|
| Bookmarks Bar | PERSONAL_TOOLBAR_FOLDER="true" |
every browser |
| Other Bookmarks | UNFILED_BOOKMARKS_FOLDER="true" |
Firefox (its own exporter writes it), and us |
| Mobile Bookmarks | MOBILE_BOOKMARKS_FOLDER="true" |
us — importers ignore attributes they do not know |
| Bookmarks Menu (Firefox) | none — its contents are written loose at the top level | every browser, the way Firefox's own exporter writes it (since v1.3.0) |
The Bookmarks Menu has no attribute of its own in Firefox's format: Firefox
exports the menu's entries as the file's top level and imports loose
top-level entries back into the menu. A BM JSON root: "menu" folder (§2)
is therefore written to HTML by unwrapping it — its children appear at the
top level, before the marked roots — and reading that file in Firefox puts
them back where they were (03 §1). Chromium has no menu root, so in Chrome
or Edge those entries land in Other Bookmarks, as they do from Firefox's own
export.
1.2 Parse tolerance (import)
Must accept, with a warning where noted:
-
Missing
</DT>/ stray<p>(normal for the format). -
<DD>description lines → warning: descriptions dropped (not in our model). ⚠️ A<DD>also changes the tree shape, so this is not merely a dropped string: a<DD>start tag closes the open<DT>, and a<DL>following it nests inside the<DD>— neither inside the<DT>nor as the<DT>'s next sibling. A naivenextDlForfinds nothing and silently drops the entire folder subtree. The walk must also look inside (and after) a<DD>next-sibling — see05 §1. Fixture:weird/folder-with-dd.html. -
ICON="data:image/png;base64,…"→ base64 favicon; written by Firefox and Chrome, and read by Chrome's native File ▸ Import.ICON_URI→ remote favicon URL; written by Firefox, ignored by Chrome. Both are parsed past and dropped, with a single aggregated warning: "N favicons ignored — thechrome.bookmarksAPI cannot set favicons." (Note the precise claim: Chrome's own importer can do this; the extension API exposes no favicon field, so we cannot.) -
Unknown attributes ignored silently —
SHORTCUTURL,TAGS,LAST_CHARSET,POST_DATA,FOLDED(Safari),LAST_VISIT, and the IE-eraFEED/FEEDURL/WEBSLICE/ISLIVEPREVIEW/PREVIEWSIZE. -
The three root markers (§1.1) are read by value: present and not
false/0/no. Firefox writesUNFILED_BOOKMARKS_FOLDER="false"on folders that are not Other Bookmarks, and v1.0.x readPERSONAL_TOOLBAR_FOLDERby presence alone, so a="false"made a folder the bar. -
Addresses (since v1.1.0,
05 §1): blank → skipped,MISSING_URL; not parseable (URL.canParsefalse — e.g.www.example.comwith no scheme, a space in the host) → skipped,INVALID_URL, becausechrome.bookmarks.createrejects it mid-write, after a Replace has already cleared the tree; Firefoxplace:smart bookmarks → skipped,PLACE_QUERIES_SKIPPED(Chrome's own importer drops them too; in Chrome they are dead links, and on Firefox BookmarkMagic still does not write them — the notice says "skipped", not "dead", since v1.3.0). On Firefox, an address longer than 65 536 characters → skipped before planning,URL_TOO_LONG(applied after parsing, with the limit the browser layer passes in, so every format is covered by one rule).javascript:,data:andfile:addresses are kept verbatim (09T3). Fixture:weird/invalid-urls.html. -
Empty titles are kept empty (since v1.1.0), counted as
EMPTY_TITLE. They used to become the address, which turned a favicon-only Bookmarks Bar into a row of URLs after one export/import cycle; Chrome shows the address itself wherever it needs a title. -
A loose bookmark before a list. With no
</DT>, the HTML parser nests a following<DL>inside a bookmark's<DT>; that list is read at the same depth, after the bookmark. With an explicit</DT>, only a folder<DT>consumes the next body-level list. v1.0.x dropped the list in both shapes. Fixture:weird/loose-first.html. -
An unescaped formatting tag in a title (
C++ <b>tips</A>): the parser re-opens that<b>around every later entry (dt > b > a,dl > b > dt). Entries are found through such wrappers — a<DT>'s own<A>/<H3>/<DL>is any descendant whose nearest<DT>is that one. v1.0.x imported one bookmark from such a file. Fixture:weird/unclosed-format-tag.html. A<DT>that still yields nothing is counted asUNREADABLE_ENTRIES. -
An unescaped
<h3>inside a bookmark title (<A …>Intro <h3>Heading</h3></A>) is part of the title: a<DT>'s<H3>makes it a folder only when it is not inside that entry's own<A>. v1.1.0 before the review read it as an empty folder and dropped the address. -
A root list wrapped in
<div>/<center>/a table cell → found as an outermost<DL>when body-level collection finds nothing. -
Real Chrome output writes Other's and Mobile's contents loose at the top level, after the bar, with no folder line (
bookmark_html_writer.cc; fixturechrome-156-export.html, built to that writer byte for byte, CRLF included). The olderchrome-131-export.htmlwraps them in anOther bookmarksfolder that Chrome itself never writes; it is kept as a third-party shape, not as a record of Chrome. -
<HR>separator elements (Firefox) → skipped and counted,SEPARATORS_SKIPPED(no warning until v1.3.0; once Firefox users could import, a silent loss stopped being acceptable). These are elements, so "unknown attributes ignored" does not cover them. The file model has no separator: none of the four formats BookmarkMagic writes carries one. -
Empty folders → preserved.
-
Root list selection. Do not pick a single root
<DL>—document.querySelector('dl')and "the outermost<DL>" are both lossy. Safari has been reported (Mozilla bug 801450) to emit top-level<DT><H3>folders with no outer wrapper, and real files can mix the two: one wrapped root list followed by loose<DT>s. Either single-root rule silently drops whichever half it did not pick, with no warning.Instead walk
<body>'s children in document order and accept both kinds of entry point — a<DT>is read as a root entry, a<DL>is walked as a root list. One caveat: when a file emits an explicit</DT>, a folder's child<DL>also lands at body level, so compute each body-level<DT>'s child list first and skip any<DL>already consumed that way, or the whole subtree is emitted twice. Algorithm in05 §1. ⚠️ The exact Safari shape is still unverified against a real export (00 §10).
Hard failures only: no NETSCAPE-Bookmark-file-1 doctype and no <DL>
found; or node/size/depth caps exceeded (TOO_MANY_NODES, FILE_TOO_LARGE,
TOO_DEEP). The node cap is checked on the raw text (a count of <DT tags)
before DOMParser runs, so a 25 MB file of 1.7 million entries is refused
without building its DOM (09 T2). The depth cap applies to entries: an empty
list one level past it is harmless. A file with a valid doctype and zero <DL> is not a failure —
it yields an empty ParseResult with a NO_BOOKMARKS warning (05 §1).
1.3 Timestamps
ADD_DATE / LAST_MODIFIED are epoch seconds in every browser that writes
Netscape HTML — including Firefox, whose exporter divides PRTime by
MICROSEC_PER_SEC before writing. Normalize via timestamps.ts magnitude
detection (05 §4), which also tolerates ms/µs values from non-browser
exporters. Invalid → omit + warning.
Note the asymmetry the model has to absorb: chrome.bookmarks returns
dateAdded in milliseconds, while this file format and our BookmarkNode
both use seconds. 05 §4's magnitude table converts either correctly.
Chrome writes ADD_DATE="0" for nodes with no recorded date — that is normal,
not an anomaly, and must not raise a warning (05 §4).
2. BM JSON v1 (our schema — "BM" = BookmarkMagic)
{
"format": "bookmarkmagic",
"version": 1,
"generator": "BookmarkMagic 1.0.0",
"exportedAt": "2026-07-03T07:05:00Z",
"roots": [
{
"title": "Bookmarks bar",
"toolbar": true,
"addDate": 1751500000,
"children": [
{ "title": "Example", "url": "https://example.com/", "addDate": 1751500000 }
]
}
]
}
roots= array ofBookmarkNode(see02_ARCHITECTURE.md §4). Folders may omitchildren(⇒ empty). Unknown extra keys are ignored on import (forward compatibility);version > 1→ warning "newer file, best-effort"; an absentversionis read as 1."root": "other" | "mobile" | "menu"(since v1.1.0;"menu", Firefox's Bookmarks Menu, since v1.3.0; folders only, never beside"toolbar") marks a folder that IS that browser root — the JSON form of §1.1's markers. Additive: v1 readers ignore unknown keys, so the version stays 1, and a 1.0.x reader simply nests as before.- Legacy backups. A 1.0.x safety backup has exactly the shape of a Chromium
profile —
generatorBookmarkMagic 1.0.x, norootkeys, three top-level folders, the firsttoolbar— so it is recognised and marked on read ([1]other,[2]mobile). Fixture:weird/bm-legacy-1.0.1-backup.json. Known limit: a 1.0.x "Everything" export (not a backup) from a profile with policy-managed bookmarks and an empty, hidden Mobile root has the same shape with the managed folder third, which is then read as Mobile — its contents land in Mobile instead of a folder. Nothing is lost; the file's contents are all imported. - Addresses: blank or unparseable → skipped with
MISSING_URL/INVALID_URL(Chrome turnsurl: ""into a folder).place:is kept: this is the restore format, and a backup must bring back what the browser held. - Dates go through
timestamps.tslike every other format, so milliseconds and numeric strings are read and nonsense (1e300) is flagged, not stored. - The safety backup is written compact (
indent: 0, roughly half the bytes): it must stay under the 25 MB import cap to be restorable at all (03 §1step 6b). Exports stay indented. - Validation is hand-rolled structural checking in
parse/bm-json.ts(no schema library — zero-dep rule). Every node:titlestring required;urlif present must be string;childrenonly on folders. - Chrome's profile
Bookmarksfile and Firefox.jsonbackups are separate dialects with their own sections (§2a, §2b).
2a. Chrome profile Bookmarks file (import only, since v1.1.0)
The JSON file Chromium keeps in the profile folder — User Data/Default/Bookmarks
on Windows, ~/Library/Application Support/Google/Chrome/Default/Bookmarks on
macOS, ~/.config/google-chrome/Default/Bookmarks on Linux — with no
extension. Edge, Brave, Vivaldi and Opera keep the same file. Written by
BookmarkCodec, pretty-printed by base::JSONWriter (3-space indent, keys
sorted):
{
"checksum": "…",
"roots": {
"bookmark_bar": { "children": [ … ], "date_added": "13344473600000000",
"date_modified": "…", "guid": "…", "id": "1",
"name": "Bookmarks bar", "type": "folder" },
"other": { …, "name": "Other bookmarks", "type": "folder" },
"synced": { …, "name": "Mobile bookmarks", "type": "folder" }
},
"version": 1
}
- Nodes are
{ "type": "url", "name", "url", "date_added" }or{ "type": "folder", "name", "children", "date_added", "date_modified" }.id,guid,meta_info,date_last_used,show_icon,source,sync_metadataandchecksumare ignored. The checksum is never verified, so a hand-repaired file still imports. - Dates are decimal strings of microseconds since 1601-01-01 UTC. They are
past 2^53, so the conversion cuts the last six digits as a string before any
arithmetic, then subtracts 11 644 473 600 — truncating to the second, exactly
as Chrome's HTML writer (
ToTimeT) does."0"means unset. Run through §1.3's magnitude detection instead, such a value lands in the microsecond bucket and comes out near the year 2395 (timestamps.tschromeTimeToSeconds). - Roots. The bar is always emitted, as a
toolbarfolder, with the file's ownname; Other and Mobile are emitted asroot-marked folders only when they hold something. A blank root name falls back to the caller's localized title. Any other root key — Opera'scustom_root(Speed Dial, Trash, Unsorted), vendor additions — is skipped and its bookmarks counted asEXTRA_ROOTS_SKIPPED; old profiles also keep async_transaction_versionstring inroots, which is not a root and is ignored silently. - Addresses follow §1.2: blank →
MISSING_URL, unparseable →INVALID_URL,place:→PLACE_QUERIES_SKIPPED. A node of any othertype, or not an object at all →UNREADABLE_ENTRIES. Empty names are kept (EMPTY_TITLE). - Parity rule (the spec, tested against a Chromium-faithful pair,
chrome-156-Bookmarks+chrome-156-export.html): the tree read from the profile file equals the tree read from Chrome's own HTML export of it, once Other's and Mobile's contents are written loose at the top level, with no folder line — which is whatbookmark_html_writer.ccdoes. The JSON keeps what the HTML loses: which items were in Other and which in Mobile.
2b. Firefox JSON backup (import only, since v1.1.0)
bookmarks-YYYY-MM-DD.json, written by Library → Import and Backup → Backup…
(the automatic .jsonlz4 backups are compressed and are a separate, later
item — 15). One line of JSON.stringify output:
{"guid":"root________","title":"","type":"text/x-moz-place-container","root":"placesRoot","children":[
{"title":"menu","root":"bookmarksMenuFolder","type":"text/x-moz-place-container","children":[…]},
{"title":"toolbar","root":"toolbarFolder", …},
{"title":"tags","root":"tagsFolder", …},
{"title":"unfiled","root":"unfiledBookmarksFolder", …},
{"title":"mobile","root":"mobileFolder", …}]}
- Nodes:
typetext/x-moz-place(bookmark:title,uri),…-container(folder:title,children),…-separator(skipped and counted,SEPARATORS_SKIPPED, as<HR>is — so a backup and its HTML twin still give the same result, which the parity rule requires). A node with notypefalls back totypeCode1/2/3. Dates are PRTime — integer microseconds since the Unix epoch — converted explicitly and truncated, as Firefox's own HTML export does (microsToSeconds). - Roots, emitted in the order Firefox's HTML export writes them, whatever
the file order: the menu's contents loose at the top level; then the toolbar
as a
toolbarfolder and Other Bookmarks (unfiled) as aroot: "other"folder, each only when its rawchildrenlist is non-empty (a toolbar holding only a separator still yields an empty folder, matching the exporter); then Mobile as aroot: "mobile"folder — which Firefox's HTML export leaves out altogether. The tags root is dropped silently: it is a view over bookmarks the other roots already hold, and importing it would add every tagged bookmark twice. Any other root →EXTRA_ROOTS_SKIPPED. - Root titles. Firefox stores only the internal keys
toolbar,unfiled,mobile, and localizes them at display time. The caller passes localized titles (import.rootTitle.*,07); with none, the file's own key is used, never an English string fromcore/. iconUri(older files:iconuri) →FAVICONS_IGNORED; abookmarkProperties/descriptionanno →DESCRIPTIONS_DROPPED(counted where the HTML export would have written a<DD>);tags,keyword,charset,postData,guid,idandindexare ignored silently, like their HTML attributes. Addresses follow §1.2,place:included.- A container that is not the places root (a hand-made or third-party file) is read as a plain list: its children become the top-level entries.
- Parity rule, tested on
firefox-bookmarks-2026-07-25.jsonagainstfirefox-html-export.html: equal trees and warnings once the Mobile folder is removed.
3. CSV
Header row required, column order fixed:
folder_path,title,url,add_date
"Bookmarks bar/Dev tools","GitHub","https://github.com/","1751500000"
"","Example","https://example.com/","1751500000"
- Separator
/infolder_path; literal/inside a folder name escaped as\/(and\as\\). Empty path ⇒ top level. A single folder whose title is empty is written as a lone\— otherwise it is indistinguishable from "no path" and the folder dissolves on re-import. A lone\is unreachable from normal escaping (every literal\is doubled), so it is free to use. - RFC 4180: quote fields containing
, " \n; escape"as"". Accept both,and;delimiters on import (sniff header); export delimiter is a Settings option (default,). A quoted field that never closes isCSV_UNCLOSED_QUOTE, naming the line it opened on — it used to swallow the rest of the file into one cell. - Formula cells. A title or folder path starting with
= + - @, tab or CR (after any'guard quotes) is written with one extra leading', and the reader removes exactly one again — so=HYPERLINK(…)is never a live formula in Excel, and the round trip stays exact. - Import also skips blank, whitespace-only and padding (
,,,) rows, and a leading Excelsep=;line. Address rules as BM JSON (place:kept). - Rows are bookmarks only; folders are reconstructed from paths. CSV is a
flattened projection — the full list of what it does not preserve, shown
in the Export tab and asserted by the projected round-trip (
11 §3):- empty folders (no row can represent them);
lastModifiedon anything, andaddDateon folders (no columns);toolbar/ root identity — after a CSV parsetoolbaris alwaysundefined, so the first path segment is an ordinary folder title, never a root reference (consequence spelled out in03 §1);- sibling order across folders: folders materialise in row order, so two folders' relative position is whatever the row sequence implies;
- same-named sibling folders merge — two "New folder"s (Chrome's default name) come back as one holding both sets of contents.
- Column order is fixed and part of the format contract — appending a column is
a breaking change (major version,
12 §4). - Export writes UTF-8 with BOM (Excel compatibility).
4. Markdown (export-only)
Nested list, one line per item:
# Bookmarks — 2026-07-03
- **Bookmarks bar**
- **Dev tools**
- [GitHub](https://github.com/)
- [Example](https://example.com/)
Option "flat with headings": ## per top-level folder, flat link lists under
each. In titles, backslash-escape every character CommonMark gives meaning to
(\ ` * _ { } [ ] ( ) < > # + - . ! | ~ &) and collapse line breaks to a
space — escaping only the link brackets let raw HTML such as
<img onerror=…> through (09 T1) and let a newline turn the rest of the list
into a heading. Angle-bracket-wrap URLs containing ) or spaces.
5. Filenames
bookmarks-{all|partial}-YYYYMMDD-HHmm.{html|json|csv|md} · safety backup:
bookmarkmagic-backup-YYYYMMDD-HHmm.json.