{"id":13410550,"url":"https://github.com/kdheepak/panvimdoc","last_synced_at":"2025-04-04T12:08:25.789Z","repository":{"id":43097500,"uuid":"394350304","full_name":"kdheepak/panvimdoc","owner":"kdheepak","description":"Write documentation in pandoc markdown. Generate documentation in vimdoc.","archived":false,"fork":false,"pushed_at":"2024-07-25T18:01:19.000Z","size":31976,"stargazers_count":283,"open_issues_count":8,"forks_count":15,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T11:10:30.513Z","etag":null,"topics":["documentation","markdown","neovim","pandoc","vim"],"latest_commit_sha":null,"homepage":"https://kdheepak.com/panvimdoc","language":"CSS","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/kdheepak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["kdheepak"],"custom":["https://donate.stripe.com/8wM9E7bBO9ZsbGUdQR"]}},"created_at":"2021-08-09T15:46:23.000Z","updated_at":"2025-03-22T01:09:28.000Z","dependencies_parsed_at":"2023-01-04T15:05:20.355Z","dependency_job_id":"7f23940b-61a8-4ce0-9d3f-2510177b5215","html_url":"https://github.com/kdheepak/panvimdoc","commit_stats":{"total_commits":590,"total_committers":15,"mean_commits":"39.333333333333336","dds":0.05932203389830504,"last_synced_commit":"69d9529e2a0ed53b1ba6dc56f471bf263af71042"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdheepak%2Fpanvimdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdheepak%2Fpanvimdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdheepak%2Fpanvimdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdheepak%2Fpanvimdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kdheepak","download_url":"https://codeload.github.com/kdheepak/panvimdoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174420,"owners_count":20896078,"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":["documentation","markdown","neovim","pandoc","vim"],"created_at":"2024-07-30T20:01:07.638Z","updated_at":"2025-04-04T12:08:25.766Z","avatar_url":"https://github.com/kdheepak.png","language":"CSS","readme":"# panvimdoc\n\n[![Docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://kdheepak.com/panvimdoc/)\n[![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)\n[![Sponsor](https://img.shields.io/badge/GitHub_Sponsor-%E2%9D%A4-blue)](https://github.com/sponsors/kdheepak)\n[![Donate](https://img.shields.io/badge/Donate_Via_Stripe-%E2%9D%A4-blue)](https://donate.stripe.com/8wM9E7bBO9ZsbGUdQR)\n\nWrite documentation in [pandoc markdown](https://pandoc.org/MANUAL.html). Generate documentation in\nvimdoc.\n\n\u003cimg width=\"1512\" alt=\"image\" src=\"https://github.com/kdheepak/panvimdoc/assets/1813121/dfaed08d-fb9b-4cac-aad0-da71b605265d\"\u003e\n\n::: center This software is released under a MIT License. :::\n\n# TLDR\n\n1. Add the following to `./.github/workflows/panvimdoc.yml`:\n\n   ```yaml\n   name: panvimdoc\n   \n   on:\n     push:\n       branches: [main]\n       paths:\n         - README.md \n         - .github/workflows/panvimdoc.yml \n   \n   permissions:\n     contents: write\n   \n   jobs:\n     docs:\n       runs-on: ubuntu-latest\n       name: pandoc to vimdoc\n       steps:\n         - uses: actions/checkout@v2\n         - uses: kdheepak/panvimdoc@main\n           with:\n             vimdoc: ${{ github.event.repository.name }}\n         - uses: stefanzweifel/git-auto-commit-action@v4\n           with:\n             commit_message: \"Auto generate docs\"\n             branch: ${{ github.head_ref }}\n   ```\n\n2. `README.md` gets converted to `./doc/${{ github.event.repository.name }}.txt` and auto-committed to the repo.\n\n_Optional_: Add the following to `./.github/dependabot.yml` to auto update your github action dependencies:\n\n```\nversion: 2\nupdates:\n  # Maintain dependencies for GitHub Actions\n  - package-ecosystem: github-actions\n    directory: \"/\"\n    schedule:\n      interval: weekly\n    open-pull-requests-limit: 10\n```\n\n# Usage\n\n### Generating vimdoc using GitHub Actions\n\nCreate an empty doc file:\n\n```bash\ntouch doc/.gitkeep\ngit commit -am \"Add empty doc folder\"\ngit push\n```\n\nThen add the following to `./.github/workflows/panvimdoc.yml`:\n\n```yaml\nname: panvimdoc\n\non: [push]\n\njobs:\n  docs:\n    runs-on: ubuntu-latest\n    name: pandoc to vimdoc\n    steps:\n      - uses: actions/checkout@v2\n      - name: panvimdoc\n        uses: kdheepak/panvimdoc@main\n        with:\n          vimdoc: __VIMDOC_PROJECT_NAME_HERE__ # Output vimdoc project name (required)\n          # The following are all optional\n          pandoc: \"README.md\" # Input pandoc file\n          version: \"NVIM v0.8.0\" # Vim version number\n          toc: true # Table of contents\n          description: \"\" # Project description used in title (if empty, uses neovim version and current date)\n          titledatepattern: \"%Y %B %d\" # Pattern for the date that used in the title\n          demojify: false # Strip emojis from the vimdoc\n          dedupsubheadings: true # Add heading to subheading anchor links to ensure that subheadings are unique\n          treesitter: true # Use treesitter for highlighting codeblocks\n          ignorerawblocks: true # Ignore raw html blocks in markdown when converting to vimdoc\n          docmapping: false # Use h4 headers as mapping docs\n          docmappingprojectname: true # Use project name in tag when writing mapping docs\n          shiftheadinglevelby: 0 # Shift heading levels by specified number\n          incrementheadinglevelby: 0 # Increment heading levels by specified number\n```\n\nThe only required thing for you to do is to choose a `__VIMDOC_PROJECT_NAME_HERE__` appropriately. This is\nusually the name of the plugin or the documentation file without the `.txt` extension. For example,\nthe following:\n\n```yaml\n- name: panvimdoc\n  uses: kdheepak/panvimdoc@main\n  with:\n    vimdoc: panvimdoc\n```\n\nwill output a file `doc/panvimdoc.txt` and the vim help tag for it will be `panvimdoc` using the\n`main` branch of the repository.\n\nAll the other options are optional.\n\nIt is recommended to pin to an exact version so you can be confident that no surprises occur for you\nor your users. See \u003chttps://github.com/kdheepak/panvimdoc/releases/latest\u003e for which version to use.\nOnce you pick a version, you can pin it like so:\n\n```yaml\n- name: panvimdoc\n  uses: kdheepak/panvimdoc@vX.X.X\n```\n\nFor an example of how this is used, see one of the following workflows:\n\n- [kdheepak/panvimdoc](./.github/workflows/panvimdoc.yml): [doc/panvimdoc.txt](./doc/panvimdoc.txt)\n- [kdheepak/tabline.nvim](https://github.com/kdheepak/tabline.nvim/blob/main/.github/workflows/ci.yml):\n  [doc/tabline.txt](https://github.com/kdheepak/tabline.nvim/blob/main/doc/tabline.txt)\n\nOr see any of the packages here that depend on this action:\n\u003chttps://github.com/kdheepak/panvimdoc/network/dependents\u003e\n\n### Generating HTML using GitHub Actions\n\nIf you are interested in making your vim plugin documentation available as a HTML page, check out\n[.github/workflows/docs.yml](./.github/workflows/docs.yml) file. \n\nYou can find the Markdown file you are reading right now converted to HTML here: https://kdheepak.com/panvimdoc/\n\nHere's an example:\n\n```yml\nname: docs\n\non:\n  push:\n    branches: main\n\npermissions:\n  contents: write\n\njobs:\n  publish-gh-page:\n    runs-on: ubuntu-latest\n    steps:\n      - name: checkout code\n        uses: actions/checkout@v3\n      - name: pandoc markdown to html\n        uses: docker://pandoc/latex:3.1\n        with:\n          args: \u003e-\n            --katex --from markdown+tex_math_single_backslash --to html5+smart\n            --template=\"./scripts/template.html5\" --css=\"/panvimdoc/css/theme.css\"\n            --css=\"/panvimdoc/css/skylighting-solarized-theme.css\" --toc --wrap=none --metadata\n            title=\"panvimdoc\" doc/panvimdoc.md --lua-filter=scripts/include-files.lua\n            --lua-filter=scripts/skip-blocks.lua -t html -o public/index.html\n      - name: deploy to GitHub pages\n        uses: JamesIves/github-pages-deploy-action@v4\n        with:\n          branch: gh-pages\n          folder: public\n```\n\n### Using pre-commit locally\n\n[pre-commit](https://pre-commit.com/) lets you easily install and manage pre-commit hooks locally.\n\nTwo hooks are available, differing only in the way dependencies are handled:\n\n- `panvimdoc-docker`: Requires a running Docker engine on your host. All other dependencies will be loaded inside the container.\n- `panvimdoc`: Runs in your local environment, so you have to make sure all dependencies of panvimdoc are installed\n    (i.e., `pandoc v3.0.0` or greater)\n\nTo use a hook, first install pre-commit. Then, add the following to your `.pre-commit-config.yaml` (here `panvimdoc-docker` is used):\n\n```yaml\n- repo: 'https://github.com/kdheepak/panvimdoc'\n  rev: v4.0.1\n  hooks:\n    - id: panvimdoc-docker\n      args:\n        - '--project-name'\n        - \u003cyour-project-name\u003e\n```\n\nYou can specify additional arguments to `panvimdoc.sh` using `args`. See the section below (or run `./panvimdoc.sh`) for the full list of arguments.\n\nTo 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:\n\n```yaml\n- repo: 'https://github.com/kdheepak/panvimdoc'\n  rev: v4.0.1\n  hooks:\n    - id: panvimdoc-docker\n      files: ^.*\\.md$\n      args:\n        - '--project-name'\n        - \u003cyour-project-name\u003e\n        - '--input-file'\n        - \u003cyour-input-file.md\u003e\n```\n\n### Using it manually locally\n\nThe `./panvimdoc.sh` script runs `pandoc` along with all the filters and custom output writer.\n\n```bash\n$ ./panvimdoc.sh\nUsage: ./panvimdoc.sh --project-name PROJECT_NAME --input-file INPUT_FILE --vim-version VIM_VERSION --toc TOC --description DESCRIPTION --dedup-subheadings DEDUP_SUBHEADINGS --treesitter TREESITTER\n\nArguments:\n  --project-name: the name of the project\n  --input-file: the input markdown file\n  --vim-version: the version of Vim that the project is compatible with\n  --toc: 'true' if the output should include a table of contents, 'false' otherwise\n  --description: a project description used in title (if empty, uses neovim version and current date)\n  --dedup-subheadings: 'true' if duplicate subheadings should be removed, 'false' otherwise\n  --title-date-pattern: '%Y %B %d' a pattern for the date that used in the title\n  --demojify: 'false' if emojis should not be removed, 'true' otherwise\n  --treesitter: 'true' if the project uses Tree-sitter syntax highlighting, 'false' otherwise\n  --ignore-rawblocks: 'true' if the project should ignore HTML raw blocks, 'false' otherwise\n  --doc-mapping: 'true' if the project should use h4 headers as mapping docs, 'false' otherwise\n  --doc-mapping-project-name: 'true' if tags generated for mapping docs contain project name, 'false' otherwise\n  --shift-heading-level-by: 0 if you don't want to shift heading levels , n otherwise\n  --increment-heading-level-by: 0 if don't want to increment the starting heading number, n otherwise\n```\n\nYou will need `pandoc v3.0.0` or greater for this script to work.\n\n# Motivation\n\nWriting user-friendly documentation is important for every successful software project. This is\nparticularly true when writing documentation for users in the world of vim plugins.\n\nThe process of writing and maintaining this documentation can often be a cumbersome, time-consuming\ntask. This project is aims to make that process a little bit easier by allowing anyone to write\ndocumentation in markdown (or any format Pandoc supports) and converting it to vimdoc automatically.\nThis way, plugin authors will have to write documentation just once (for example, as part of the\nREADME of the project), and the vim documentation can be autogenerated.\n\n## Rationale\n\n1. **Simplicity**: Writing in Markdown is often more intuitive for developers. By converting from\n   Markdown to vimdoc, authors can maintain the simplicity of Markdown while adhering to the vimdoc\n   standards.\n2. **Unified Documentation**: Plugin authors can write their documentation just once (such as in the\n   project's README) and automatically generate vim documentation, ensuring consistency and saving\n   time.\n3. **Preserving Vim Features**: Vimdoc isn’t just plain text; it supports syntax highlighting, tags,\n   links, and careful formatting using whitespace. It's essential to preserve these features when\n   converting to ensure the quality and usefulness of the documentation. See\n   \u003chttps://vimhelp.org/helphelp.txt.html#help-writing\u003e or\n   [`@nanotree`'s project](https://github.com/nanotee/vimdoc-notes) for more information.\n4. **Leveraging Pandoc**: Unlike existing solutions, this project leverages Pandoc's wide range of\n   features, including support for multiple Markdown flavors and easy-to-write custom filters in\n   Lua.\n5. **Interoperability**: The choice of Pandoc allows for enhanced flexibility, making it easier to\n   extend functionality or even adapt the converter for other documentation formats in the future.\n\n## Background\n\nWriting documentation in Markdown and converting it to vimdoc is not a novel idea.\n\nFor example, [ibhagwan/ts-vimdoc.nvim](https://github.com/ibhagwan/ts-vimdoc.nvim) is an\nimplementation a neovim treesitter based markdown to vimdoc converter that works fairly well. There\nare no dependencies except for the Markdown treesitter parser. It is neovim only but you can use\nthis on github actions even for a vim plugin documentation.\n\nThere's also [wincent/docvim](https://github.com/wincent/docvim) which is written in Haskell.\nFinally, there's [FooSoft/md2vim](https://github.com/FooSoft/md2vim) which is written in Go.\n\nHowever, none of these projects use Pandoc. Pandoc Markdown supports a wide number of features: See\n\u003chttps://pandoc.org/MANUAL.html\u003e for more information. Most importantly, it supports a range of\nMarkdown formats and flavors. And, Pandoc has filters and a custom output writer that can be\nconfigured in lua. Pandoc filters can extend the capability of Pandoc with minimal lua scripting,\nand these are very easy to write and maintain too.\n\nThat means, with this project, you can write your Vim documentation in Markdown, RestructuredText,\nAsciiDoc, etc and convert it to VimDoc, PDF, Word, HTML etc.\n\n# Goals\n\nBy offering a specification and reference implementation for converting Pandoc Markdown to vimdoc,\nthis project aims to reduce friction in the documentation process for vim plugin authors.\n\nHere are the specific goals that guide this project:\n\n- **Readability**: The Markdown files must render correctly when presented as README files on\n  platforms like GitHub, GitLab, or SourceHut.\n- **Web-Friendly HTML**: If converted to HTML using Pandoc, the Markdown files must be web-friendly\n  and render appropriately.\n- **VimDoc Features**: The generated vim documentation must support essential features like links\n  and tags.\n- **Aesthetically Pleasing**: The vim documentation must not only be functional but also visually\n  pleasing in both vim and plain text files. This includes the appropriate use of columns and\n  spacing.\n- **Guidelines**: While the format of built-in Vim documentation is a valuable reference, it is used\n  as a guideline rather than a specification.\n\n# Features\n\nThis project offers a comprehensive suite of features designed to streamline the conversion process\nfrom Markdown to vimdoc:\n\n- Automatically generates titles for vim documentation.\n- Creates a table of contents to enhance navigation within the document.\n- Automatically handles the generation of links and tags.\n- Maintains markdown syntax for tables, ensuring proper rendering.\n- Allows for manual control through raw vimdoc syntax where necessary.\n- Offers the ability to include multiple Markdown files, providing flexibility in documentation\n  structure.\n\n# Specification\n\nThe specification is described in [panvimdoc.md](./doc/panvimdoc.md) along with examples. The\ngenerated output is in [panvimdoc.txt](./doc/panvimdoc.txt). The reference implementation of the\nPandoc lua filter is in [panvimdoc.lua](./scripts/panvimdoc.lua). See [panvimdoc.sh](./panvimdoc.sh)\nfor how to use this script, or check the [Usage](#usage) section.\n\n\u003c!-- panvimdoc-ignore-start --\u003e\n\nIf you would like to contribute to the specification, or if you have feature requests or opinions,\nplease feel free to comment here: \u003chttps://github.com/kdheepak/panvimdoc/discussions/11\u003e.\n\n\u003c!-- panvimdoc-ignore-end --\u003e\n\n# References\n\n- \u003chttps://learnvimscriptthehardway.stevelosh.com/chapters/54.html\u003e\n- \u003chttps://github.com/nanotee/vimdoc-notes\u003e\n- \u003chttps://github.com/mjlbach/babelfish.nvim\u003e\n- \u003chttps://foosoft.net/projects/md2vim/\u003e\n- \u003chttps://github.com/wincent/docvim\u003e\n- \u003chttps://github.com/Orange-OpenSource/pandoc-terminal-writer/\u003e\n\n# Donate\n\nIf you've found this project helpful, you can show your appreciation by sponsoring me on [GitHub Sponsors](https://github.com/sponsors/kdheepak/) or [donating via Strip](https://donate.stripe.com/8wM9E7bBO9ZsbGUdQR).\n","funding_links":["https://github.com/sponsors/kdheepak","https://donate.stripe.com/8wM9E7bBO9ZsbGUdQR","https://github.com/sponsors/kdheepak/"],"categories":["Programming Languages Support","CSS","Lua"],"sub_categories":["Markdown and LaTeX"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdheepak%2Fpanvimdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkdheepak%2Fpanvimdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdheepak%2Fpanvimdoc/lists"}