Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sstallion/vimwiki-cli

Vimwiki Command-Line Interface
https://github.com/sstallion/vimwiki-cli

cli vim vimwiki wiki

Last synced: 3 months ago
JSON representation

Vimwiki Command-Line Interface

Host: GitHub
URL: https://github.com/sstallion/vimwiki-cli
Owner: sstallion
License: bsd-2-clause
Created: 2021-04-19T00:25:32.000Z (almost 4 years ago)
Default Branch: master
Last Pushed: 2024-02-12T18:44:27.000Z (12 months ago)
Last Synced: 2024-11-06T06:49:22.054Z (3 months ago)
Topics: cli, vim, vimwiki, wiki
Language: Python
Homepage:
Size: 72.3 KB
Stars: 16
Watchers: 4
Forks: 3
Open Issues: 6
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

README

        # Vimwiki Command-Line Interface

[![](https://github.com/sstallion/vimwiki-cli/actions/workflows/ci.yml/badge.svg?branch=master)][1]

[![](https://img.shields.io/pypi/v/vimwiki-cli)][2]

[![](https://img.shields.io/pypi/pyversions/vimwiki-cli)][2]

[![](https://img.shields.io/github/license/sstallion/vimwiki-cli)][3]

`vimwiki-cli` is a command-line interface to [Vimwiki][4], a plugin for the

[Vim][5] 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.

[![](https://asciinema.org/a/413921.svg)](https://asciinema.org/a/413921?autoplay=1)

## Installation

`vimwiki-cli` is available on [PyPI][2] 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][6] to `.git/hooks/pre-commit`

in the wiki directory. Alternatively, if [pre-commit][8] 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.

```yaml

# 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][7] for more details.

## License

Source code in this repository is licensed under a Simplified BSD License. See

[LICENSE][3] for more details.

[1]: https://github.com/sstallion/vimwiki-cli/actions/workflows/ci.yml

[2]: https://pypi.org/project/vimwiki-cli/

[3]: https://github.com/sstallion/vimwiki-cli/blob/master/LICENSE

[4]: https://vimwiki.github.io/

[5]: https://www.vim.org/

[6]: https://github.com/sstallion/vimwiki-cli/blob/master/scripts/pre-commit.sh

[7]: https://github.com/sstallion/vimwiki-cli/blob/master/CONTRIBUTING.md

[8]: https://pre-commit.com/index