Gooseberry - a Knowledge Base for the Lazy

Crates.io CI GitHub release dependency status

WIP

Gooseberry provides a command-line interface for Hypothesis (a tool to annotate the web) and lets you generate a knowledge-base wiki without you having to actually type your knowledge out.

Table of Contents

Installation requirements

Binaries

See the releases

Contributing

See CONTRIBUTING.md for an in-depth explanation of how Gooseberry works and what could be improved.

Motivation

So yes, knowledge-base tools are old hat and a dime a dozen, and we really have no excuse to not have a nice big tangled folder of markdown files filled with our overflowing wisdom. But after spending all day writing code and papers and tasks, it just isn't fair that our reading time also needs to be typing time to get all that knowledge down. And if we don't type things out our fancy knowledge-base is bare, empty, and sad.

In comes Gooseberry - a tool to build a knowledge base from highlighting and annotating passages while reading news articles, blog posts, papers, what have you. Gooseberry combines the ease of annotation offered by Hypothesis, bulk tagging and organization support in the command line, and a customizable plaintext wiki with HandleBars templating.

A typical workflow

  1. Find an article, blog post, paper etc. to read.
  2. Highlight lines and facts you'd like to remember later. You can add comments and tags already if you're up for it but the focus can also be just on reading and highlighting without thinking too much about taking notes.
  3. More often than not, when one gets into a topic it ends in 50 open tabs of subtopics. This is fine, keep reading and highlighting away, we'll get back to this.
  4. Finally, once your thirst for knowledge has been fulfilled, fire up a terminal and run

Here's an example. Today I read and annotated three articles about insects: this Nautilus article titled "We need insects more than they need us", this publication about honey bees and pesticides, and an Atlantic article about the "anternet" .

I synced and tagged these annotations:

gooseberry sync and tag

Then ran gooseberry make to make an mdBook style wiki which I could then open in the browser:

Tag page example

Or an Obsidian style wiki, with annotations grouped into folders based on their base URI

Obsidian example

Annotation text is just markdown so text formatting, LaTeX, pictures etc. goes too!

Picture example

The annotation template is configurable, as is the folder and grouping structure. Each annotation can link back to the position in the website that you got it from, if ever you feel like you're missing context.

Some advantages

Customization

The default config TOML file is located in

Change this by creating a config file with gooseberry config default > config.toml, modifying the contents, and then setting the environment variable $GOOSEBERRY_CONFIG to point to this file.

Hypothesis

Authorize Hypothesis either by setting the $HYPOTHESIS_NAME and $HYPOTHESIS_KEY environment variables to your username and developer API token or by running gooseberry config authorize.

Gooseberry takes annotations from a given Hypothesis group which you can create/set with gooseberry config group.

Knowledge base

You can set all the below options at once by running gooseberry config kb all or changing the corresponding keys in the config file (found at gooseberry config location)

Knowledge base directory

gooseberry config kb directory

The directory to save the generated knowledge base files.

IMPORTANT: This directory is cleared at every sync so if you're storing Hypothesis annotations alongside other notes, make sure to make a separate folder.

Annotation template

gooseberry config kb annotation

Change the template used for rendering the annotation.

The following keys can be used inside the template

See the Handlebars Language Guide for more on templating. Some examples for using the list keys and for formatting dates are shown below for different systems:

```markdown

{{date_format "%c" (created)}} - {{id}}

{{#each tags}}| {{this}} {{#if @last}}|{{/if}}{{/each}}

{{#each highlight}}> {{this}}{{/each}}

{{text}}

See in context ```

Renders as:

```markdown

Sat Jan 16 11:12:49 2021 - test

| tag1 | tag2 |

exact text highlighted in website

testing annotation

See in context ```

This makes each tag a link to a dedicated page consisting of annotations with that tag - you can set this up by configuring the hierarchy (hierarchy = ["tag"]).

```markdown

{{id}}

Created: {{date_format "%c" (created)}} Tags: {{#each tags}}#{{this}}{{#unless @last}}, {{/unless}}{{/each}}

{{#each highlight}}> {{this}}{{/each}}

{{text}}

See in context ```

Renders as:

```markdown

test

Created: Sat Jan 16 10:22:20 2021 Tags: #tag1, #tag2

exact text highlighted in website

testing annotation ```

This uses #tags b/c Obsidian likes those.

TODO add org-mode example

Page template

gooseberry config kb page

Change the template used for rendering a single page (NOT the Index page).

The following keys can be used inside the template:

The default template is:

```markdown

{{name}}

{{#each annotations}}{{this}}{{/each}}

```

Grouping annotations into folders and pages

gooseberry config kb hierarchy

The hierarchy defines how the folder and file structure of the knowledge base looks and which annotations are on what pages.

The available options are:

Multiple hierarchies combined make folders and sub-folders, with the last entry defining pages.

e.g.

hierarchy = ["BaseURI", "Tag"] would make a separate folder for each base_uri. Within each folder would be a page for each tag consisting of annotations marked with that tag.

hierarchy = ["Tag"] gives the structure in the mdbook figure above, i.e. no folders, a page for each tag.

Sorting annotations within a page

gooseberry config kb sort

This defines how annotations are sorted within each page.

The available options are:

Multiple sort options can be combined in order of priority e.g. sort = ["Tag", "Created"] sorts by tags, then by the date of creation.

Index link template

gooseberry config kb link

This configures the index file, which generally contains links to all other pages in the generated knowledge base (unless hierarchy=[] in which case all annotations are rendered on the index page). The template controls how each of these links are rendered.

Available keys:

Examples:

```markdown - {{name}}

```

```markdown - [[{{name}}]]

```

to make internal links, or

```markdown - ![[{{name}}]]

```

to transclude files

```org - [[{{relative_path}}][{{name}}]]

```

Index filename

gooseberry config kb index

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.

File extensions

gooseberry config kb extension

e.g. "md", "org", "txt" etc. (Don't include the .)

Why "Gooseberry"?

Because Discworld will never let me down when it comes to names: Dis-organizer Mark 5, the Gooseberry