{"id":25427836,"url":"https://github.com/gryf/vimwiki2html","last_synced_at":"2026-05-19T14:31:49.664Z","repository":{"id":277199634,"uuid":"931660436","full_name":"gryf/vimwiki2html","owner":"gryf","description":"Parse and generate html out of vimwiki source files","archived":false,"fork":false,"pushed_at":"2025-04-28T15:32:33.000Z","size":392,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-14T06:28:06.516Z","etag":null,"topics":["conversion","html","python","vim","vimwiki"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gryf.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-12T16:42:50.000Z","updated_at":"2025-04-28T15:32:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"036d2d4a-599c-4cd7-b1ac-037433e1c991","html_url":"https://github.com/gryf/vimwiki2html","commit_stats":null,"previous_names":["gryf/vimwiki2html"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/gryf/vimwiki2html","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gryf%2Fvimwiki2html","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gryf%2Fvimwiki2html/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gryf%2Fvimwiki2html/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gryf%2Fvimwiki2html/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gryf","download_url":"https://codeload.github.com/gryf/vimwiki2html/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gryf%2Fvimwiki2html/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263234943,"owners_count":23434918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["conversion","html","python","vim","vimwiki"],"created_at":"2025-02-17T01:30:28.396Z","updated_at":"2025-10-04T14:32:28.665Z","avatar_url":"https://github.com/gryf.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"============\nvimwiki2html\n============\n\nVimWiki2HTML is a python implementation for converting `VimWiki`_ default\nsyntax into html.\n\nMotivation\n----------\n\nMy main motivation is to be able to deploy output of the ``VimwikiAll2HTML`` to\nsomewhere else, either to use it directly on local filesystem, rsync it to some\nof other machines or even expose it via webserver. With that assumption I've\nnoticed it might be somewhat troublesome with current design especially when\ndealing with asset files, which are not stored on ``~/vimwiki_html``, but\nrather are simply linked to ``~/vimwiki`` path.\n\nAlso in some really large files, I've noticed ``Vimwiki2HTML`` can be really\nslow. Currently I have around 750 wiki files.  A lot of them are pretty small,\nyet some of them are complex, full of tables, code blocks and lists. Below is a\nsimple benchmark I've done to convert whole wiki collection into html using\nvimwiki ``VimwikiAll2HTML`` command:\n\n.. code:: console\n\n   $ time vim -s script.vim\n\n   real\t2m33,027s\n   user\t2m17,865s\n   sys\t0m6,750s\n   $ cat script.vim\n   :VimwikiIndex\n   :VimwikiAll2HTML\n   :q!\n\nAnd yes, it took two and a half minutes to build whole wiki as HTML.\n\nLet see how Python implementation performs. Currently it have most of features\nI need (see the functionality coverage below):\n\n.. code:: console\n\n   $ time vw2html\n   html.py:703: WARNING: Image \"p.png\" have no schema\n   html.py:720: WARNING: File `p.png' doesn't exists, ignoring\n   html.py:715: WARNING: File `../../images/vimwiki_logo.png' pointing outside of wiki root, ignoring\n   html.py:703: WARNING: Image \"images/allegro/nz9_t.jpg\" have no schema\n   html.py:703: WARNING: Image \"Nerd Font\" have no schema\n   html.py:720: WARNING: File `Nerd Font' doesn't exists, ignoring\n\n   real 0m0,428s\n   user 0m2,173s\n   sys  0m0,608s\n\nBesides some basic info/warning about potential issues and copying all needed\nfiles (including images and linked static non-wiki files), it took less than\nsecond thanks to parallel conversion - although with single thread it still\ntake under 1 second:\n\n.. code:: console\n\n   real\t0m0,873s\n   user\t0m0,683s\n   sys\t0m0,182s\n\n\nRequirements\n------------\n\nThe only requirement is Python 3.12 or higher.\n\nInstallation\n------------\n\nCurrently the only option is to install it using virtualenv:\n\n.. code:: console\n\n   $ python -m venv .venv\n   $ . .venv/bin/activate\n   (.venv) $ pip install .\n\n\nUsage\n-----\n\nJust use the ``vw2html`` command to convert selected file or directory.\n\nYou might also use configuration file placed under a file\n``$XDG_CONFIG_HOME/vw2html.toml`` for tweaking program behaviour. All the\npossible options are listed below:\n\n.. code:: toml\n\n   [[vimwiki]]\n   # Directory to the vimwiki root path. Can contain ~/ or env variables.\n   path = ''\n   # Directory to the output path. Can contain ~/ or env variables. if not\n   # provided it will be created as adding _html suffix for whatever directory\n   # is set on path.\n   path_html = ''\n   # Main file without extension. Usually index.\n   index = 'index'\n   # Extension for wiki files.\n   ext = '.wiki'\n   # Path to templates. If not specified, wiki path will be used.\n   template_path = ''\n   # Default template without extension.\n   template_default = 'default'\n   # Default template extension.\n   template_ext = '.tpl'\n   # Absolute path to the css stylesheet.\n   css_name = ''\n   # Header level to ignore with TOC, 0 means include all\n   skip_toc_level = 0\n   # If set to false, conversion will execute wiki after wiki. Usefull for\n   # debugging.\n   convert_async = true\n\nAs for css file, there is default one which comes with VimWiki and is located\nin `vimwiki/autoload/vimwiki/style.css` although due to different way and\nlocations of installing vim plugins, it will need to be specifically set either\nin config file, or passed to the ``vw2html`` command via ``-s`` parameter.\n\nTo use ``vw2html`` without bothering about providing anything via commandline,\nit's as easy as:\n\n.. code:: toml\n\n   [[vimwiki]]\n   path = \"/path/to/vimwiki\"\n\nAnd that's it. Other paths will be assumed or calculated using wiki path, or\nusing defaults, so in this case:\n\n- ``path_html`` will become ``/path/to/vimwiki_html``\n- ``ext`` will be ``.wiki``\n- ``template_path`` will be ``/path/to/vimwiki``\n- ``template_default`` will be ``default``\n- ``template_ext`` will be ``.tpl``\n- ``css_name`` will be none\n- ``skip_toc_level`` will be 0\n\nin other words:\n\n- root wiki: ``path/to/vimwiki``\n- html output: ``path/to/vimwiki_html``\n- default template file: ``path/to/vimwiki/default.tpl``\n\noptionally you can provide CSS file using ``css_name`` with full path to css\nfile.\n\nWiki path is needed even for single wiki file, as it is used for gathering all\nneeded pieces like templates, stylesheet and assets.\n\nAnother thing is, you can have multiple vimwiki configs in single file, i.e.:\n\n.. code:: toml\n\n   [[vimwiki]]\n   path = \"/path/to/vimwiki\"\n\n   [[vimwiki]]\n   path = \"~/vimwiki\"\n\nand whenever you call ``vw2html`` command with single file or whole wiki\ndirectory, it will search for matching root in available configs and use\nappropriate one.\n\nTemplates\n---------\n\nEven so templates can be in whatever HTML standard (including raw *tag soup*,\nHTML4, XHTML and HTML5), parser used for extracting css and javascript files\norigins from Python stdlib, just for simplicity (it might change in the future\nwith optional dependency on BeautifulSoup - for now it's ``minidom`` parser),\nso be careful and close all the tags even if standards like HTML5 permit for\nunclosing tags like ``\u003clink\u003e``.\n\nIf you place css file(s) into template, you don't have to provide ``css_name``\nin the configuration or use ``--stylesheet`` commandline option - all the files\nwill be gathered from the links and put into destination directory with exact\ndirectory structure like in source vimwiki path. Additionally, assets from CSS\nfiles will be copied as well (namely image files), while JavaScript files will\nnot be searched for those.\n\nWhen using no template (i.e. using \"default\") using external CSS file is\noptional as well, although resulting HTML will be pretty raw.\n\nIntegration with vim\n--------------------\n\nYou can use ``vw2html`` with vim for rendering wiki, instead of using\n``Vimwiki2HTML`` and/or ``VimwikiAll2HTML``. There are many ways to achieve\nthat, one of it is to map the keys:\n\n.. code:: vim\n\n   map \u003cF5\u003e :call system(\"vw2html \" . bufname(\"%\"))\u003cCR\u003e\n   map \u003cF6\u003e :call system(\"vw2html\")\u003cCR\u003e\n\nso, suppose there is a valid configuration and user hit F5 it will pass current\nfile to ``vw2html`` and convert it to HTML. F6 on the other hand will execute\n``vw2html`` without arguments, which will do the conversion on entire wiki.\n\n\nConversion state\n----------------\n\nWhat's supported\n''''''''''''''''\n\n- Typefaces\n\n  - bold/strong\n  - italic/emphasis\n  - strikeout/del\n  - inline code/monospace\n  - superscript\n  - subscript\n\n- Headers\n- Paragraphs\n- Lists\n\n  - Support for unordered lists (``*``, ``-``, ``#``)\n  - Support for ordered lists (``1.``, ``2)``)\n  - Support for TODO lists (default markings for the items)\n  - Support for definition lists\n\n    - including multiline paragraph in definition\n    - including limited lists support nested within definition\n\n- Preformatted text\n\n  - code blocks can be colored using ``{{{type=foo``` or ``{{{foo`` where \"foo\"\n    is the lexer recognized by the pygments_\n\n- Comments\n- Horizontal line\n- Placeholders\n\n  - ``%title``\n  - ``%date``\n  - ``%template``\n  - ``%nohtml``\n\n  - ``%plainhtml`` (this one is undocumented, and allows to add explicit html\n    tags which follows that placeholder. It's inline only, which means no span\n    on multiple lines, although this placeholder can be repeated several times)\n\n  - ``%toc`` - This is additional placeholder, which doesn't exists in VimWiki\n    and will be replaced with table of contents in similar way how\n    ``VimwikiTOC`` operates but it will be generated during html conversion,\n    which makes the ToC always up to date. There is also a config option to\n    specify which header up to toplevel toc should ignore.\n\n  - Template placeholders\n\n    - ``%root_path%``\n    - ``%title%``\n    - ``%date%``\n    - ``%content%``\n    - ``%css%`` - this one is undocumented as well, and allows to add css\n      filename. Note, that css file will be copied to the root of vimwiki\n      regardless of it's placement on filesystem\n\n- Links\n\n  - Diary\n  - wikilinks (absolute/relative/plain)\n  - external links (local/remote/bare)\n\n  - transclusion links (or, image tags, as no other are supported on vimwiki)\n    even those which have no schema (VimWiki docs doesn't mention those, yet\n    it's simply working)\n\n  - raw links (or bare)\n  - anchor links (implemented differently - only last anchor is taken into\n    account - may cause anchors collision)\n\n  - adding arbitrary attributes for the link - i.e.\n    ``[[target|descritption|class=\"foo\"]]``. This is addition which doesn't\n    exists on VimWiki, but it's nice addition for adding lightbox-ish\n    functionality\n\n- Tables\n\n  - tables with headers\n  - columns and rows spanning\n  - aligning for the columns (``VimWiki2HTML`` doesn't do that)\n\n- Explicit html tags (supported tag list: ``b``, ``i``, ``s``, ``u``, ``sub``,\n  ``sup``, ``kbd``, ``br`` and ``hr``).\n- Escape other HTML tags\n\nWhat's not\n''''''''''\n\n- Placeholders\n\n  - Template placeholders\n\n    - ``%wiki_path%``\n\n- Links:\n\n  - interwiki links\n\n- Lists:\n\n  - which start with roman number (i.e. ``i``, ``x``, ``mc``, ``I``, ``X``,\n    ``MC``)\n  - which start with letters (i.e. ``a``, ``b``, ``z``, ``A``, ``B``, ``Z``)\n  - VimWiki parser produce invalid item lists - no closing item tags for both\n    kind of the lists (``\u003cul\u003e`` and ``\u003col\u003e``).\n  - With the list defined like below (overindented lists, and another dedented\n    list):\n\n    .. code::\n\n       paragraph\n\n         * some list item (which is inednted)\n         * another item\n\n       * another list\n\n    ``Vimwiki2HTML`` will generate two lists, or rather list and a dangling\n    item in a ``\u003cli\u003e`` tag. OTOH in such case ``vw2html`` will generate two\n    lists properly on the same level - output may differ visually.\n\n  - interpretation of items like:\n\n    .. code::\n\n       paragraph\n\n       * some list item\n       * another item\n\n       * last item\n\n    will produce two separate lists, not like in VimWiki html parser single\n    list with second item having swallowed empty line.\n\n- Mathematical formulae (both - inline and block)\n- Blockquotes\n- Tags\n- Configurable explicit html tags (besides default list)\n\n\nMost of those are either second priority for implementation or things, which I\nhave no interested in.\n\n\nLicense\n-------\n\nThis piece of software is licensed under MIT.\n\n\n.. _VimWiki: https://github.com/vimwiki/vimwiki\n.. _pygments: https://pygments.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgryf%2Fvimwiki2html","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgryf%2Fvimwiki2html","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgryf%2Fvimwiki2html/lists"}