{"id":13395441,"url":"https://github.com/sirupsen/zk","last_synced_at":"2025-04-05T03:12:20.422Z","repository":{"id":41546585,"uuid":"262033983","full_name":"sirupsen/zk","owner":"sirupsen","description":"Zettelkasten on the command-line 📚 🔍","archived":false,"fork":false,"pushed_at":"2022-04-17T10:44:03.000Z","size":55,"stargazers_count":588,"open_issues_count":3,"forks_count":25,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-03-29T02:08:40.428Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sirupsen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-07T11:39:50.000Z","updated_at":"2025-03-28T22:28:11.000Z","dependencies_parsed_at":"2022-07-07T15:28:07.077Z","dependency_job_id":null,"html_url":"https://github.com/sirupsen/zk","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sirupsen%2Fzk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sirupsen%2Fzk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sirupsen%2Fzk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sirupsen%2Fzk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sirupsen","download_url":"https://codeload.github.com/sirupsen/zk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280272,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T17:01:58.822Z","updated_at":"2025-04-05T03:12:20.404Z","avatar_url":"https://github.com/sirupsen.png","language":"Ruby","funding_links":[],"categories":["Ruby","others","Happy Exploring 🤘"],"sub_categories":[],"readme":"# zk\n\nStupid-fast plain-text Zettelkasten (`zk`) built for (terminal) nerds. Heavily\nfeaturing `fzf`, `ripgrep`, `bat`, and `sqlite`.\n\nThe goal of the `zk` repository is to collect scripts and configurations for\nother plain-text Zettelkasten users.\n\n**Note:** This is an on-going extraction from my local environment, but has the\nutilities I use by far the most often. I can almost guarantee you you're going\nto run into a stacktrace somewhere because of some utility that isn't installed,\netc. Please open PRs/issues if it's not working, or you have questions,\nconcerns, comments. I'd also love contributions of scripts to `bin/`, such as\nshowing related notes, polish to search, Vim configs, etc.\n\nIf you are looking for something slightly more complete that retains the\nMarkdown-nature, you should take a look at [Obsidian][2]. After switching\nnote-taking system every year for years, I am no longer interested in custom\nsoftware and will stick to time-tested utilities.\n\n![](https://pbs.twimg.com/media/EQGYhAJUYAEPC4j?format=jpg\u0026name=4096x4096)\n\nIn this `screenshot`, we have `zks` running in the top-right, `zkt` in the\nbottom-right, and `vim` in the left pane. `zk` can be used without `tmux`, but\nit's recommended to use `tmux`.\n\n## Usage\n\nThe scripts assumes `$ZK_PATH` is set to your Zettelkasten directory. Your\nZettelkasten are markdown files in this directory. Nesting is presently not\nsupported.  Each note must have a 12-number prefix (date note was created), e.g.\n`202005050837 Monkey Ladder.md`. It's recommended to do some kind of backup,\ne.g. Dropbox/iCloud/...\n\nYour `zk` Zettelkasten is designed to be edited with your favourite editor.\nCurrently `zk` only supports Vim natively. `zk` augments your editor with\nvarious scripts to help extract further value.\n\n`zk`. Open `vim` in the left pane, and `zks` in the right pane. Your\nlaunch-point!\n\n`zks`. `fzf`-enabled full-text search (top-right pane in screenshot above) over\nall your notes, using `sqlite`. The index updates automatically based on file\nmodification. See the `FZF_DEFAULT_OPTS` below for various key-bindings you can\nuse to open splits in Vim, copy to clipboard, etc.  directly from here. `Alt-S`\nwill find similar notes with `zksim`.\n\n`zksim`. Finds similar notes to the note passed as an argument. See [#1][1] for\nmore.\n\n`zkt`. `fzf`-enabled tag browser. Pressing enter on a tag will show you notes\nwith that tag.  notes, using `sqlite`. See the `FZF_DEFAULT_OPTS` below for\nvarious key-bindings you can use to open splits, copy to clipboard, etc.\ndirectly from here.\n\n`zkt-raw`. Raw list of tags sorted by totals. Useful for other analysis. Used by\n`zkt`.\n\n`zkn`. Create a new note, with an appropriate prefix.\n\n`zk-assets-localize`. Given a file, downloads/copies the markdown images to `media/`.\n\n`zk-backlinks`. Adds back-links to each note. I.e., if A links to B, but B\ndoesn't link to A, then it'll append `Backlink: [[A]]` to B.\n\n`zkrt`/`zk-related-tags`. Finds tags related to the ones in the passed file. You can\npass `-t` to see a tree of tags.\n\n## Installation\n\nClone `zk` and add `bin/` to your `$PATH`:\n\n```\n$ git clone https://github.com/sirupsen/zk.git ~/zk\n$ echo 'export PATH=$PATH:$HOME/zk/bin' \u003e\u003e ~/.bashrc\n$ echo 'export ZK_PATH=\"$HOME/Zettelkasten\"' \u003e\u003e ~/.bashrc\n```\n\nInstall the dependencies with your package manager.\n\nMacOS:\n```bash\n# brew install ripgrep fzf sqlite3 bat\n# gem install sqlite3\n```\n\nLinux:\n\n`build-essential`,`libsqlite3-dev` and `ruby-dev` are needed to install the sqlite3 gem. For example—on Debian/Ubuntu, run:\n```bash\n# apt install ripgrep fzf sqlite3 bat build-essential libsqlite3-dev ruby ruby-dev\n# gem install sqlite3\n```\n\nFor **Vim**, browse through my Vim config\n[this](https://github.com/sirupsen/dotfiles/blob/master/home/.vimrc) to add a\n`:Note`, shortcut for tags, auto-completing other notes after typing `[[`, etc.\nAnother function to look at is `:GPT`, which will take your range and send it to\nGPT3 for completion. Very cool for a perspective! One day this'll be a plugin\nthat's easier to install.\n\nIf you're using `fzf` with `vim`, it's recommended to add this to your `bash`\nconfiguration. It adds super useful key-bindings to open files in splits\n(`Ctrl-X`/`Ctrl-V`) from `zkt` and `zks` directly. It also adds `Ctrl-O` to\ninsert the file-name of whatever you're hovering into Vim, which is handy for\nlinks!:\n\n```bash\nexport FZF_DEFAULT_OPTS=\"--height=40% --multi --tiebreak=begin \\\n  --bind 'ctrl-y:execute-silent(echo {} | pbcopy)' \\\n  --bind 'alt-down:preview-down,alt-up:preview-up' \\\n  --bind \\\"ctrl-v:execute-silent[ \\\n    tmux send-keys -t \\{left\\} Escape :vs Space \u0026\u0026 \\\n    tmux send-keys -t \\{left\\} -l {} \u0026\u0026 \\\n    tmux send-keys -t \\{left\\} Enter \\\n  ]\\\"\n  --bind \\\"ctrl-x:execute-silent[ \\\n    tmux send-keys -t \\{left\\} Escape :sp Space \u0026\u0026 \\\n    tmux send-keys -t \\{left\\} -l {} \u0026\u0026 \\\n    tmux send-keys -t \\{left\\} Enter \\\n  ]\\\"\n  --bind \\\"ctrl-o:execute-silent[ \\\n    tmux send-keys -t \\{left\\} Escape :read Space ! Space echo Space \u0026\u0026 \\\n    tmux send-keys -t \\{left\\} -l \\\\\\\"{}\\\\\\\" \u0026\u0026 \\\n    tmux send-keys -t \\{left\\} Enter \\\n  ]\\\"\"\n```\n\n## Syncing\n\nI recommend storing the notes in iCloud/Google Drive/Dropbox or whatever you use\nto normally sync files. Nice and simple. Some people store them in Git.\n\n[1]: https://github.com/sirupsen/zk/pull/1\n[2]: https://obsidian.md/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsirupsen%2Fzk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsirupsen%2Fzk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsirupsen%2Fzk/lists"}