blueNote

A Notes/Clippings Browser

---

Build

git clone [email protected]:yifan-gu/blueNote.git && go build
./blueNote -h

---

Notes

This tool supports both HTML highlights exported via the Kindle App and the My Clippings.txt file directly from a Kindle device.

• My Clippings.txt:

  • Pros: Contains all highlights and notes.
  • Cons: Lacks chapter information.

• HTML Highlights:

  • Pros: Better formatting and includes chapter information.
  • Cons: You can only generate highlights/notes one book at a time.

---

Usage

Convert My Clippings.txt to JSON and display it in the console

./blueNote convert -i kindle-my-clippings -o json --json.pretty examples/My\ Clippings.txt

Convert Kindle HTML notes to JSON and display them in the console

(click here to see how to export the kindle HTML notes via Kindle App)

./blueNote convert -i kindle-html -o json --json.pretty examples/kindle_html_single_book_example.html

Convert notes and store them into MongoDB

./blueNote convert -i kindle-html -o mongodb examples/kindle_html_single_book_example.html

Add -s if the book is a collection of multiple books

./blueNote convert -i kindle-html -o json --json.pretty -s examples/kindle_html_collection_example.html

Run as an http server that serves data from the MongoDB via GraphQL enpoints

./blueNote server

Query the highlights using the GraphQL API

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "query { marks(author: \"Maugham\") { type title author data note tags createdAt lastModifiedAt } }"}' \
  http://localhost:11212/graphql 2>/dev/null | jq .
{
  "data": {
    "marks": [
      {
        "author": "Maugham, W. Somerset",
        "createdAt": 1733038917438,
        "data": "trouble, much resented the churchwarden's managing ways. He really seemed to look upon himself as the most important person in the parish. Mr. Carey constantly told his wife that if Josiah Graves did not take care he would give him a good rap over the knuckles one day; but Mrs. Carey advised him to bear with Josiah Graves: he meant well, and it was not",
        "lastModifiedAt": 1733038917438,
        "note": "",
        "tags": [],
        "title": "Of Human Bondage",
        "type": "HIGHLIGHT"
      }
    ]
  }
}

---

TODO

Documentation

• Update README to reflect JSON/MongoDB-based usage.

Emacs Org-roam

• [Dropped] Roam module (fix bug).
• [Dropped] Check roam version.

Parser/Exporter

• Refactor book module.
• Refactor configs for parser and exporter.
• Fix location output.
• Fix user notes content.
• JSON exporter.
• Optional author/title flag.
• Stacktrace error handling.
• List parsers and exporters.
• MongoDB exporter.
• JSON parser.
• One-click export from Kindle app.
• Change parser/exporter type from string to safe type.
• My Clippings.txt parser.
• Diff the previous processed My Clippings.txt so don't parse the whole file again.
• Support multiple authors.
• Add progress indicator.
• Difference between createdAt and when notes are added to the database.
• Figure out the difference in length between json and loaded mongodb json.

Server Backend

• Database storage.
• Index, unique on digest.
• Update storage interface.
• Recompute digest.
• Limit on returned marks.
• Add timestamps (created, last modified).
• Server REST API.
• GraphQL API (READ).
• GraphQL API (CREATE).
• GraphQL API (UPDATE).
• GraphQL API (DELETE).
• Handle GraphQL null fields.
• GraphQL API tests with mocked storage.

Application

• Create database schema for users.
• Create database schema for books.
• Create database schema for mark interactions (user likes, comments, shares).
• Add search by tags, keywords, book, author.
• Show random notes/highlights every time.
• Display connected notes.
• Add clickable tags, books, authors.
• Manual tag updates.
• Ratings system.
• Support audiobooks.
• Generate tags automatically.
• Suggest connected notes.

Advanced Features

• User ratings.
• User comments.
• User profiles.
• User-uploaded audiobook readings.