6 |
7 | ### Features
8 |
9 | - Sync web article highlights/annotations on Obsidian startup or manual trigger
10 | - Update existing articles with new highlights and annotations
11 | - Customization highlights through [Nunjucks](https://mozilla.github.io/nunjucks) template
12 |
13 | ## Usage
14 |
15 | After installing the plugin, configure the the settings of the plugin then initiate the first sync manually. Thereafter, the plugin can be configured to sync automatically or manually
16 |
17 | Use Hypothesis icon on the side icon ribbon or command to trigger manual sync.
18 |
19 | ### Settings
20 |
21 | - `Connect`: Enter [API Token](https://hypothes.is/account/developer) in order to pull the highlights from Hypohesis
22 | - `Disconnect`: Remove API Token from Obsidian
23 | - `Auto Sync Interval`: Set the interval in minutes to sync Hypothesis highlights automatically
24 | - `Highlights folder`: Specify the folder location for your Hypothesis articles
25 | - `Use domain folders`: Group generated files into folders based on the domain of the annotated URL
26 | - `Sync on startup`: Automatically sync highlights when open Obsidian
27 | - `Highlights template`: Nunjuck template for rendering your highlights
28 | - `Groups`: Add/remove group to be synced
29 | - `Reset sync`: Wipe your sync history. Does not delete any previously synced highlights from your vault
30 |
31 | ### To sync all new highlights since previous update
32 |
33 | - Click: Hypothesis ribbon icon
34 | - Command: Sync new highlights
35 | - Command: Resync deleted file
36 | > (Note: Files synced before v0.1.5 will need to reset sync history and delete all synced files to have this feature work properly)
37 |
38 | ## Limitations & caveats
39 |
40 | - Limit to 1000 highlights on initial sync for performance. Subsequent sync for deltas are capped at 200 as pagination of result sets does not work in conjunction with API search_after parameter.
41 | - Only tested with Obsidian Mac OSX and Windows 10.
42 | - Does not suport annotations on PDFs.
43 |
44 | ## Acknowledgement
45 |
46 | This project is inspired by Hady Ozman's [Obsidian Kindle Plugin](https://github.com/hadynz/obsidian-kindle-plugin).
47 |
48 | ## Do you find this plugin useful?
49 |
50 |
51 |
52 | Thank you for your support 🙏
53 |
--------------------------------------------------------------------------------
/manifest.json:
--------------------------------------------------------------------------------
1 | {
2 | "id": "obsidian-hypothesis-plugin",
3 | "name": "Hypothes.is",
4 | "version": "0.1.19",
5 | "minAppVersion": "0.11.0",
6 | "description": "Sync your Hypothesis highlights",
7 | "author": "weichenw",
8 | "authorUrl": "https://github.com/weichenw",
9 | "isDesktopOnly": false
10 | }
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "obsidian-hypothesis-plugin",
3 | "version": "0.0.1",
4 | "description": "Sync your Hypothesis highlights",
5 | "main": "src/main.ts",
6 | "repository": {
7 | "type": "git",
8 | "url": "https://github.com/weichenw/obsidian-hypothesis-highlights.git"
9 | },
10 | "scripts": {
11 | "clean": "rimraf dist main.js",
12 | "build": "svelte-check && npm run lint && webpack",
13 | "dev": "NODE_ENV=development webpack && cp ./dist/main.js* .",
14 | "lint": "eslint . --ext .ts"
15 | },
16 | "keywords": [],
17 | "author": "weichenw",
18 | "license": "MIT",
19 | "dependencies": {
20 | "axios": "^0.26.0",
21 | "gray-matter": "^4.0.3",
22 | "lodash.pickby": "^4.6.0",
23 | "nunjucks": "^3.2.3"
24 | },
25 | "devDependencies": {
26 | "@babel/core": "^7.15.8",
27 | "@tsconfig/svelte": "^1.0.10",
28 | "@types/lodash.pickby": "^4.6.6",
29 | "@types/node": "^14.14.37",
30 | "@types/nunjucks": "^3.2.0",
31 | "@typescript-eslint/eslint-plugin": "^5.0.0",
32 | "@typescript-eslint/parser": "^5.0.0",
33 | "babel-loader": "^8.2.2",
34 | "copy-webpack-plugin": "^8.1.1",
35 | "crypto-js": "^4.1.1",
36 | "electron": ">=13.6.6",
37 | "eslint": "^8.0.0",
38 | "obsidian": "^0.12.0",
39 | "rimraf": "^3.0.2",
40 | "sanitize-filename": "^1.6.3",
41 | "svelte": "^3.37.0",
42 | "svelte-check": "^1.4.0",
43 | "svelte-loader": "^3.1.0",
44 | "svelte-preprocess": "^4.7.0",
45 | "svelte-select": "^4.4.3",
46 | "ts-loader": "^8.1.0",
47 | "tslib": "^2.2.0",
48 | "typescript": "^4.2.4",
49 | "webpack": "^5.30.0",
50 | "webpack-cli": "^4.6.0",
51 | "webpack-node-externals": "^2.5.2"
52 | }
53 | }
--------------------------------------------------------------------------------
/src/api/api.ts:
--------------------------------------------------------------------------------
1 |
2 | import { Notice, moment } from 'obsidian';
3 | import axios from "axios";
4 |
5 | export default class ApiManager {
6 | readonly baseUrl: string = 'https://hypothes.is/api';
7 | private token: string;
8 | private userid: string;
9 |
10 | constructor(token: string, userid: string = undefined) {
11 | this.token = token;
12 | this.userid = userid;
13 | }
14 |
15 | private getHeaders() {
16 | return {
17 | 'AUTHORIZATION': `Bearer ${this.token}`,
18 | 'Accept': 'application/json',
19 | };
20 | }
21 |
22 | async getProfile() {
23 | try {
24 | const response = await axios.get(`${this.baseUrl}/profile`, { headers: this.getHeaders() })
25 | return response.data.userid
26 | }
27 | catch (e) {
28 | new Notice('Failed to authorize Hypothes.is user. Please check your API token and try again.')
29 | console.error(e);
30 | return;
31 | }
32 | }
33 |
34 | async getHighlights(lastSyncDate?: Date, limit = 2000) {
35 | let annotations = [];
36 |
37 | try {
38 | // Paginate API calls via search_after param
39 | // search_after=null starts at with the earliest annotations
40 | let newestTimestamp = lastSyncDate && moment.utc(lastSyncDate).format()
41 | while (annotations.length < limit) {
42 | const response = await axios.get(
43 | `${this.baseUrl}/search`,
44 | {
45 | params: {
46 | limit: 200, // Max pagination size
47 | sort: "updated",
48 | order: "asc", // Get all annotations since search_after
49 | search_after: newestTimestamp,
50 | user: this.userid,
51 | },
52 | headers: this.getHeaders()
53 | }
54 | )
55 | const newAnnotations = response.data.rows;
56 | if (!newAnnotations.length) {
57 | // No more annotations
58 | break;
59 | }
60 |
61 | annotations = [ ...annotations, ...newAnnotations ];
62 | newestTimestamp = newAnnotations[newAnnotations.length - 1].updated;
63 | }
64 |
65 | } catch (e) {
66 | new Notice('Failed to fetch Hypothes.is annotations. Please check your API token and try again.')
67 | console.error(e);
68 | }
69 |
70 | return annotations;
71 | }
72 |
73 | async getHighlightWithUri(uri: string, limit = 200) {
74 | try {
75 | const response = await axios.get(`${this.baseUrl}/search`, {
76 | params: {
77 | limit,
78 | uri,
79 | user: this.userid,
80 | sort: "updated",
81 | order: "asc"
82 | },
83 | headers: this.getHeaders()
84 | })
85 |
86 | return response.data.rows;
87 | } catch (e) {
88 | new Notice('Failed to fetch Hypothes.is annotations. Please check your API token and try again.')
89 | console.error(e);
90 | }
91 | }
92 |
93 | async getGroups() {
94 | try {
95 | const response = await axios.get(`${this.baseUrl}/groups`, { headers: this.getHeaders() })
96 | return response.data
97 | } catch (e) {
98 | new Notice('Failed to fetch Hypothes.is annotation groups. Please check your API token and try again.')
99 | console.error(e);
100 | }
101 | }
102 | }
103 |
--------------------------------------------------------------------------------
/src/assets/defaultTemplate.njk:
--------------------------------------------------------------------------------
1 | {% if is_new_article %}
2 | # {{title}}
3 |
4 | ## Metadata
5 | {% if author %}- Author: [{{author}}]({{authorUrl}}){% endif %}
6 | - Title: {{title}}
7 | {% if url %}- Reference: {{url}}{% endif %}
8 | - Category: #article
9 | {% endif %}
10 |
11 | {%- if is_new_article %}
12 | ## Page Notes
13 | {% for highlight in page_notes -%}
14 | {{highlight.annotation}}
15 | {%- if highlight.tags | length %}
16 | Tags: {% for tag in highlight.tags -%} #{{tag | replace(" ", "-")+" "}}{%- endfor %}
17 | {% endif %}
18 | {% endfor %}
19 | {%- endif -%}
20 |
21 | {%- if is_new_article -%}
22 | ## Highlights
23 | {% for highlight in highlights -%}
24 | - {{highlight.text}} — [Updated on {{highlight.updated}}]({{highlight.incontext}})
25 | {%- if 'Private' != highlight.group %} — Group: #{{highlight.group | replace(" ", "-")}}{% endif %}
26 | {% if highlight.tags | length %} - Tags: {% for tag in highlight.tags %} #{{tag | replace(" ", "-")+" "}}{% endfor %}
27 | {% endif -%}
28 | {% if highlight.annotation %} - Annotation: {{highlight.annotation}}{% endif %}
29 | {% endfor %}
30 | {% endif %}
31 |
--------------------------------------------------------------------------------
/src/assets/hypothesisIcon.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/src/custom.d.ts:
--------------------------------------------------------------------------------
1 | /* eslint-disable @typescript-eslint/no-explicit-any */
2 |
3 | declare module '*.njk' {
4 | const content: any;
5 | export default content;
6 | }
7 |
8 | declare module '*.html' {
9 | const content: any;
10 | export default content;
11 | }
12 |
13 | declare module '*.svg' {
14 | const content: any;
15 | export default content;
16 | }
17 |
--------------------------------------------------------------------------------
/src/fileManager.ts:
--------------------------------------------------------------------------------
1 | import type { Vault, MetadataCache, TFile } from 'obsidian';
2 | import { get } from 'svelte/store';
3 | import { Renderer } from '~/renderer';
4 | import { settingsStore } from '~/store';
5 | import { sanitizeTitle } from '~/utils/sanitizeTitle';
6 | import type { Article } from '~/models';
7 | import { frontMatterDocType, addFrontMatter } from "~/utils/frontmatter"
8 |
9 | type AnnotationFile = {
10 | articleUrl?: string;
11 | file: TFile;
12 | };
13 |
14 | const articleFolderPath = (article: Article): string => {
15 | const settings = get(settingsStore);
16 | if (settings.useDomainFolders) {
17 | // "metadata.author" is equal to the article domain at the moment
18 | return `${settings.highlightsFolder}/${article.metadata.author}`;
19 | }
20 |
21 | return settings.highlightsFolder;
22 | };
23 |
24 | export default class FileManager {
25 | private vault: Vault;
26 | private metadataCache: MetadataCache;
27 | private renderer: Renderer;
28 |
29 | constructor(vault: Vault, metadataCache: MetadataCache) {
30 | this.vault = vault;
31 | this.metadataCache = metadataCache;
32 | this.renderer = new Renderer();
33 | }
34 |
35 | // Save an article as markdown file, replacing its existing file if present
36 | public async saveArticle(article: Article): Promise24 | 33 |
34 |25 | 28 |
29 |5 | Available variables to use 6 |
7 | 8 | Article Metadata 9 |