# Annotation Bookmark Extension Specs
###### tags: `Docs` `Specs` `Dev`
[TOC]

## Features

### Basics
- A text selection in a webpage gets an extra option in its context menu: ‘Highlight/Bookmark selected text’
- Bookmarking a selection will save it in the browser’s bookmarks.
- When visiting any page, retrieve its corresponding bookmarks, and display them (= highlight text).
- Clicking a highlight ~~lets one remove the bookmark or copy its URL~~ updates the address bar with the fragment identifier, so the browser’s star button can be used to organize or remove the bookmark.

### Optional
- Ability to edit the bookmark’s selection
- Show star besides the highlight when hovering, and mimic the ‘edit bookmark’ menu, to make it obvious both that it is a bookmark and where to edit it.
- The Name of the bookmark can be/include a note that the user wrote.
- Share bookmarks
- The URL for the Bookmark can be shared with other users of the browser extension
- Ideally through existing link sharing methods (e.g. share by email, ~~Pinboard~~, Shaarli, Wallabag)
- Use [freeze-dry](https://github.com/WebMemex/freeze-dry) to store the page being bookmarked.
- How will we handle this cache in a share scenario?
- Do we want to store our bookmarks in the snapshot? Could be both machine-readable ([RDFa](https://www.w3.org/TR/annotation-html/#annotations-embedded-as-rdfa)?), and human-readable (highlight + possibly note)

## User Story
Alica uses browser extension *Deepmark-it* to highlight a section in a blog post and save to bookmarks.

1. When Alica visits the blog post again, her bookmark will be visible (highlighted).

2. Alica can share the bookmark with Bobtje via email, messaging[?]
Bobtje uses the same browser extension to view the bookmark.

## Implementation

### Overview

- The saved bookmark will have as its Location the page URL plus a fragment identifier that encodes the WA Selector for the selection.

### Browser bookmark apis that will be used
1. Create Bookmark: `bookmarks.create()`
2. Retrieve Bookmark: `browser.bookmarks.getTree()`
a. Also there are other apis to get bookmark by id however, we might need to lookup by URL of the page.

### Notes & questions
- When retrieving the bookmarks and displaying it, the quoteurl.js default behaviour is scroll to selection - which is perfect when we click on the bookmarks to visit the selection.
- But when the user visits the page without frag identifier, then the extension will retrieve the bookmarks, but need not scroll.
- When creating bookmark via context menu, the bookmark organizing options like name, tag or folder options implementation doesn't seem straight forward.

### Links to Code, Repository, Documentation, Demos and other Stuff
- [Github Repo](https://github.com/salus-sage/deepmark-it)
- [Quote Url and highlight js](https://github.com/Treora/quoteurl)
- [Selectors and States as Fragment Identifiers](https://www.w3.org/TR/selectors-states/#frags)
- [URI Fragment Converter](http://w3c.github.io/web-annotation/selector-note/converter/)

## References
- [Reference minutes of meeting 23rd Sep](https://hackmd.io/psiUrcJPSpKsewduQmbmTA?both)
- [Moz Browser bookmarks API](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/bookmarks)
- For retrieval, we can use `browser.bookmarks.getTree()` and walk through the bookmarks ourselves, may be faster and more flexible than using `search()`.