Skip to content

Commit b96912c

Browse files
NinjaniNinjani
committed
(doc): reorganize and update README
1 parent 819998e commit b96912c

File tree

1 file changed

+123
-146
lines changed

1 file changed

+123
-146
lines changed

‎README.md

Lines changed: 123 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,9 @@
77

88
[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/ninjani)
99

10-
Gooseberry provides a command-line interface for [Hypothesis](https://web.hypothes.is/) (a tool to annotate the web) and lets you generate a
11-
knowledge-base wiki without you having to actually type your knowledge out.
10+
Gooseberry provides
11+
- a command-line interface for [Hypothesis](https://web.hypothes.is/) (a tool to annotate the web)
12+
- lets you generate a knowledge-base wiki without you having to actually type your knowledge out.
1213

1314
![Obsidian example](data/images/obsidian_example.png)
1415

@@ -18,33 +19,6 @@ knowledge-base wiki without you having to actually type your knowledge out.
1819
1920
This demonstrates the interactive search functionality. `Enter` adds a new tag, `Shift-Left` deletes a tag, and `Shift-Right` deletes an annotation. (TODO: embed keypresses in GIF)
2021

21-
## Table of Contents
22-
23-
* [Install](#install)
24-
* [Installation requirements](#installation-requirements)
25-
* [Binaries](#binaries)
26-
* [With brew (OSX)](#with-brew-osx)
27-
* [AUR](#aur)
28-
* [Contributing](#contributing)
29-
* [Motivation](#motivation)
30-
* [A typical workflow](#a-typical-workflow)
31-
* [Some advantages](#some-advantages)
32-
* [Filtering](#filtering)
33-
* [Customization](#customization)
34-
* [Hypothesis](#hypothesis)
35-
* [Knowledge base](#knowledge-base)
36-
* [Knowledge base directory](#knowledge-base-directory)
37-
* [Annotation template](#annotation-template)
38-
* [Page template](#page-template)
39-
* [Grouping annotations into folders and pages](#grouping-annotations-into-folders-and-pages)
40-
* [Sorting annotations within a page](#sorting-annotations-within-a-page)
41-
* [Tags and nesting](#tags-and-nesting)
42-
* [Index link template](#index-link-template)
43-
* [Index filename](#index-filename)
44-
* [Ignoring tags](#ignoring-tags)
45-
* [File extensions](#file-extensions)
46-
* [Why "Gooseberry"?](#why-gooseberry)
47-
4822
## Install
4923

5024
### Installation requirements
@@ -132,106 +106,150 @@ you got it from, if ever you feel like you're missing context.
132106
accepting plaintext files
133107
(like Obsidian, mdBook, org-mode, vim-wiki, etc.)
134108

135-
## Filtering
136-
137-
You can filter the annotations you want to modify or export using the following options in most gooseberry commands:
138109

110+
## Usage
111+
```
112+
Usage: gooseberry [OPTIONS] <COMMAND>
113+
114+
Commands:
115+
sync Sync newly added or updated Hypothesis annotations
116+
search Opens a search buffer to filter annotations. Has keyboard shortcuts for deleting annotations, modifying tags, and creating knowledge-base files
117+
tag Tag annotations according to topic
118+
delete Delete annotations in bulk
119+
view View (optionally filtered) annotations
120+
uri Get the set of URIs from a list of (optionally filtered) annotations
121+
make Create knowledge-base text files using optionally filtered annotations
122+
index Create an index file using hierarchy and optionally filtered annotations
123+
complete Generate shell completions
124+
config Manage configuration
125+
clear Clear all gooseberry data
126+
move Move (optionally filtered) annotations from a different hypothesis group to Gooseberry's
127+
help Print this message or the help of the given subcommand(s)
128+
129+
Options:
130+
-c, --config <CONFIG> Location of config file (uses default XDG location or environment variable if not given) [env: GOOSEBERRY_CONFIG=]
131+
-h, --help Print help
139132
```
140-
--from <FROM>
141-
Only annotations created after this date and time
142-
143-
Can be colloquial, e.g. "last Friday 8pm"
144-
145-
--before <BEFORE>
146-
Only annotations created before this date and time
147-
148-
Can be colloquial, e.g. "last Friday 8pm"
149133

150-
--uri <URI>
151-
Only annotations with this pattern in their URL
152-
153-
Doesn't have to be the full URL, e.g. "wikipedia"
134+
The default config TOML file is located in
154135

155-
--any <ANY>
156-
Only annotations with this pattern in their `quote`, `tags`, `text`, or `uri`
136+
* Linux: `/home/<username>/.config`
137+
* Mac: `/Users/<username>/Library/Preferences`
157138

158-
--tags <TAGS>
159-
Only annotations with ANY of these tags (use --and to match ALL)
139+
Change this by creating a config file with `gooseberry config default > config.toml` and modifying the contents. You can
140+
then use this as your configuration with `gooseberry -c path/to/config.toml <subcommand>` or by setting the environment
141+
variable `$GOOSEBERRY_CONFIG` to point to the file.
160142

161-
--groups <GROUPS>
162-
Only annotations from these groups
143+
Authorize Hypothesis either by setting the `$HYPOTHESIS_NAME` and `$HYPOTHESIS_KEY` environment variables to your username and developer API token or
144+
by running `gooseberry config authorize`.
163145

164-
--exclude-tags <EXCLUDE_TAGS>
165-
Only annotations without ANY of these tags
146+
Gooseberry takes annotations from given Hypothesis group(s) which you can create/set with `gooseberry config group`. This automatically syncs all existing annotations from these groups.
166147

167-
--quote <QUOTE>
168-
Only annotations that contain this text inside the text that was annotated
148+
Sync newly added annotations with `gooseberry sync`.
169149

170-
--text <TEXT>
171-
Only annotations that contain this text in their textual body
150+
The `search` command provides an interactive search interface to your annotations (optionally pre-filtered using the filtering options below). Each annotation is rendered using the annotation template (configured with `gooseberry config kb annotation` and described below). The interface supports the following keybindings:
151+
Arrow keys to scroll, Tab to toggle selection, Ctrl-A to select all, Esc to abort
152+
Enter to add a tag, Shift-Left to delete a tag, Shift-Right to delete an annotation
153+
Shift-Down to make knowledge-base files, Shift-Up to print the set of URIs.
172154

173-
-i, --include-updated
174-
Include annotations updated in given time range (instead of just created)
175-
-n, --not
176-
Annotations NOT matching the given filter criteria
155+
You can also accomplish these tasks without the interactive interface using the `tag`, `delete`, `view`, `uri`, `make`, and `index` commands.
177156

178-
--and
179-
(Use with --tags) Annotations matching ALL of the given tags
157+
**NOTE: tagging and deletions are synced to Hypothesis!**
180158

181-
-p, --page
182-
Only page notes
159+
### Filtering
183160

184-
-a, --annotation
185-
Only annotations (i.e exclude page notes)
161+
You can filter the annotations you want to modify or export using the following options in most gooseberry commands:
186162

187-
-f, --fuzzy
188-
Toggle fuzzy search
189163
```
164+
--from <FROM>
165+
Only annotations created after this date and time
166+
167+
Can be colloquial, e.g. "last Friday 8pm"
190168
191-
## Customization
169+
--before <BEFORE>
170+
Only annotations created before this date and time
171+
172+
Can be colloquial, e.g. "last Friday 8pm"
192173
193-
The default config TOML file is located in
174+
-i, --include-updated
175+
Include annotations updated in given time range (instead of just created)
194176
195-
* Linux: `/home/<username>/.config`
196-
* Mac: `/Users/<username>/Library/Preferences`
177+
--uri <URI>
178+
Only annotations with this pattern in their URL
179+
180+
Doesn't have to be the full URL, e.g. "wikipedia"
181+
182+
[default: ]
197183
198-
Change this by creating a config file with `gooseberry config default > config.toml` and modifying the contents. You can
199-
then use this as your configuration with `gooseberry -c path/to/config.toml <subcommand>` or by setting the environment
200-
variable `$GOOSEBERRY_CONFIG` to point to the file.
184+
--any <ANY>
185+
Only annotations with this pattern in their `quote`, `tags`, `text`, or `uri`
186+
187+
[default: ]
201188
202-
### Hypothesis
189+
--tags <TAGS>
190+
Only annotations with ANY of these tags (use --and to match ALL)
203191
204-
Authorize Hypothesis either by setting the `$HYPOTHESIS_NAME` and `$HYPOTHESIS_KEY` environment variables to your username and developer API token or
205-
by running `gooseberry config authorize`.
192+
--groups <GROUPS>
193+
Only annotations from these groups
206194
207-
Gooseberry takes annotations from given Hypothesis group(s) which you can create/set with `gooseberry config group`.
195+
--exclude-tags <EXCLUDE_TAGS>
196+
Only annotations without ANY of these tags
208197
209-
### Knowledge base
198+
--quote <QUOTE>
199+
Only annotations that contain this text inside the text that was annotated
200+
201+
[default: ]
210202
211-
You can set all the below options at once by running `gooseberry config kb all` or changing the corresponding keys in
212-
the config file (found at `gooseberry config location`)
203+
--text <TEXT>
204+
Only annotations that contain this text in their textual body
205+
206+
[default: ]
213207
214-
Generate knowledge base files using `gooseberry make` - this command has options to filter annotations, and to clear the
215-
directory before generating (`-c` or `--clear`). By default, it also generates an index file (configured by the `index`
216-
and `link` configuration options below) using the filtered annotations - this can be disabled with `--no-index`.
217-
Use `gooseberry index` to generate just the index file, this command also has annotation filtering options.
208+
-n, --not
209+
Annotations NOT matching the given filter criteria
218210
219-
#### Knowledge base directory
211+
--and
212+
(Use with --tags) Annotations matching ALL of the given tags
220213
221-
`gooseberry config kb directory`
214+
-p, --page
215+
Only page notes
222216
223-
The directory to save the generated knowledge base files.
217+
-a, --annotation
218+
Only annotations (i.e exclude page notes)
219+
```
224220

225-
**IMPORTANT:** This directory is cleared at every sync so if you're storing Hypothesis annotations alongside other notes, make sure to make a separate
226-
folder.
221+
### Knowledge base
227222

228-
#### Annotation template
223+
The `gooseberry make` command is used to generate knowledge base files using (optionally filtered) annotations. By default, it also generates an index file (configured by the `index`
224+
and `link` configuration options) - this can be disabled with `--no-index`. Use `gooseberry index` to generate just the index file.
225+
226+
Configuration options for the knowledge base are as follows:
227+
```
228+
Usage: gooseberry config kb <COMMAND>
229+
230+
Commands:
231+
all Change everything related to the knowledge base
232+
directory Change knowledge base directory
233+
annotation Change annotation handlebars template
234+
page Change page handlebars template
235+
link Change index link handlebars template
236+
index Change index file name
237+
extension Change knowledge base file extension
238+
hierarchy Change folder & file hierarchy
239+
sort Change sort order of annotations within a page
240+
ignore Set which tags to ignore
241+
nest Set string defining nested tags (e.g "/" => parent/child)
242+
help Print this message or the help of the given subcommand(s)
243+
```
229244

230-
`gooseberry config kb annotation`
245+
You can set all knowledge base configuration options at once by running `gooseberry config kb all` or changing the corresponding keys in the config file (found at `gooseberry config where`).
231246

232-
Change the template used for rendering the annotation.
247+
**IMPORTANT:** The knowledge base directory is cleared at every sync so if you're storing Hypothesis annotations alongside other notes, make sure to make a separate
248+
folder.
249+
250+
#### Annotation template
233251

234-
The following keys can be used inside the template
252+
The `annotation` template is used to render a single annotation. The following keys can be used inside the template:
235253

236254
* `{{ id }}` - Annotation ID
237255
* `created` - Date of creation. Use with the `date_format` helper (See [here](https://docs.rs/chrono/0.4.19/chrono/format/strftime/index.html) for formatting options)
@@ -318,11 +336,7 @@ TODO add org-mode example
318336

319337
#### Page template
320338

321-
`gooseberry config kb page`
322-
323-
Change the template used for rendering a single page (NOT the Index page).
324-
325-
The following keys can be used inside the template:
339+
The `page` template is used for rendering a single page of annotations (NOT the Index page). The following keys can be used inside the template:
326340

327341
* `{{ name }}` - file stem
328342
* `{{ relative_path }}` - path relative to KB directory
@@ -342,11 +356,7 @@ The default template is:
342356

343357
#### Grouping annotations into folders and pages
344358

345-
`gooseberry config kb hierarchy`
346-
347-
The hierarchy defines how the folder and file structure of the knowledge base looks and which annotations are on what pages.
348-
349-
The available options are:
359+
The `hierarchy` configuration defines how the folder and file structure of the knowledge base looks and which annotations are on what pages. The available options are:
350360

351361
* Empty - Set `hierarchy = []` to have all annotations rendered on the index page.
352362
* Tag - Groups annotations by tag
@@ -368,11 +378,7 @@ annotations marked with that tag.
368378

369379
#### Sorting annotations within a page
370380

371-
`gooseberry config kb sort`
372-
373-
This defines how annotations are sorted within each page.
374-
375-
The available options are:
381+
The `sort`configuration defines how annotations are sorted within each page. The available options are:
376382

377383
* Tag - Sorts by tag (multiple tags are considered as "tag1,tag2,tag3" for sorting)
378384
* URI
@@ -387,24 +393,9 @@ The available options are:
387393
Multiple sort options can be combined in order of priority e.g. `sort = ["Tag", "Created"]` sorts by tags, then by the
388394
date of creation.
389395

390-
#### Tags and nesting
391-
392-
`gooseberry config kb nested`
393-
394-
This defines the pattern to use for nesting tags. e.g. if `nested_tag = "/"` then a tag of "parent/child" combined
395-
with `hierarchy = ["Tag"]` would create a "parent" folder with a "child" file inside it.
396-
397-
Commas (",") and semicolons (";") should not be used inside tags as they are used as separators by Gooseberry.
398-
399396
#### Index link template
400397

401-
`gooseberry config kb link`
402-
403-
This configures the index file, which generally contains links to all other pages in the generated knowledge base
404-
(unless `hierarchy=[]` in which case all annotations are rendered on the index page). The template controls how each of
405-
these links are rendered.
406-
407-
Available keys:
398+
The `link` template controls how each link in the index file is rendered. The available keys are:
408399

409400
* `{{ name }}` - file stem
410401
* `{{ relative_path }}` - path relative to KB directory
@@ -442,26 +433,12 @@ to transclude files
442433
443434
```
444435

445-
#### Index filename
446-
447-
`gooseberry config kb index`
448-
449-
The name of the Index file, e.g. `mdbook` needs this to be called "SUMMARY" and in Obisidan you could use "00INDEX" to make it show up first in the
450-
file explorer.
451-
452-
#### Ignoring tags
453-
454-
`gooseberry config kb ignore`
455-
456-
Some annotations maybe aren't meant for the knowledge base. You can exclude these by tagging them with a specific tag, and then adding this tag to the
457-
`ignore_tags` configuration option (manually in the config file or with the above command). Note: Annotations with ignored tags will still be included
458-
in the `search` and `tag` commands.
459-
460-
#### File extensions
461-
462-
`gooseberry config kb extension`
436+
#### Other options
463437

464-
e.g. "md", "org", "txt" etc. (**Don't include the .**)
438+
- `index` - sets the name of the Index file, e.g. `mdbook` needs this to be called "SUMMARY" and in Obisidan you could use "00INDEX" to make it show up first in the file explorer.
439+
- `ignore` - sets the list of tags to ignore when creating the knowledge base. *Note: Annotations with ignored tags will still be included in the `search` and `tag` commands*
440+
- `nest` - defines the pattern to use for nesting tags. e.g. if `nested_tag = "/"` then a tag of "parent/child" combined with `hierarchy = ["Tag"]` would create a "parent" folder with a "child" file inside it. *Note: Commas (",") and semicolons (";") should not be used inside tags as they are used as separators by Gooseberry.*
441+
- `extension` - sets the file extension for the knowledge base files. e.g. "md", "org", "txt" etc. *Note: Don't include the . in the extension*
465442

466443
## Why "Gooseberry"?
467444

0 commit comments

Comments
 (0)