pkb

README

pkb

Personal Knowledge Base

Config driven CLI to manage the notes and documents that make up your personal knowledge base.

Contents

• Why?
• Install
  • Download from GitHub
  • Build it locally
• Commands
• Configuration
  • Schema
  • Expanding values in templates
  • Custom file name formats
  • Selecting an output directory
• Using with Obsidian

Why?

I use Obsidian for reading/reviewing and minor updates but don't enjoy writing content there as much as I do in Neovim.

I'm more likely to keep good notes and actually maintain documents if the editing is done in Neovim rather than having to launch a specific app every time I need to jot something down.

pkb is designed to be terminal first so you can create and edit documents where you are most comfortable, but is fully compatible with Obsidian. See using with Obsidian for specifics on how to set them up to work together in perfect harmony.

Don't use Obsidian for your own knowledge base? pkb is just creating markdown documents from templates, so it's probably compatible with whatever you are using! If it's not but you would like it to be just raise an issue and I'll see what I can do 🤞.

Install

Download from GitHub

Find the latest version for your system on the GitHub releases page.

Build it locally

If you have go installed, you can clone this repo and run:

make install

This will build the binary and then copy it to /usr/bin/pkb so it will be available on your path. Nothing more to it.

Commands

Run pkb --help for a full, up to date list of available commands.

new

Create a new note/file from your defined templates.

You will be prompted to select the template (and if defined, any sub templates) then the file will be opened in the editor specified in your config file.

Don't want to edit it right now? Just use --no-edit. The file will still be created, just not opened.

edit

Open your editor in your notes directory.

Want to pick a specific file through pkb rather than in your editor? Use the --pick flag to select the specific file then open it for editing.

copy

Copy the contents of a file to your system clipboard.

Useful if you want to write up notes about something in your editor, but then need to share them somewhere for other people to read.

Coming soon: even more things to simplify your knowledge base management.

Configuration

Config driven means you control how pkb works with the options in a config file.

By default pkb checks for the config file in your $XDG_CONFIG_DIR, or $HOME/.config.

Schema

You can see an example of the config file format in the example.config.json in the schema directory. Make sure you add the $schema keyword to the top of your config file to for in editor validation and descriptions of what fields are used for.

Expanding values in templates

The following values will be automatically expanded in templates:

• {{.CustomDateFormat}} - the current date in a custom format specified in the template config. This must be a valid golang date format, with the exception of day suffixes (e.g. 1st, 3rd etc). If your format contains a day suffix this will be be handled so the suffix is correctly displayed. The format string needs to be included in the template config to be able to use a custom date format.
• {{.Date}} - the current date in the format YYYY-MM-DD.
• {{.Name}} - the name of the created document.
• {{.Time}} - the time the file was created in the format HH:MM.
• {{.Week}} - the current week number.
• {{.Year}} - the current year.

Custom file name formats

By default when you create a new file from a template you will be prompted to enter the name value, however you can customise with name_format.

The following values are currently supported:

• {{.Date}} - the current date in the format YYYY-MM-DD.
• {{.Prompt}} - prompt for user input.
• {{.Week}} - the current week number.
• {{.Year}} - the current year.

You can combine the supported formats to use them together, e.g.:

"name_format": "{{.Date}}-{{.Prompt}}"

In this example the document would be created with the current date then the value you typed in the prompt, e.g. 2022-09-19-typed-value.md.

Selecting an output directory

If you don't want to hard code the output directory in your config you can use the dynamic values to prompt you for input at time of creation.

The following values are currently supported:

• {{.Prompt}} - will let you type in a new directory name. If the directory does not already exist it will be created.
• {{.Select}} - select from existing directories inside the parent.

Using with Obsidian

To get the best out of pkb and Obsidian, you just need to tell them to both look in the same place for your files.

If you already have an Obsidian vault just set the directory in your pkb config file to the same location.

pkb will expect templates to be in a directory called .templates in the location you specified as the directory in your config. You can make sure Obsidian is using the same location by going to Settings > Templates and setting the Template folder location value.

Documentation

Overview

Package main is the entrypoint for the CLI.