#notes/misc
- Introduction
- How it works/what it does
- Installing
- Configuring & running
- Processing a few notes
- Processing all notes
- Processors
- Backlinker
- Table of contents generator
- Note actions
- Add or remove text in titles
- Highlight searches
- Collecting note links
- Configuring
bearutils - Extending Bearutils
- Disclaimer
This is bearutils, a collection of Pythonista scripts for working with Bear on iOS. It was inspired by the desire to make backlinks possible in combination with slow process of getting notes from Bear via the x-callback-url mechanism (the method used by other iOS Bear backlink generators), and quickly evolved into a framework for doing a variety of tasks with Bear, including:
- Adding backlinks
- Adding tables of contents
- Highlighting search terms
- Collecting links to notes with a given tag into a single note
- Appending or prepending text to note titles based on a tag
- Moving tags from the end of a note to the beginning
bearutils processes all or a subset of Bear notes. It loads the requested set of notes and runs a series of processors on them which accomplish various tasks, such as those described above.
bearutils works via a method similar to Andy Matuschak's note-link-janitor, which reads Bear's SQL database to make backlinks. Because there's no access to the filesystem in iOS, bearutils instead operates on a backup file exported from Bear. This method is very fast, and has the extra advantage of ensuring you have a current backup should something go horribly wrong when running the program! bearutils extracts the notes from a Bear backup file and then performs actions.
For maximum safety, bearutils uses the Bear API to make any changes to notes. This could potentially change in a future release, but would the require manually importing a modified backup file.
Although bearutils gains its speed by reading a backup rather than using Bear's API to read each note individually, there is one circumstance where it must fetch a note from Bear rather than using the backup. This is when the note has an attachment such as an image. In this case, the backed-up note doesn't contain the information needed to reference the attachment when saving the modified note to Bear, so bearutils must request the note via the API to get this information. It only does so, however, when a processor makes changes to a note.
Note that currently bearutils works only with the default Bear markdown style, not with actual Markdown.
First, you need Pythonista (app store link). Yes, it costs money. It's with it.
Next, you need bearutils. The easiest method is to download the zip file, expand it with the Files app, then share the folder with Pythonista ("External Files -> Open").
bearutils can work with all of the notes saved in Bear, or with a manually selected subset. Either way, you need to run bear.py. Do so by selecting it, then hitting the play button in the editor (you may need to hold down on the play button to force running in Python 3).
Global options for bearutils and the processors can be found in options.ini. Some processors can be configured via a special note titled "Beatitudes actions", which applies when working with all notes. When working with just one or a few notes, bearutils presents an options dialog.
If you just want to add a table of contents to a note or two, it might be irritating to have to export a backup. Instead, you can copy the note IDs from the notes you want bearutils to process. When launched, bearutils will detect the IDs on the clipboard and prompt you to use them or a Bear backup.
The downside of processing notes in this way is that bearutils must get each note via the Bear API, so it's really only practical for one or two notes.
Before launching bearutils, export a backup from Bear (Settings -> Import & export -> Backup all notes) and save it with the Files app. When you launch bearutils, pick "Select a Bear backup file" if prompted, and select your just-saved backup. bearutils will then run the actions configured in options.ini and the "Bearutils actions" note (see below).
bearutils features a number of built-in note processors. Some need to look at all of the notes (e.g., the backlink generator) and some can work on single notes (e.g., the table of contents generator).
The main reason for the existence of bearutils is to generate backlinks, so this is one of the actions. The backlink processor adds a Backlinks section to any note linked to by another.
This processor will search notes for a ## Table of contents heading and will update it with a list of links to headings within the note. It will also look for a ## TOC header as a shorthand placeholder.
Create a note with the title Bearutils actions (title configurable in options.ini). Make a bulleted list. Each bullet represents an action to take when bearutils processes all notes.
Available actions include the following. Any time a tag is used, you can surround it with backticks to prevent the Bearutils note from being tagged with that tag.
I like to use emoji to represent certain types of notes. You can do the following (actual examples):
- Append to titles in
#some tag/subtag#: 👍 - Prepend to titles in
#stuff: Hello - Remove from titles in
#things: 😂
Note that the last action, Remove, only removes from the beginning and end of titles.
Bear on iOS doesn't show search results within notes. bearutils will search your notes and highlight search term terms. You can do the following to search:
- ::search term:: in everywhere
- ::search term:: in
#tag - ::search term:: in [[Some note]]
You can later remove highlights by crossing them out;
- -::Found search term::- in everywhere
- -::Horses::- in [[Temp]]
It can be useful to collect links to all notes with a given tag, for example in using the Zettelkasten method. The Collect action will find all notes with a given tag and add them to the specified note, but only if they aren't already linked in that note:
- Collect
#topics/metamaterials#in [[§ Metamaterials]]
The file options.ini controls how bearutils works. It uses Python's configparser module. The [Processors] section defines what to do when either a few notes are to be processed (i.e., from copied note IDs) or when all notes are processed from a backup. The other sections are options for each processor.
The options file is commented and should be reasonably self-explanatory.
bearutils is designed to be modular and easy to extend by writing new processors. Processors should subclass processors.notes_processor and are required to implement two methods: process () and render ().
The first method, process (), determines which of the passed notes will be changed, while render() returns those changes. The reason for this structure is that the Bear backup file does not include the UUID for attachments to a note (e.g., images), so bearutils has to fetch the note directly from Bear using the API to be able to preserve attachments when it saves changes.
See notes_processor.py and the processors in processors/ for more details.
bearutils is a personal project, written entirely on an iPad with my thumb while a baby slept in my lap, and will probably delete all of your notes, corrupt your hard drive, steal your dog, and eat the last cookie. Back up everything all the time. Feel free to send pull requests with tabs, not spaces, and proper comments.