reference-links: true

Filter and convert Vimwiki notes using pandoc

Introduction

Panvimwiki provides tools for conversion to Microsoft Word docx or other output formats supported by Pandoc Panvimwiki provides command line tools as well as Vim commands to concatenate and convert Diary Notes or convert any Vimwiki note.

Installation

Panvimwiki requires Pandoc. Installation with pixi is recommended because the system version, e.g., with Ubuntu, may be too old. Or download from the website. Pypandoc supports binary installation of pandoc.

Using the Vim 8 native packages, panvimwiki should install in pack/*/opt/panvimwiki because it depends on :python3 and requires installation of the python package panvimwiki.

From a bash shell, enter the following:

# Adjust dest to suit, e.g., $HOME/vimfiles/pack/vimwiki/opt/panvimwiki
dest="$HOME/.vim/pack/vimwiki/opt/panvimwiki"

git clone https://github.com/jfishe/panvimwiki.git "$dest"

# Activate the python environment used by Vim.
# Then install panvimwiki in that python environment.
python -m pip install "$dest"
# Or to install from pypi:
python -m pip install panvimwiki

Panvimwiki requires Vim compiled with Python 3, so add the following to vimrc prior to :filetype-plugin-on. See :packadd for an explanation. Otherwise, install panvimwiki in pack/*/start/panvimwiki.

if has('python3')
  packadd! panvimwiki
endif

Install Conquer of Completion (CoC) to use completion.

Usage

Completion

Conquer of Completion (CoC) can complete Vim-Zettel YAML header fields:

• type: note, literature, reference, or index.
• status: Create, Process, or Reviewed.

Refer to :h vim-zettel.txt, especially :h g:zettel_options.

Command Line Shell

Panvimwiki provides plain text pre-filters and pandoc filters for use from the command line.

For example from a bash prompt:

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

From python:

from pathlib import Path
from panvimwiki.convert import convert

PREFILTER = (
    "delete_bullet_star",
    "delete_task_pending",
)
FILTER = (
    "delete_tag_lines",
    "delete_empty_heading",
    "delete_taskwiki_heading",
)
EXTRA_ARGS = (
    "--shift-heading-level-by",
    "1",
    "--data-dir",
    str(Path.home() / "vimwiki_html/templates"),
)

convert(
    inputfile=str(Path.home() / "vimwiki/index.wiki"),
    outputfile=str(Path.home() / "vimwiki_html/markdown/index.md"),
    to="markdown",
    prefilters=PREFILTER,
    filters=FILTER,
    extra_args=EXTRA_ARGS,
)

Pre-Filters

delete_bullet_star

Remove unordered lists which use the star (asterisk) bullet marker.

The pre-filter does not remove task list items (see delete_task_pending). The pre-filter does not handle wrapped bullets--i.e., it will delete the bulleted-line and leave the wrapped lines. I haven't figured out a good regex for wrapped lines.

echo '- Bulleted list item 1 should appear' \
  '* Bulleted list item 6 should NOT appear' |
  delete_bullet_star

- Bulleted list item 1 should appear

delete_task_pending

Delete pending tasks.

echo '- [ ] Bulleted list done0 item 0 should NOT appear' \
  '- [.] Bulleted list done1 item 1 should appear' |
  delete_task_pending

- [.] Bulleted list done1 item 1 should appear

Pandoc Filters

Panvimwiki provides plain text pre-filters, pandoc filters and post-filters for use from the command line.

delete_tag_lines

Delete lines which only contain Vimwiki tags, e.g., ':tag1:tag2:'

delete_empty_heading

Remove headings that do not have any children or paragraphs. Remove tag lines first, delete_tag_lines or the heading is not considered empty.

delete_taskwiki_heading

Post-Filters

reference_citation

Convert citations to a reference list.

Example.md:

::::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
::: {#ref-bloggs-jones .csl-entry}
Bloggs, A. J., and X. Y. Jones. 1959. "Title Title Title Title Title Title
Title Title Title Title." _Journal Journal Journal_. :::

::: {#ref-chomsky-73 .csl-entry}
Chomsky, N. 1973. "Conditions on Transformations." In _A Festschrift for Morris
Halle_, edited by S. R. Anderson and P. Kiparsky. New York: Holt, Rinehart &
Winston.
:::
:::::

reference_citation < Example.md produces:

[#ref-bloggs-jones]: Bloggs, A. J., and X. Y. Jones. 1959. "Title Title Title Title
Title Title Title Title Title Title." _Journal Journal Journal_.

[#ref-chomsky-73]: Chomsky, N. 1973. "Conditions on Transformations." In _A
Festschrift for Morris Halle_, edited by S. R. Anderson and P. Kiparsky.
New York: Holt, Rinehart & Winston.

wikilink_markdown

Convert Pandoc markdown tasks and wikilinks to :h vimwiki-todo-lists and markdown links compatible with :h vimwiki-syntax-links.

Commands

Local Commands

These commands are only available (and meaningful) when you are currently in a Vimwiki file.

VimwikiConvert[!]

Convert the current Vimwiki buffer. With !, open with default viewer.

Convert the current Vimwiki :buffer to the selected output format (default: docx) specified in g:panvimwiki_settings.

Copy the path to the Word file to the clipboard register "+ quoteplus. On Windows Subsystem for Linux (WSL), convert the path from POSIX to Windows before copying to clipboard.

Remove extraneous info:

• Vimwiki tag lines, e.g., :tag1:tag2:
• Not started tasks, e.g., - [ ] Task1
• Non-task bullet lines, e.g., * [[URI|Description]] or * Text
• Remove empty parent/child headings.

VimwikiConvertWeek[!]

Concatenate DiaryNotes for Monday through current buffer and convert. With !, open in default viewer.

After concatenating DiaryNotes for the week, behave as VimwikiConvert.

VimwikiReference

If in markdown format, expand Pandoc Citations in the current file and append to the end of the file. The Yaml metadata should specify the bibliographic data and the Citation Style Language (CSL).

Add the following to .markdownlint.yml to suppress MD033:

# MD033/no-inline-html : Inline HTML :
# https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
MD033:
  # MD033/no-inline-html Inline HTML [Element: div]
  # Allowed elements
  allowed_elements:
    - "div"

VimwikiReference overwrites the file, so Vim may prompt to reload the buffer (cf. Warning :h W12). If you choose not to reload the buffer, :h :DiffOrig facilitate review of the changes.

VimwikiMarkdownFormat

If in markdown format, convert :h vimwiki-syntax-links wikilinks_title_after_pipe to Inline links, without the "wikilink" title that pandoc adds by default. Preserve :h vimwiki-todo-lists, using task_lists.

VimwikiMarkdownFormat overwrites the file, so Vim may prompt to reload the buffer (cf. Warning :h W12). If you choose not to reload the buffer, :h :DiffOrig facilitate review of the changes.

Settings

Global Settings

g:panvimwiki_settings

Optionally add the following to or, preferably, '~/.vim/plugin/vimwiki.vim'. Panvimwiki defaults to docx format, without extra_args.

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

Development and Testing

Pandoc is required for testing; install it separately (see Installation). Then create an isolated Python environment with uv:

git clone https://github.com/jfishe/panvimwiki.git
cd panvimwiki
uv sync --all-extras --dev --group=testing

tox -av        # List tox commands and descriptions.
tox --recreate # Build the package and run tests with python and Vader.
tox -e vim     # Run Vader tests and generate coverage report.
# Run Vader tests and view results with Vim.
vim -Nu tests/vim/vimrc -c 'Vader tests/vim/*.vader'