~gpanders/wk

wk/README.md -rw-r--r-- 3.2 KiB
4f358b1aGregory Anders Import std.io in main.zig a month ago
                                                                                
effb62c9 Greg Anders
d68709c7 Greg Anders
effb62c9 Greg Anders
d68709c7 Greg Anders
34e7a98f Greg Anders
34e7a98f Greg Anders
d68709c7 Greg Anders
b0f73a80 Greg Anders
d68709c7 Greg Anders
b0f73a80 Greg Anders
d68709c7 Greg Anders
b0f73a80 Greg Anders
6e91c771 Greg Anders
15326132 Greg Anders
effb62c9 Greg Anders
15326132 Greg Anders
b0f73a80 Greg Anders
d68709c7 Greg Anders
c7f43670 Greg Anders
effb62c9 Greg Anders
d68709c7 Greg Anders
6e91c771 Greg Anders
d68709c7 Greg Anders
effb62c9 Greg Anders
d68709c7 Greg Anders
6e91c771 Greg Anders
d68709c7 Greg Anders
6e91c771 Greg Anders
d68709c7 Greg Anders
effb62c9 Greg Anders
15326132 Greg Anders
6e91c771 Greg Anders
15326132 Greg Anders
effb62c9 Greg Anders
15326132 Greg Anders
6e91c771 Greg Anders
effb62c9 Greg Anders
6e91c771 Greg Anders
4eee30fc Greg Anders
effb62c9 Greg Anders
4eee30fc Greg Anders
effb62c9 Greg Anders
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
wk
==

Command line tool to manage a personal wiki, written in [zig][].

[zig]: https://ziglang.org

Introduction
------------

`wk` is a command line tool to manage a personal wiki. By design, the wiki is
minimal and made up of simple plain text files. It is designed to be used
solely in the terminal (it has no GUI or web interface) and to be synchronized
using external tools (e.g. version control or a syncing service such as
Nextcloud or Syncthing).

New wiki pages are given a `.md` extension, although there is nothing enforcing
that they be written in Markdown syntax. New pages are also given a YAML
metadata template, which is used by `wk` to extract the wiki page title and
tags, which is used by various subcommands.

Example:

```markdown
---
title: Some wiki page
date: July 26, 2020
tags: example
---

This is an example of a wiki page.
```

All new pages are given a unique ID, which is prepended to its filename. This
ID is displayed in the various `wk` commands. Pages can be linked together
using these IDs.

See examples [here][examples].

[examples]: https://git.sr.ht/~gpanders/wiki/tree

Installation
------------

Download and extract a [release] to the location of your choosing.

[release]: https://git.sr.ht/~gpanders/wk/refs

### Homebrew

If you use macOS and Homebrew you can use

    brew install --HEAD gpanders/tap/wk

### Build from source

Install [zig]. After cloning this repository, build `wk` with

    make

This will build `wk` under `zig-cache/bin/`. You can install `wk` using

    make install

By default, this installs to `/usr/local/bin/`. To install to a different
location, set the `prefix` variable. For example, to install under
`$HOME/.local/bin/` use

    make prefix=$HOME/.local install

Usage
-----

Notes are stored in the directory represented by the environment variable
`$WIKI_DIR`. If `$WIKI_DIR` is unset, it defaults to `$HOME/.local/share/wk/`.

Notes are created with

    wk new TITLE

The file name of the new note will be the given title prepended with a unique
ID and a `.md` extension. The title can contain spaces, but be sure to wrap it
in quotes so your shell doesn't split it.

To list all of your existing notes, use

    wk list

This will print the title of each existing note along with its ID.

For a full list of available commands, use `wk help`. For more information on
a specific command, use `wk help COMMAND`.

For commands that take arguments, the argument can be a note ID, title, or file
name (with or without the extension) of an existing note. The output of any
`wk` command can be used with other commands, allowing commands to be
composed. For example, to open all notes containing the tag "foo", use

    wk tag foo | wk open

Most commands can be abbreviated. Use `wk help CMD` for more information.

Editor Integration
------------------

### Vim

This repo includes a Vim plugin in the `contrib/vim/` directory. This plugin adds
some useful features to Vim that makes working in your personal wiki a bit
easier. Notably, it sets the `include` and `includeexpr` options, allowing you
to use Vim's `gf` and `include-search` features (use `:h gf` and `:h
include-search` in Vim for more info). The plugin also enables autocompletion
of tags and wiki IDs through the `completefunc` option.