文档

文档 (opens new window) 构建 (opens new window)

使用pandoc markdown (opens new window)编写文档。生成vimdoc文档。

image (opens new window)

::: center 此软件根据MIT许可证发布。 :::

支持该项目 #

如果您发现此项目有帮助，请考虑支持其持续开发和维护。您可以在GitHub Sponsors上赞助我或进行捐款。 通过Strip进行捐赠：

赞助 @kdheepak (opens new window) 捐赠 (opens new window)

每一点赞助都有帮助，无论是给我买一杯咖啡还是让我有更多时间来维护和改进这个项目。我真诚地感谢你的慷慨和支持！

TLDR #

  1. 为你的项目选择一个名称，即${VIMDOC_PROJECT_NAME}。参考 .github/workflows/panvimdoc.yml (opens new window) 作为示例。

  2. 添加 将下面的Markdown翻译成中文并删除第一级标题：将以下内容添加到./.github/workflows/panvimdoc.yml：

name: panvimdoc

on: [push]

jobs:
  docs:
    runs-on: ubuntu-latest
    name: pandoc转换为vimdoc
    steps:
      - uses: actions/checkout@v2
      - uses: kdheepak/panvimdoc@main
        with:
          vimdoc: ${VIMDOC_PROJECT_NAME}
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "自动生成文档"
          branch: ${{ github.head_ref }}
  1. README.md文件将被转换为./doc/${VIMDOC_PROJECT_NAME}.txt并提交到仓库。

使用方法 #

使用Github Actions #

创建一个空的文档文件：

touch doc/${VIMDOC_PROJECT_NAME}.txt
git commit -am "添加空的文档"
git push

实际上你不需要这个文件，只需要doc文件夹，但是创建一个文件可能是最简单的。

然后将以下内容添加到./.github/workflows/panvimdoc.yml： 工作： 文档： 运行在：ubuntu-latest 名称：pandoc to vimdoc 步骤： - 使用：actions/checkout@v2 - 名称：panvimdoc 使用：kdheepak/panvimdoc@main 参数： vimdoc: ${VIMDOC_PROJECT_NAME} # 输出的vimdoc项目名称（必填） # 以下都是可选的 pandoc: "README.md" # 输入的pandoc文件 version: "NVIM v0.8.0" # Vim版本号 toc: true # 目录 description: "" # 项目描述 demojify: false # 从vimdoc中删除表情符号 dedupsubheadings: true # 添加标题到子标题锚链接以确保子标题是唯一的 treesitter: true # 使用treesitter对代码块进行高亮显示 ignorerawblocks: true # 在将markdown转换为vimdoc时忽略原始HTML块 docmapping: false # 使用h4标题作为映射文档 docmappingprojectname: true # 在编写映射文档时使用项目名称作为标签 将以下的Markdown翻译成中文并删除一级标题：

shiftheadinglevelby: 0 # 按指定数字移动标题级别
incrementheadinglevelby: 0 # 按指定数字增加标题级别

你需要做的唯一必要的事情就是适当选择一个VIMDOC_PROJECT_NAME。通常这是插件的名称或不带.txt扩展名的文档文件的名称。例如，下面的示例：

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

将输出一个名为doc/panvimdoc.txt的文件，并且该文件的vim帮助标签将使用存储库的main分支，标签为panvimdoc。

所有其他选项都是可选的。

建议您固定到一个确切的版本，这样您和用户就可以确信不会出现意外情况。请访问https://github.com/kdheepak/panvimdoc/releases/latest (opens new window)查看要使用的版本。选择一个版本后，可以像下面这样固定它：

- name: panvimdoc
  uses: kdheepak/[email protected]
``` 以下是如何使用此操作的示例之一：

*   [kdheepak/panvimdoc](https://github.com/kdheepak/panvimdoc/blob/main/.github/workflows/panvimdoc.yml)：[doc/panvimdoc.txt](https://github.com/kdheepak/panvimdoc/blob/main/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)

或者，请查看任何依赖此操作的软件包：[https://github.com/kdheepak/panvimdoc/network/dependents](https://github.com/kdheepak/panvimdoc/network/dependents)

如果您希望将您的vim插件文档作为HTML页面提供，请查看[.github/workflows/docs.yml](https://github.com/kdheepak/panvimdoc/blob/main/.github/workflows/docs.yml)文件。

```yaml
name: docs

on:
  push:
    branches: main

permissions:
  contents: write

jobs:
  publish-gh-page:
    runs-on: ubuntu-latest
    step 使用手动方式

`./panvimdoc.sh`脚本运行`pandoc`以及所有过滤器和自定义输出写入器。

```shell
$ ./panvimdoc.sh
用法：./panvimdoc.sh --project-name 项目名称 --input-file 输入文件 --vim-version VIM_VE Arguments:
  --project-name：项目名称
  --input-file：输入的 Markdown 文件
  --vim-version：与项目兼容的 Vim 版本
  --toc：如果输出应包含目录，则为 'true'，否则为 'false'
  --description：项目的描述
  --dedup-subheadings：如果应删除重复的子标题，则为 'true'，否则为 'false'
  --demojify：如果不删除表情符号，则为 'false'，否则为 'true'
  --treesitter：如果项目使用 Tree-sitter 语法高亮，则为 'true'，否则为 'false'
  --ignore-rawblocks：如果项目应忽略 HTML 原始块，则为 'true'，否则为 'false'
  --doc-mapping：如果项目应使用 h4 标题作为映射文档，则为 'true'，否则为 'false'
  --doc-mapping-project-name：如果为映射文档生成的标签包含项目名称，则为 'true'，否则为 'false'
  --shift-heading-level-by：如果不需要移动标题级别，则为 0 不想改变标题级别，否则
  --increment-heading-level-by: 如果不想增加起始标题编号，则为0，否则为n

您需要 pandoc v3.0.0 或更高版本才能运行此脚本。

动机

编写用户友好的文档对于每个成功的软件项目都很重要。当为 vim 插件的用户编写文档时，尤其如此。

编写和维护这些文档的过程往往是一项繁琐、耗时的任务。该项目旨在通过允许任何人使用 markdown（或 Pandoc 支持的任何格式）编写文档并自动转换为 vimdoc，从而使这个过程变得更加简单。这样，插件作者只需编写一次文档（例如，作为项目的 README 的一部分），就可以自动生成 vim 文档。

原理

  1. 简单性：对于开发人员来说，使用 Markdown 编写通常更直观。通过从 Markdown 中转换为 kdown 到 vimdoc，作者可以保持 Markdown 的简洁性，同时遵循 vimdoc 的标准。
  2. 统一文档：插件作者可以只写一次文档（比如在项目的 README 中），然后自动生成 vim 文档，确保一致性并节省时间。
  3. 保留 Vim 的特性：Vimdoc 不仅仅是纯文本；它支持语法高亮、标签、链接以及使用空格进行仔细格式化。在转换时保留这些特性是确保文档的质量和实用性的关键。请参阅 https://vimhelp.org/helphelp.txt.html#help-writing (opens new window) 或 @nanotree 的项目 (opens new window) 获取更多信息。
  4. 利用 Pandoc：与现有解决方案不同，该项目利用了 Pandoc 的广泛功能，包括对多种 Markdown 风格的支持以及使用 Lua 编写易于编写的自定义过滤器。
  5. 互操作性： 选择Pandoc可以提供更强大的灵活性，使得扩展功能甚至为将来适应其他文档格式的转换器变得更加容易。

背景 #

使用Markdown撰写文档并将其转换为vimdoc并不是一个新颖的想法。

例如，ibhagwan/ts-vimdoc.nvim (opens new window) 是一个基于neovim treesitter的Markdown到vimdoc转换器的实现，效果相当不错。除了Markdown treesitter解析器外，它没有其他依赖项。它仅适用于neovim，但即使对于vim插件文档，您也可以在github actions中使用它。

还有一个用Haskell编写的项目wincent/docvim (opens new window)。最后，还有一个用Go编写的项目FooSoft/md2vim (opens new window)。

这些项目都没有使用Pandoc。Pandoc Markdown支持许多功能：更多信息请参见https://pandoc.org/MANUAL.html (opens new window)。最重要的是， 它支持多种Markdown格式和风格。而且，Pandoc具有过滤器和自定义输出写入器，可以通过lua进行配置。Pandoc过滤器可以通过最小的lua脚本扩展Pandoc的功能，而且编写和维护这些过滤器也非常容易。

这意味着，通过这个项目，你可以用Markdown、RestructuredText、AsciiDoc等编写你的Vim文档，并将其转换为VimDoc、PDF、Word、HTML等格式。

目标 #

通过为将Pandoc Markdown转换为vimdoc提供规范和参考实现，该项目旨在降低Vim插件作者在文档过程中的阻力。

以下是指导该项目的具体目标：

  • 可读性：Markdown文件在像GitHub、GitLab或SourceHut等平台上作为README文件显示时必须正确渲染。
  • 适用于Web的HTML：如果使用Pandoc转换为HTML，Markdown文件必须适用于Web并正确渲染。
  • VimDoc功能：生成的vim文档必须具备VimDoc的特性。 以下是将Markdown翻译为中文并删除一级标题的结果：

美观：Vim文档不仅要具备功能性，还要在Vim和纯文本文件中具备视觉上的美感。这包括适当使用列和间距。

指导方针：虽然内置Vim文档的格式是有价值的参考，但它只是用作指导方针，而不是严格的规则。

特点 #

该项目提供了一套全面的特点，旨在简化从Markdown到vimdoc的转换过程：

  • 自动为vim文档生成标题。
  • 创建目录以增强文档内导航。
  • 自动处理链接和标签的生成。
  • 保持Markdown表格的语法，确保正确渲染。
  • 在必要时通过原始vimdoc语法进行手动控制。
  • 提供包含多个Markdown文件的能力，提供灵活性的文档结构。

规范 规范详见panvimdoc.md (opens new window)，包含示例。生成的输出位于panvimdoc.txt (opens new window)中。Pandoc lua过滤器的参考实现在panvimdoc.lua (opens new window)中。查看panvimdoc.sh (opens new window)以了解如何使用此脚本，或者查看使用方法部分。 #

如果您想要为规范做出贡献，或者有功能请求或意见，请随时在此处发表评论：#11 (opens new window)。

参考资料 #