A Guide to Using panvimwiki for Filtering and Converting Vimwiki Notes

Panvimwiki is a powerful tool that enables you to filter and convert your Vimwiki notes using pandoc. Whether you need to convert your notes to Microsoft Word docx or any other output format supported by Pandoc, panvimwiki has got you covered. In this article, we will explore the features, installation process, usage, and configuration settings of panvimwiki, as well as introduce some useful pre-filters and pandoc filters that can enhance your workflow.

Installation

Before you can start using panvimwiki, you need to have Pandoc installed on your system. It is recommended to install Pandoc using conda, as the system version might be outdated. Alternatively, you can download Pandoc from the official website.

To install panvimwiki, follow these steps:

1. Open a bash shell.
2. Choose a destination directory for the installation. For example, you can use $HOME/.vim/pack/vimwiki/opt/panvimwiki.
3. Clone the panvimwiki repository using the following command: git clone https://github.com/jfishe/panvimwiki.git "<destination_directory>".
4. Activate the Python environment used by Vim.
5. Install the panvimwiki Python package using the command: python -m pip install "<destination_directory>".

If you are using Vim 8 with native packages, make sure to install panvimwiki in the pack/*/opt/panvimwiki directory. However, if your Vim version is compiled with Python 3, you can also install panvimwiki in pack/*/start/panvimwiki.

Usage

Command Line Shell

Panvimwiki provides both command line tools and Vim commands for easy usage. Let’s first look at the command line tools.

To filter and convert Vimwiki notes using panvimwiki from the command line, you can use plain text pre-filters and pandoc filters. Here’s an example:

#bash
cat $HOME/vimwiki/diary/* |
    delete_bullet_star |
    delete_task_pending |
pandoc --from=vimwiki --to=markdown \
    --filter=delete_tag_lines \
    --filter=delete_taskwiki_heading \
    --filter=delete_empty_heading

The example above demonstrates how to concatenate and convert Diary Notes or any other Vimwiki note using pre-filters like delete_bullet_star and delete_task_pending, as well as pandoc filters like delete_tag_lines, delete_taskwiki_heading, and delete_empty_heading.

Vim Commands

Panvimwiki also provides Vim commands to convert Vimwiki notes. Here are some useful commands:

• VimwikiConvert[!]: Converts the current Vimwiki buffer to the selected output format specified in the configuration settings. Use ! to open the converted file with the default viewer.

• VimwikiConvertWeek[!]: Concatenates the DiaryNotes for Monday through the current buffer and converts them. Use ! to open the converted file with the default viewer.

• VimwikiReference: If you are working with markdown format, pandoc reads the current buffer with citeproc references to a BibLaTeX or other supported database, and appends reference links and the complete citation according to the default citation style language (CSL).

Settings

Panvimwiki provides global settings that allow you to customize the behavior of the tool. You can add the following settings to your ~/.vim/plugin/vimwiki.vim file to configure panvimwiki:

#vim
let g:panvimwiki_settings = {
      \ 'extra_args': [ '--shift-heading-level-by', '1',
      \ '--data-dir', '~/vimwiki_html/templates/'
      \ ],
      \ 'format': 'docx'
      \ }

In the example above, the extra_args parameter allows you to pass additional arguments to Pandoc during conversion. The format parameter sets the default output format to docx. Feel free to customize these settings according to your needs.

Pre-Filters and Pandoc Filters

Panvimwiki provides a set of pre-filters and pandoc filters that can help you enhance your workflow. Here are some notable ones:

• delete_bullet_star: Removes unordered lists that use the star (asterisk) bullet marker.

• delete_task_pending: Deletes pending tasks.

• delete_tag_lines: Deletes lines that only contain Vimwiki tags.

• delete_empty_heading: Removes headings that do not have any children or paragraphs.

• delete_taskwiki_heading: Removes taskwiki headings.

These filters can be combined in various ways to filter and convert your Vimwiki notes more effectively.

Conclusion

With panvimwiki, filtering and converting Vimwiki notes using pandoc becomes a breeze. In this article, we explored the installation process, usage, and configuration settings of panvimwiki, as well as introduced some pre-filters and pandoc filters that can enhance your workflow. Now you can take your Vimwiki notes to the next level and easily convert them to various formats. Happy note-taking!

Note: This project was generated with PyScaffold 4.5.

Image Source: None