diff --git a/README.md b/README.md
index 46e3b1b..54a5215 100644
--- a/README.md
+++ b/README.md
@@ -3,18 +3,28 @@
[![Docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://kdheepak.com/panvimdoc/)
[![Build](https://github.com/kdheepak/panvimdoc/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/kdheepak/panvimdoc/actions/workflows/test.yml?query=branch%3Amain)
-Write documentation in [pandoc markdown](https://pandoc.org/MANUAL.html).
-Generate documentation in vimdoc.
+Write documentation in [pandoc markdown](https://pandoc.org/MANUAL.html). Generate documentation in
+vimdoc.
-::: center
-This software is released under a MIT License.
-:::
+::: center This software is released under a MIT License. :::
+
+# Support This Project
+
+If you've found this project helpful, please consider supporting its ongoing development and
+maintenance. You can sponsor me on GitHub Sponsors or Donate via Strip:
+
+[![Sponsor @kdheepak](https://img.shields.io/badge/GitHub_Sponsor-%E2%9D%A4-blue)](https://github.com/sponsors/kdheepak)
+[![Donate](https://img.shields.io/badge/Donate_Via_Stripe-%E2%9D%A4-blue)](https://donate.stripe.com/8wM9E7bBO9ZsbGUdQR)
+
+Every bit of sponsorship helps, whether it's to buy me a coffee or to enable me to dedicate more
+time to maintaining and improving this project. I sincerely appreciate your generosity and support!
# TLDR
-1. Choose a name for your project, i.e. `${VIMDOC_PROJECT_NAME}`. See [.github/workflows/panvimdoc.yml](./.github/workflows/panvimdoc.yml) as an example.
+1. Choose a name for your project, i.e. `${VIMDOC_PROJECT_NAME}`. See
+ [.github/workflows/panvimdoc.yml](./.github/workflows/panvimdoc.yml) as an example.
2. Add the following to `./.github/workflows/panvimdoc.yml`:
```yaml
@@ -85,8 +95,9 @@ jobs:
incrementheadinglevelby: 0 # Increment heading levels by specified number
```
-The only required thing for you to do is to choose a `VIMDOC_PROJECT_NAME` appropriately.
-This is usually the name of the plugin or the documentation file without the `.txt` extension. For example, the following:
+The only required thing for you to do is to choose a `VIMDOC_PROJECT_NAME` appropriately. This is
+usually the name of the plugin or the documentation file without the `.txt` extension. For example,
+the following:
```yaml
- name: panvimdoc
@@ -95,12 +106,13 @@ This is usually the name of the plugin or the documentation file without the `.t
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.
+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 for which version to use.
+It is recommended to pin to an exact version so you can be confident that no surprises occur for you
+or your users. See for which version to use.
Once you pick a version, you can pin it like so:
```yaml
@@ -111,13 +123,16 @@ Once you pick a version, you can pin it like so:
For an example of how this is used, see one of the following workflows:
- [kdheepak/panvimdoc](./.github/workflows/panvimdoc.yml): [doc/panvimdoc.txt](./doc/panvimdoc.txt)
-- [kdheepak/tabline.nvim](https://github.com/kdheepak/tabline.nvim/blob/main/.github/workflows/ci.yml): [doc/tabline.txt](https://github.com/kdheepak/tabline.nvim/blob/main/doc/tabline.txt)
+- [kdheepak/tabline.nvim](https://github.com/kdheepak/tabline.nvim/blob/main/.github/workflows/ci.yml):
+ [doc/tabline.txt](https://github.com/kdheepak/tabline.nvim/blob/main/doc/tabline.txt)
-Or see any of the packages here that depend on this action:
+Or see any of the packages here that depend on this action:
+
-If you are interested in making your vim plugin documentation available as a HTML page, check out [.github/workflows/docs.yml](./.github/workflows/docs.yml) file.
+If you are interested in making your vim plugin documentation available as a HTML page, check out
+[.github/workflows/docs.yml](./.github/workflows/docs.yml) file.
@@ -141,20 +156,11 @@ jobs:
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
+ --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:
@@ -192,73 +198,98 @@ 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.
+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.
+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 or [`@nanotree`'s project](https://github.com/nanotee/vimdoc-notes) 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.
+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
+ or
+ [`@nanotree`'s project](https://github.com/nanotee/vimdoc-notes) 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](https://github.com/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.
+For example, [ibhagwan/ts-vimdoc.nvim](https://github.com/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](https://github.com/wincent/docvim) which is written in Haskell.
Finally there's [FooSoft/md2vim](https://github.com/FooSoft/md2vim) which is written in Go.
-None of these projects use Pandoc.
-Pandoc Markdown supports a wide number of features: See 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.
+None of these projects use Pandoc. Pandoc Markdown supports a wide number of features: See
+ 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.
+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.
+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.
+- **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:
+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.
+- Offers the ability to include multiple Markdown files, providing flexibility in documentation
+ structure.
# Specification
-The specification is described in [panvimdoc.md](./doc/panvimdoc.md) along with examples.
-The generated output is in [panvimdoc.txt](./doc/panvimdoc.txt).
-The reference implementation of the Pandoc lua filter is in [panvimdoc.lua](./scripts/panvimdoc.lua).
-See [panvimdoc.sh](./panvimdoc.sh) for how to use this script, or check the [Usage](#usage) section.
+The specification is described in [panvimdoc.md](./doc/panvimdoc.md) along with examples. The
+generated output is in [panvimdoc.txt](./doc/panvimdoc.txt). The reference implementation of the
+Pandoc lua filter is in [panvimdoc.lua](./scripts/panvimdoc.lua). See [panvimdoc.sh](./panvimdoc.sh)
+for how to use this script, or check the [Usage](#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: .
+If you would like to contribute to the specification, or if you have feature requests or opinions,
+please feel free to comment here: .