Skip to content

Feat/keywords links support#9

Draft
Floper wants to merge 7 commits into
philips:mainfrom
Floper:feat/keywords-links-support
Draft

Feat/keywords links support#9
Floper wants to merge 7 commits into
philips:mainfrom
Floper:feat/keywords-links-support

Conversation

@Floper

@Floper Floper commented Jun 3, 2026

Copy link
Copy Markdown

Parse Supernote internal links and keyword stars

This PR adds two new parsing features to the library: internal link resolution
(with page anchors) and keyword/star text extraction. It also exposes ILink
and IPage as public types.

Links (LINKO)

The Supernote format stores internal links in the footer under LINKO_* keys.
These were not previously parsed at all.

  • Added _parseLinks / _parseLink methods to SupernoteX — symmetrical to
    the existing keyword and title parsers
  • Added ILink interface to format.ts and exposed it on ISupernote.links as
    Record<string, ILink[]>
  • The LINKFILE field is a Base64-encoded absolute device path; _parseLink
    decodes it and extracts the filename (without path or .note extension) into a
    text field ready for use as a Wikilink
  • Page anchor resolution: each link carries a PAGEID that identifies the
    target page. _parseLink looks up that PAGEID in this.pages (populated
    before links are parsed). If matched — i.e. the link points to a page in the
    same document — it appends #Page N to text (e.g. "my-note#Page 1").
    Cross-file links where the target is not in this document produce no anchor.
  • Added PAGEID?: string to IPage so page identity is accessible for the lookup

Keywords (KEYWORD)

The KEYWORD_* and LINKO_* footer entries use a journaled/append-only format,
meaning the same key can appear multiple times. The previous footer parser used
extractNestedKeyValue which silently drops repeated keys. These two groups are
now extracted separately, preserving every entry as a string or string[].

Additionally, _parseKeyword previously left KEYWORD empty because it misread
KEYWORDSITE as a bitmap address. KEYWORDSITE actually points to a
length-prefixed block containing the OCR text of the starred word. This is now
correctly decoded into the KEYWORD field.

Public API

ILink and IPage are now exported from the package index, allowing consumers
to type link and page data without reaching into internal modules.

Tests

  • Added nomad-3.26.40-link-tag-3p.note as a test fixture (3 pages, 3 links on
    page 2, 3 keyword stars on page 3 including a brand-new tag)
  • links suite: verifies same-file links get a #Page N anchor via PAGEID
    lookup; cross-file links with a PAGEID but no matching page in this document
    produce no anchor; links with PAGEID: 'none' produce no anchor
  • keywords suite: verifies all 3 keyword stars are parsed with correct OCR
    text; verifies that the KEYWORD footer key prefix (first 4 digits, 1-indexed)
    reliably encodes the source page — including the known case where KEYWORDPAGE
    itself is '0' (invalid) while the key prefix is correct

@Floper
Floper marked this pull request as draft June 4, 2026 08:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant