A personal knowledge base & note-taking utility.

Goals:

• Notes stored in plain-text Markdown files, with the filesystem being the source of truth.
• Support both general-purpose notes (e.g. a todo list) as well as long-term knowledge retention.
• Provide a simple CLI that can be used to build custom workflows.

Run just build and add the resulting pkb binary somewhere to your path.

Notes can be created using pkb new <title> [content]. All notes must have a title but providing initial content is optional. The --id flag can be passed to specify a human-readable ID (such as TODO), otherwise a random ID will be generated to ensure the filename is unique and links will not break if the title of the note is changed. The --edit flag can be passed to open the new note in your $EDITOR after it is created.

Notes managed by pkb can be listed using the pkb list command. The output is a tab-separated list of IDs with their corresponding titles.

Notes can be updated interactively using pkb edit <id>, which will open the note in your $EDITOR. Content can also be appended to notes using pkb append <id> <content> to update a note noniteractively.

Notes can be viewed using an external program using pkb view <id>. The external viewer is configurable in the config file.

Pkb can be configured with a YAML file at $XDG_CONFIG_HOME/pkb/config.yaml (on most systems this is ~/.config/pkb/config.yaml). The following options are supported:

# Path where notes should be stored (default '$HOME/notes').
directory: 'some/other/path'
# Editor to use when editing notes (default '$EDITOR').
editor: nvim
# Extension for the note files (default 'md').
extension: mkdn
# Template to use when creating a new note. This must be a valid Golang text template (https://godocs.io/text/template).
# The title and content are available for use in the template under the `.title` and `.content` keys, and a `toYaml`
# function is provided for serializing values to YAML.
# This tool expects that the notes contain YAML frontmatter containing a `title` key.
template: |-
  ---
  title: {{ .title | toYaml }}
  ---
  {{ with .content }}{{ . }}
  {{ end }}
# External program to use when viewing notes (default 'less').
viewer: bat

A custom pkb completion file for the fish shell. This can be installed to ~/.config/fish/completions to enable tab-completion for commands and note IDs.

Basic Neovim plugin; currently supports inserting links between notes and folding the frontmatter for a nicer editing experience. The pkb.lua file can be installed to ~/.local/share/nvim/site/lua, then add to your init.lua:

-- The following setup options are defaults and do not need to be specified unless you want to customize them.
require("pkb").setup({
	directory = vim.fn.expand("$HOME/notes"),
	extension = "md"
})

When editing a note using pkb edit, the PkbInsertLink command can be used either in normal or visual mode to link to a note.

Since pkb operates on plain-text files, file-synchronization tools such as Syncthing or Nextcloud should work out of the box to provide multi-device support.

Any Markdown editor for Android will work as long as it can operate on the local filesystem. Markor in particular can parse the title frontmatter to provide additional styling when reading notes in the Viewer mode. Note that since note IDs are autogenerated for most notes, it may be difficult to find notes if the editor does not have full-text support.