If you are interested in making your vim plugin documentation available as a HTML page, check out .github/workflows/docs.yml file.

name: docs

on:
  push:
    branches: main

permissions:
  contents: write

jobs:
  publish-gh-page:
    runs-on: ubuntu-latest
    steps:
      - name: checkout code
        uses: actions/checkout@v3
      - name: pandoc markdown to html
        uses: docker://pandoc/latex:3.1
        with:
          args: >-
            --katex
            --from markdown+tex_math_single_backslash
            --to html5+smart
            --template="./scripts/template.html5"
            --css="/panvimdoc/css/theme.css"
            --css="/panvimdoc/css/skylighting-solarized-theme.css"
            --toc
            --wrap=none
            --metadata title="panvimdoc"
            doc/panvimdoc.md
            --lua-filter=scripts/include-files.lua
            --lua-filter=scripts/skip-blocks.lua
            -t html
            -o public/index.html
      - name: deploy to GitHub pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: public

Using it manually

The ./panvimdoc.sh script runs pandoc along with all the filters and custom output writer.

$ ./panvimdoc.sh
Usage: ./panvimdoc.sh --project-name PROJECT_NAME --input-file INPUT_FILE --vim-version VIM_VERSION --toc TOC --description DESCRIPTION --dedup-subheadings DEDUP_SUBHEADINGS --treesitter TREESITTER

Arguments:
  --project-name: the name of the project
  --input-file: the input markdown file
  --vim-version: the version of Vim that the project is compatible with
  --toc: 'true' if the output should include a table of contents, 'false' otherwise
  --description: a description of the project
  --dedup-subheadings: 'true' if duplicate subheadings should be removed, 'false' otherwise
  --demojify: 'false' if emojis should not be removed, 'true' otherwise
  --treesitter: 'true' if the project uses Tree-sitter syntax highlighting, 'false' otherwise
  --ignore-rawblocks: 'true' if the project should ignore HTML raw blocks, 'false' otherwise
  --doc-mapping: 'true' if the project should use h4 headers as mapping docs, 'false' otherwise
  --doc-mapping-project-name: 'true' if tags generated for mapping docs contain project name, 'false' otherwise
  --shift-heading-level-by: 0 if you don't want to shift heading levels , n otherwise
  --increment-heading-level-by: 0 if don't want to increment the starting heading number, n otherwise

You will need pandoc v3.0.0 or greater for this script to work.

Motivation

Writing user-friendly documentation is important for every successful software project. This is particularly true when writing documentation for users in the world of vim plugins.

The process of writing and maintaining this documentation can often be a cumbersome, time-consuming task. This project is aims to make that process a little bit easier by allowing anyone to write documentation in markdown (or any format Pandoc supports) and converting it to vimdoc automatically. This way, plugin authors will have to write documentation just once (for example, as part of the README of the project), and the vim documentation can be autogenerated.

Rationale

1. Simplicity: Writing in Markdown is often more intuitive for developers. By converting from Markdown to vimdoc, authors can maintain the simplicity of Markdown while adhering to the vimdoc standards.
2. Unified Documentation: Plugin authors can write their documentation just once (such as in the project's README) and automatically generate vim documentation, ensuring consistency and saving time.
3. Preserving Vim Features: Vimdoc isn’t just plain text; it supports syntax highlighting, tags, links, and careful formatting using whitespace. It's essential to preserve these features when converting to ensure the quality and usefulness of the documentation. See https://vimhelp.org/helphelp.txt.html#help-writing or @nanotree's project for more information.
4. Leveraging Pandoc: Unlike existing solutions, this project leverages Pandoc's wide range of features, including support for multiple Markdown flavors and easy-to-write custom filters in Lua.
5. Interoperability: The choice of Pandoc allows for enhanced flexibility, making it easier to extend functionality or even adapt the converter for other documentation formats in the future.

Background

Writing documentation in Markdown and converting it to vimdoc is not a novel idea.

For example, ibhagwan/ts-vimdoc.nvim is an implementation a neovim treesitter based markdown to vimdoc converter that works fairly well. There are no dependencies except for the Markdown treesitter parser. It is neovim only but you can use this on github actions even for a vim plugin documentation.

There's also wincent/docvim which is written in Haskell. Finally there's FooSoft/md2vim which is written in Go.

None of these projects use Pandoc. Pandoc Markdown supports a wide number of features: See https://pandoc.org/MANUAL.html for more information. Most importantly, it supports a range of Markdown formats and flavors. And, Pandoc has filters and a custom output writer that can be configured in lua. Pandoc filters can extend the capability of Pandoc with minimal lua scripting, and these are very easy to write and maintain too.

That means, with this project, you can write your Vim documentation in Markdown, RestructuredText, AsciiDoc, etc and convert it to VimDoc, PDF, Word, HTML etc.

Goals

By offering a specification and reference implementation for converting Pandoc Markdown to vimdoc, this project aims to reduce friction in the documentation process for vim plugin authors.

Here are the specific goals that guide this project:

• Readability: The Markdown files must render correctly when presented as README files on platforms like GitHub, GitLab, or SourceHut.
• Web-Friendly HTML: If converted to HTML using Pandoc, the Markdown files must be web-friendly and render appropriately.
• VimDoc Features: The generated vim documentation must support essential features like links and tags.
• Aesthetically Pleasing: The vim documentation must not only be functional but also visually pleasing in both vim and plain text files. This includes the appropriate use of columns and spacing.
• Guidelines: While the format of built-in Vim documentation is a valuable reference, it is used as guidelines rather than strict rules.

Features

This project offers a comprehensive suite of features designed to streamline the conversion process from Markdown to vimdoc:

• Automatically generates titles for vim documentation.
• Creates a table of contents to enhance navigation within the document.
• Automatically handles the generation of links and tags.
• Maintains markdown syntax for tables, ensuring proper rendering.
• Allows for manual control through raw vimdoc syntax where necessary.
• Offers the ability to include multiple Markdown files, providing flexibility in documentation structure.

Specification

The specification is described in panvimdoc.md along with examples. The generated output is in panvimdoc.txt. The reference implementation of the Pandoc lua filter is in panvimdoc.lua. See panvimdoc.sh for how to use this script, or check the Usage section.

If you would like to contribute to the specification, or if you have feature requests or opinions, please feel free to comment here: #11.

References

• https://learnvimscriptthehardway.stevelosh.com/chapters/54.html
• https://github.com/nanotee/vimdoc-notes
• https://github.com/mjlbach/babelfish.nvim
• https://foosoft.net/projects/md2vim/
• https://github.com/wincent/docvim
• https://github.com/Orange-OpenSource/pandoc-terminal-writer/