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.
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.
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. |
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 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
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-cliPull requests are welcome! See CONTRIBUTING.md for more details.
Source code in this repository is licensed under a Simplified BSD License. See LICENSE for more details.