sstallion / vimwiki-cli

Vimwiki Command-Line Interface

Vimwiki Command-Line Interface

vimwiki-cli is a command-line interface to Vimwiki, a plugin for the Vim text editor. It provides a front-end for interactive editor commands and can be used to automate repetitive tasks such as rebuilding tag metadata and generating links, all from the command line.

Installation

vimwiki-cli is available on PyPI and can be installed locally using the Python Package Installer:

$ python -m pip install --user vimwiki-cli

Once installed, issue vimwiki --help to see usage.

Configuration

For most installations no configuration is needed, however several environment variables are available to modify default behavior without the need to pass global options on the command line:

Environment Variable	Global Option	Description
VIMWIKI_EDITOR	--editor	Editor to launch, defaults to $EDITOR or vim.
VIMWIKI_COUNT	--count	Index of wiki to open.
VIMWIKI_SELECT	--select	Select wiki from interactive list.
VIMWIKI_OPEN_MATCHES	--open-matches	Open search results by default.
VIMWIKI_OPEN_TABS	--open-tabs	Open pages in a new tab by default.

Advanced

Supported Commands

Each CLI command corresponds to one or more Ex commands executed in the editor. The following table details the mapping between these commands:

CLI Command	Ex Commands
vimwiki	:VimwikiIndex
vimwiki all-html	:VimwikiIndex | VimwikiAll2HTML
vimwiki check-links	:VimwikiIndex | VimwikiCheckLinks
vimwiki diary	:VimwikiDiaryIndex
vimwiki diary generate-links	:VimwikiDiaryIndex | VimwikiDiaryGenerateLinks
vimwiki diary today	:VimwikiMakeDiaryNote
vimwiki diary tomorrow	:VimwikiMakeTomorrowDiaryNote
vimwiki diary yesterday	:VimwikiMakeYesterdayDiaryNote
vimwiki generate-links PAGE PATTERN	:VimwikiIndex | VimwikiGoto PAGE | VimwikiGenerateLinks PATTERN
vimwiki goto PAGE	:VimwikiIndex | VimwikiGoto PAGE
vimwiki help	:help vimwiki.txt | only
vimwiki search PATTERN	:VimwikiIndex | VimwikiSearch PATTERN
vimwiki tags generate-links PAGE TAGS	:VimwikiIndex | VimwikiGoto PAGE | VimwikiGenerateTagLinks TAGS
vimwiki tags rebuild	:VimwikiIndex | VimwikiRebuildTags
vimwiki tags search PATTERN	:VimwikiIndex | VimwikiSearchTags PATTERN

Shell Completion

Shell completion is available for bash, fish, and zsh shells. To generate an activation script, issue:

$ env _VIMWIKI_COMPLETE=source_$(basename $SHELL) vimwiki >/path/to/vimwiki-complete.sh

Once generated, the activation script may be sourced directly or from the shell startup file to provide completion:

$ . /path/to/vimwiki-complete.sh

Git Integration

For wikis managed with Git, a pre-commit hook script is available that executes non-interactive commands to rebuild tag metadata and generate links before commit.

The pre-commit hook relies on the following configuration options:

Configuration Option	Description
vimwiki.options	Extra options to pass to the vimwiki command
vimwiki.linkspage	Page which contains generated links
vimwiki.taglinkspage	Page which contains generated tag links
vimwiki.generatelinks	Generate links before commit (bool)
vimwiki.generatediarylinks	Generate diary links before commit (bool)
vimwiki.generatetaglinks	Generate tag links before commit (bool)
vimwiki.rebuildtags	Rebuild tag metadata before commit (bool)
vimwiki.allhtml	Convert wiki to HTML before commit (bool)

For example, to configure the hook to rebuild tag metadata and generate tag links in the Tags page before commit, issue:

$ git config vimwiki.taglinkspage Tags
$ git config vimwiki.generatetaglinks true
$ git config vimwiki.rebuildtags true

To enable the hook, copy or link pre-commit.sh to .git/hooks/pre-commit in the wiki directory. Alternatively, if pre-commit is installed, add a pre-commit configuration file, .pre-commit-config.yaml and run pre-commit autoupdate to enable the latest version of the hook.

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
  - repo: https://github.com/sstallion/vimwiki-cli
    rev: v1.1.0
    hooks:
      - id: vimwiki-cli

Contributing

Pull requests are welcome! See CONTRIBUTING.md for more details.

License

Source code in this repository is licensed under a Simplified BSD License. See LICENSE for more details.

vimwiki-cli's Issues

Support `:VimwikiBacklinks`

Support for displaying backlinks should be added to the new command group proposed by Issue #3.

Pages with spaces in name breaks `goto`

This appears to be an issue in Vimwiki itself; the :VimwikiGoto command takes <f-args> rather than <q-args>, which causes pages with spaces in the names to fail. Passing a quoted string to the command does not work as expected due to use of <f-args>. This will need to be fixed upstream - it may also be worth doing a quick evaluation to see if other commands have the same issue.

Support `+clientserver` editors

Editors compiled with the +clientserver option allows expressions to be sent remotely to an existing process. This would allow interactive vimwiki commands to open pages in a different window to leave the command-line free for other uses. It looks like the --remote-expr flag will be the most likely entry point, however there will be some complicating factors around detecting whether a server is running before execution as this flag does not seem to have the same behavior as the other --remote flags.

Distribute man page

A man page should be distributed that documents operation. The click-man package might be useful.

vimwiki diary today - fails when vim-startify is installed

the commands `vimwiki diary today, yesterday or tomorrow' don't make it past vim-startify, where the 2021-09-20.wiki filename is somehow lost.

That said, the command vimwiki diary lands neatly on the diary index, no startify problems.

I don't know if this is actually a vimwiki-cli issue, or a vim-startify issue, I'll experiment some.

Support `:VimwikiRebuildTags!` in `pre-commit.sh`

Currently, the pre-commit hook does have have support for passing the --all flag to vimwiki. This can cause issues if committing to a freshly cloned repository without existing tag metadata.

Simplify pre-commit hook installation

A command should be added to simplify installing scripts/pre-commit.sh to wikis managed by git.

Support HTML generation

Support for generating HTML as a non-interactive command should be added. This should most likely be added to scripts/pre-commit.sh as well.

Simplify shell completion support

Currently, users must generate activation scripts manually following the procedure documented by Click. This is somewhat inconvenient. Ideally, a command would be added similar to pip completion that detects the calling shell and outputs the appropriate activation script. The click-completion package might be useful.

Support `:VimwikiDeleteFile` and `:VimwikiRenameFile`

A new command group should be added to manage pages to support these commands.