panvimdoc

Write documentation in pandoc markdown. Generate documentation in vimdoc.

::: center This software is released under a MIT License. :::

TLDR

Add the following to ./.github/workflows/panvimdoc.yml:

name: panvimdoc

on:
  push:
    branches: [main]
    paths:
      - README.md 
      - .github/workflows/panvimdoc.yml 

permissions:
  contents: write

jobs:
  docs:
    runs-on: ubuntu-latest
    name: pandoc to vimdoc
    steps:
      - uses: actions/checkout@v2
      - uses: kdheepak/panvimdoc@main
        with:
          vimdoc: ${{ github.event.repository.name }}
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "Auto generate docs"
          branch: ${{ github.head_ref }}

README.md gets converted to ./doc/${{ github.event.repository.name }}.txt and auto-committed to the repo.

Optional: Add the following to ./.github/dependabot.yml to auto update your github action dependencies:

version: 2
updates:
  # Maintain dependencies for GitHub Actions
  - package-ecosystem: github-actions
    directory: "/"
    schedule:
      interval: weekly
    open-pull-requests-limit: 10

Usage

Generating vimdoc using GitHub Actions

Create an empty doc file:

touch doc/.gitkeep
git commit -am "Add empty doc folder"
git push

Then add the following to ./.github/workflows/panvimdoc.yml:

name: panvimdoc

on: [push]

jobs:
  docs:
    runs-on: ubuntu-latest
    name: pandoc to vimdoc
    steps:
      - uses: actions/checkout@v2
      - name: panvimdoc
        uses: kdheepak/panvimdoc@main
        with:
          vimdoc: __VIMDOC_PROJECT_NAME_HERE__ # Output vimdoc project name (required)
          # The following are all optional
          pandoc: "README.md" # Input pandoc file
          version: "NVIM v0.8.0" # Vim version number
          toc: true # Table of contents
          description: "" # Project description used in title (if empty, uses neovim version and current date)
          titledatepattern: "%Y %B %d" # Pattern for the date that used in the title
          demojify: false # Strip emojis from the vimdoc
          dedupsubheadings: true # Add heading to subheading anchor links to ensure that subheadings are unique
          treesitter: true # Use treesitter for highlighting codeblocks
          ignorerawblocks: true # Ignore raw html blocks in markdown when converting to vimdoc
          docmapping: false # Use h4 headers as mapping docs
          docmappingprojectname: true # Use project name in tag when writing mapping docs
          shiftheadinglevelby: 0 # Shift heading levels by specified number
          incrementheadinglevelby: 0 # Increment heading levels by specified number

The only required thing for you to do is to choose a __VIMDOC_PROJECT_NAME_HERE__ appropriately. This is usually the name of the plugin or the documentation file without the .txt extension. For example, the following:

- name: panvimdoc
  uses: kdheepak/panvimdoc@main
  with:
    vimdoc: panvimdoc

will output a file doc/panvimdoc.txt and the vim help tag for it will be panvimdoc using the main branch of the repository.

All the other options are optional.

It is recommended to pin to an exact version so you can be confident that no surprises occur for you or your users. See https://github.com/kdheepak/panvimdoc/releases/latest for which version to use. Once you pick a version, you can pin it like so:

- name: panvimdoc
  uses: kdheepak/panvimdoc@vX.X.X

For an example of how this is used, see one of the following workflows:

Or see any of the packages here that depend on this action: https://github.com/kdheepak/panvimdoc/network/dependents

Generating HTML using GitHub Actions

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

You can find the Markdown file you are reading right now converted to HTML here: https://kdheepak.com/panvimdoc/

Here's an example:

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 pre-commit locally

pre-commit lets you easily install and manage pre-commit hooks locally.

Two hooks are available, differing only in the way dependencies are handled:

panvimdoc-docker: Requires a running Docker engine on your host. All other dependencies will be loaded inside the container.
panvimdoc: Runs in your local environment, so you have to make sure all dependencies of panvimdoc are installed (i.e., pandoc v3.0.0 or greater)

To use a hook, first install pre-commit. Then, add the following to your .pre-commit-config.yaml (here panvimdoc-docker is used):

- repo: 'https://github.com/kdheepak/panvimdoc'
  rev: v4.0.1
  hooks:
    - id: panvimdoc-docker
      args:
        - '--project-name'
        - <your-project-name>

You can specify additional arguments to panvimdoc.sh using args. See the section below (or run ./panvimdoc.sh) for the full list of arguments.

To change the input file, modify the files field of the hook and supply the corresponding --input-file to args. In the example below, the hook will be triggered if any .md file changes:

- repo: 'https://github.com/kdheepak/panvimdoc'
  rev: v4.0.1
  hooks:
    - id: panvimdoc-docker
      files: ^.*\.md$
      args:
        - '--project-name'
        - <your-project-name>
        - '--input-file'
        - <your-input-file.md>

Using it manually locally

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 project description used in title (if empty, uses neovim version and current date)
  --dedup-subheadings: 'true' if duplicate subheadings should be removed, 'false' otherwise
  --title-date-pattern: '%Y %B %d' a pattern for the date that used in the title
  --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

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.
Unified Documentation: Plugin authors can write their documentation just once (such as in the project's README) and automatically generate vim documentation, ensuring co

Panvimdoc

Install / Use

README