{"id":15374690,"url":"https://github.com/mrtazz/vim-plan","last_synced_at":"2025-04-15T15:12:36.602Z","repository":{"id":39890591,"uuid":"120673639","full_name":"mrtazz/vim-plan","owner":"mrtazz","description":"experiments in a vim plugin for personal planning","archived":false,"fork":false,"pushed_at":"2024-04-17T14:04:59.000Z","size":45,"stargazers_count":8,"open_issues_count":9,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-15T15:12:28.284Z","etag":null,"topics":["planning","plugin","vim","vim-plugin"],"latest_commit_sha":null,"homepage":"","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrtazz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-02-07T21:25:38.000Z","updated_at":"2024-05-10T16:58:15.000Z","dependencies_parsed_at":"2023-10-11T16:56:13.119Z","dependency_job_id":null,"html_url":"https://github.com/mrtazz/vim-plan","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/mrtazz%2Fvim-plan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrtazz%2Fvim-plan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrtazz%2Fvim-plan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrtazz%2Fvim-plan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrtazz","download_url":"https://codeload.github.com/mrtazz/vim-plan/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249094933,"owners_count":21211837,"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":["planning","plugin","vim","vim-plugin"],"created_at":"2024-10-01T13:59:31.193Z","updated_at":"2025-04-15T15:12:36.583Z","avatar_url":"https://github.com/mrtazz.png","language":"Vim Script","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vim-plan\n\nVIM plugin that supports my planning and note taking workflow.\n\n## Overview\n\n## Usage\n\nThis plugin provides a handful of helper functions to organize a directory of\nnotes. The general setup is that there are at least 2 different directories.\nOne for generic notes (by default `notes/`) and one for daily notes (by\ndefault `dailies/`). This workflow is heavily inspired by tools like\n[Obsidian][obsidian] and [NotePlan][noteplan] and should be in large parts\ncompatible.\n\nHelper functions are by default mapped to commands but not mapped to any\nkeybindings to not clash with any existing mappings:\n\n```\ncommand! PlanDaily :call plan#OpenDailyNote()\ncommand! PlanNote :call plan#OpenNote()\ncommand! PlanMarkDone :call plan#MarkDone()\ncommand! PlanMarkCanceled :call plan#MarkCanceled()\ncommand! PlanMigrateToToday :call plan#MigrateToToday()\ncommand! -nargs=1 PlanImportAsset :call plan#ImportAsset(\u003cq-args\u003e)\n```\n\n### Syntax\nvim-plan uses the `conceal` feature to show todos in a visually different way\nto make it easier to quickly scan notes for todos. It suppports 4 different\nstates of todos:\n\n```\n- [ ] an open task\n- [x] a completed task\n- [-] a cancelled task\n- [\u003e] a moved task\n```\n\nwhich will look like this as long as the cursor isn't on the line:\n\n```\n⭕️ an open task\n✅ a completed task\n❎ a cancelled task\n🔜 a moved task\n```\n\nThis only works if vim is compiled with `conceal` support and utf-8 encoding.\nThis is how it looks like in MacVim:\n\n![screen recording of conceal feature](https://github.com/mrtazz/vim-plan/assets/68183/5062d1c3-f487-4de4-86f2-e83b9ec11030)\n\n\n### TODOs in location window\nThe plugin provides a command `:PlanFindTodos` that uses `:lgrep` to find the\npattern `- [ ] ` in the dailies and notes directories and shows the results in\na location window for the buffer to select and jump to. I'm using it with\n[rg](https://github.com/BurntSushi/ripgrep) via the following `.vimrc`\nsetting, to show me the newest daily notes first:\n\n```\n\" set rg as grep program\nset grepprg=rg\\ --vimgrep\\ --no-heading\\ --smart-case\\ --sortr=path\n```\n\n### Autosaving of notes\nNotes are saved periodically when the cursor is idle (in both normal and\ninsert mode) and also on leaving a buffer.\n\n\n### Templating\nWhen opening a file that doesn't exist yet, vim-plan reads a template folder\nto figure out if there is a template set for the file type. This is very\nsimilar to how [vim-stencil][vim_stencil] works. Valid template files are\n`daily` or `note`.\n\nWhen reading those templates in vim-plan will replace the following template\nvariables inline:\n\n- `%%DATE%%` with the current date of the format mm/dd/yyyy\n- `%%DATE_8601%%` with the current date of the format yyyy/mm/dd\n- `%%WEEKDAY%%` with the name of weekday\n- `%%WEEKNUMBER%%` with the number of the week\n- `%%YEAR%%` with the current year yyyy\n- `%%MONTH%%` with the name of the current month\n\n### Useful shell commands\n\nI complement this workflow with a couple of shell commands I run from a\nMakefile in my notes repository:\n\n```make\n\nTODAY := $(shell date \"+%Y%m%d\")\nTODAY_ATTACHMENTS := ./dailies/$(TODAY)_attachments\n\n$(TODAY_ATTACHMENTS):\n\tinstall -d $@\n\n# this is run from Hazel on macos to sync screenshots to a daily attachments\n# folder for my daily note\n.PHONY: sync-screenshots-to-today\nsync-screenshots-to-today: $(TODAY_ATTACHMENTS)\n\tmv ~/Desktop/Screenshot*.png $\u003c\n\n# this is useful to find images I imported but never linked in any notes\n.PHONY: find-unlinked-images\nfind-unlinked-images:\n\t@find dailies -type f -name \"*.png\" | sort | while read img ; do grep -q \"$$(basename \"$$img\")\" -R dailies notes || echo \"Image: $$img not linked in any notes\" ; done\n\n# get a list of all open todos\n.PHONY: find-todos\nfind-todos:\n\t@rg --sort path '\\- \\[ \\]' dailies notes\n\n# get a list of notes tagged with something (#fr in this case)\n.PHONY: recent-fr-tasks\nrecent-fr-tasks:\n\t@rg --sort path '#fr' dailies notes\n\n# generate tags, see below for ctag definitions I use\n.PHONY: tags\ntags:\n\tctags -R .\n\n```\n\n### Tags\nI use a small addition to the normal ctags definitions mostly to be able to\ntab complete @usernames in vim:\n\n```\n% cat .ctags.d/md.ctags\n--langdef=markdowntags\n--languages=markdowntags\n--langmap=markdowntags:.md\n--kinddef-markdowntags=t,tag,tags\n--mline-regex-markdowntags=/(^|[[:space:]])@(\\w\\S*)/\\2/t/{mgroup=1}\n```\n\nIn my notes repo I have a nightly action that updates tags which makes it really easy\nto have completion of notes with about a day or so delay:\n\n```\nname: update-tags\n\non:\n  workflow_dispatch:\n  schedule:\n    # run every weekday morning\n    - cron: '30 3 * * 1-5'\n\njobs:\n  update:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v2\n\n      - name: dependencies\n        run:  sudo apt-get install universal-ctags\n\n      - name: generate tags\n        run: make tags\n\n      - name: commit and push changes\n        run: |\n          git config user.name Github Actions\n          git config user.email actions@noreply.github.com\n          git add tags\n          git commit --allow-empty -m \"update tags\"\n          git push\n```\n\n### Additional tooling\nThere is a commandline tool [`plan`](https://github.com/mrtazz/plan) which provides some additional\nsupport tooling mostly around automation. For example I run this Action every weekday morning to\nprep my daily note with some information:\n\n```\nname: daily-prep\n\non:\n  workflow_dispatch:\n  schedule:\n    # run every weekday morning\n    - cron: '30 5 * * 1-5'\n\njobs:\n  update:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v2\n\n      - name: populate daily note\n        run:  make prepare-the-day\n        env:\n          ISSUES_TOKEN_GITHUB: ${{ secrets.ISSUES_TOKEN_GITHUB }}\n\n      - name: commit and push changes\n        run: |\n          git config user.name Github Actions\n          git config user.email actions@noreply.github.com\n          git add dailies\n          git commit -m \"create daily note\"\n          git push\n```\n\n## Configuration\nThere are a couple of variables that can be set to customize mostly file\nlocations:\n\n```vimscript\n\" base dor for all notes\nlet g:PlanBaseDir = get(g:, 'PlanBaseDir', $HOME . \"/.plan\")\n\" template dir relative to base dir\nlet g:PlanTemplateDir = get(g:, 'PlanTemplatePath', \"templates\")\n\" daily notes dir relative to base dir\nlet g:PlanDailiesDir = get(g:, 'PlanTemplatePath', \"dailies\")\n\" generic notes dir relative to base dir\nlet g:PlanNotesDir = get(g:, 'PlanTemplatePath', \"notes\")\n\" allow user to append a title to default note file name\n\" set to 0 or omit to disable adding a title to notes\nlet g:PlanPromptForTitle = get(g:, 'PlanPromptForTitle', 1)\n\" the name of the directory relative to the current file to import assets to\nlet g:PlanAssetsDirectory = get(g:, 'PlanAssetsDirectory', \"assets\")\n```\n\n## See also\n- [vim-stencil][vim_stencil]\n\n[vim_stencil]: https://github.com/mrtazz/vim-stencil\n[obsidian]: https://obsidian.md/\n[noteplan]: https://noteplan.co/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrtazz%2Fvim-plan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrtazz%2Fvim-plan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrtazz%2Fvim-plan/lists"}