*panvimwiki.txt*                Filter and convert Vimwiki notes using pandoc.

==============================================================================
Table of Contents                               *panvimwiki-table-of-contents*

1. Introduction                                      |panvimwiki-introduction|
2. Installation                                      |panvimwiki-installation|
3. Usage                                                    |panvimwiki-usage|
  - Command Line Shell                         |panvimwiki-command-line-shell|
  - Commands                                             |panvimwiki-commands|
  - Settings                                             |panvimwiki-settings|
4. Development and Testing                |panvimwiki-development-and-testing|
5. Note                                                      |panvimwiki-note|
Filter and convert Vimwiki notes using pandoc

<https://panvimwiki.readthedocs.io/en/latest/?badge=latest>
<https://pypi.org/project/panvimwiki/>
<https://github.com/jfishe/panvimwiki/actions/workflows/ci.yml>
<https://pyscaffold.org/>


==============================================================================
1. Introduction                                      *panvimwiki-introduction*

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


==============================================================================
2. Installation                                      *panvimwiki-installation*

Panvimwiki requires Pandoc <https://pandoc.org/> Installation with `conda` is
recommended because the system version, e.g., with Ubuntu, may be too old. Or
download from the website. Pypandoc
<https://github.com/JessicaTegner/pypandoc?tab=readme-ov-file#installing-via-pip>
supports binary installation of pandoc using `pip`.

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:

>bash
    # 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`.

>vim
    if has('python3')
      packadd! panvimwiki
    endif
<


==============================================================================
3. Usage                                                    *panvimwiki-usage*


COMMAND LINE SHELL                             *panvimwiki-command-line-shell*

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

For example from a bash prompt:

>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
<

From python:

>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                             *panvimwiki-delete_bullet_star*

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

The pre-filter does not remove task list items (see
|panvimwiki-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.

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

>text
    - Bulleted list item 1 should appear
<


delete_task_pending                           *panvimwiki-delete_task_pending*

Delete pending tasks.

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

>text
    - [.] 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                                 *panvimwiki-delete_tag_lines*

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


delete_empty_heading                         *panvimwiki-delete_empty_heading*

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


delete_taskwiki_heading                   *panvimwiki-delete_taskwiki_heading*


POST-FILTERS ~


reference_citation                             *panvimwiki-reference_citation*

Convert citations to a reference list.

`Example.md`:

>markdown
    ::: {#refs .references .csl-bib-body .hanging-indent}
    ::: {#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:

>markdown
    [#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 <https://pandoc.org/> markdown tasks and wikilinks to
|vimwiki-todo-lists| and markdown links compatible with |vimwiki-syntax-links|.


COMMANDS                                                 *panvimwiki-commands*


LOCAL COMMANDS ~

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


VimwikiConvert[!]                                  *panvimwiki-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 |panvimwiki-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[!]                          *panvimwiki-VimwikiConvertWeek*

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

After concatenating DiaryNotes for the week, behave as
|panvimwiki-vimwikiconvert|.


VimwikiReference                                 *panvimwiki-VimwikiReference*

If in markdown format, expand Pandoc Citations
<https://pandoc.org/MANUAL.html#citation-syntax> in the current file and append
to the end of the file. The Yaml metadata should specify the bibliographic data
<https://pandoc.org/MANUAL.html#specifying-bibliographic-data> and the Citation
Style Language (CSL)
<https://pandoc.org/MANUAL.html#specifying-a-citation-style>.

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

>yaml
    # 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 |W12|). If you choose not to reload the buffer, |:DiffOrig|
facilitate review of the changes.


VimwikiMarkdownFormat                       *panvimwiki-VimwikiMarkdownFormat*

If in markdown format, convert |vimwiki-syntax-links|
wikilinks_title_after_pipe
<https://pandoc.org/MANUAL.html#extension-wikilinks_title_after_pipe> to Inline
links <https://pandoc.org/MANUAL.html#inline-links>, without the "wikilink"
title that pandoc adds by default. Preserve |vimwiki-todo-lists|, using
task_lists <https://pandoc.org/MANUAL.html#inline-linksInline>.

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


SETTINGS                                                 *panvimwiki-settings*


GLOBAL SETTINGS ~


g:panvimwiki_settings                       *panvimwiki-g:panvimwiki_settings*

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

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


==============================================================================
4. Development and Testing                *panvimwiki-development-and-testing*

Because pandoc is required, a conda environment called `panvimwiki` is created.
The default name may be overridden with the `--name <environment name>`
parameter.

>bash
    git clone https://github.com/jfishe/panvimwiki.git
    cd panvimwiki
    conda env create --file environment.yml
    conda activate panvimwiki
<

>bash
    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'
<


==============================================================================
5. Note                                                      *panvimwiki-note*

This project has been set up using PyScaffold 4.5. For details and usage
information on PyScaffold see <https://pyscaffold.org/>.

==============================================================================
6. Links                                                    *panvimwiki-links*

1. *Documentation Status*: https://readthedocs.org/projects/panvimwiki/badge/?version=latest
2. *PyPI-Server*: https://img.shields.io/pypi/v/panvimwiki.svg
3. *Test and Publish
Python 🐍 distribution 📦 to PyPI and TestPyPI*: https://github.com/jfishe/panvimwiki/actions/workflows/ci.yml/badge.svg
4. *Project
generated with PyScaffold*: https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl:
