panvimdoc.txt

*panvimdoc.txt*         For NVIM v0.8.0         Last change: 2023 September 17

==============================================================================
Table of Contents                                *panvimdoc-table-of-contents*

1. panvimdoc                                             |panvimdoc-panvimdoc|
2. Support This Project                       |panvimdoc-support-this-project|
3. TLDR                                                       |panvimdoc-tldr|
4. Usage                                                     |panvimdoc-usage|
5. Motivation                                           |panvimdoc-motivation|
  - Rationale                                 |panvimdoc-motivation-rationale|
  - Background                               |panvimdoc-motivation-background|
6. Goals                                                     |panvimdoc-goals|
7. Features                                               |panvimdoc-features|
8. Specification                                     |panvimdoc-specification|
9. References                                           |panvimdoc-references|
10. Specification                                    |panvimdoc-specification|
  - External includes              |panvimdoc-specification-external-includes|
  - Codeblocks                            |panvimdoc-specification-codeblocks|
11. Title                                                    |panvimdoc-title|
12. Heading                                                |panvimdoc-heading|
  - Sub Heading 2                            |panvimdoc-heading-sub-heading-2|
  - Markdown Links                          |panvimdoc-heading-markdown-links|
  - Linking to help tags              |panvimdoc-heading-linking-to-help-tags|
  - Mappings                                      |panvimdoc-heading-mappings|
  - Table                                            |panvimdoc-heading-table|
  - Markdown only content            |panvimdoc-heading-markdown-only-content|
  - Vimdoc only content                |panvimdoc-heading-vimdoc-only-content|
  - Details and summary                |panvimdoc-heading-details-and-summary|
  - Keyboard HTML tag                    |panvimdoc-heading-keyboard-html-tag|
  - Examples                                      |panvimdoc-heading-examples|
  - Examples                                      |panvimdoc-heading-examples|
  - Remove emojis                            |panvimdoc-heading-remove-emojis|

==============================================================================
1. panvimdoc                                             *panvimdoc-panvimdoc*

<https://kdheepak.com/panvimdoc/>
<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.



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


==============================================================================
2. Support This Project                       *panvimdoc-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:

<https://github.com/sponsors/kdheepak>
<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!


==============================================================================
3. TLDR                                                       *panvimdoc-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.


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

>yaml
    name: panvimdoc
    
    on: [push]
    
    jobs:
      docs:
        runs-on: ubuntu-latest
        name: pandoc to 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: "Auto generate docs"
              branch: ${{ github.head_ref }}
<


3. `README.md` gets converted to `./doc/${VIMDOC_PROJECT_NAME}.txt` and committed
to the repo.




==============================================================================
4. Usage                                                     *panvimdoc-usage*


USING GITHUB ACTIONS ~

Create an empty doc file:

>bash
    touch doc/${VIMDOC_PROJECT_NAME}.txt
    git commit -am "Add empty doc"
    git push
<

You don’t actually need the file, only the `doc` folder but it is probably
easiest to create a file.

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

>yaml
    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} # 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)
              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`
appropriately. This is usually the name of the plugin or the documentation file
without the `.txt` extension. For example, the following:

>yaml
    - 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:

>yaml
    - name: panvimdoc
      uses: kdheepak/panvimdoc@vX.X.X
<

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>

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

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.

>yml
    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.

>bash
    $ ./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
      --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.


==============================================================================
5. Motivation                                           *panvimdoc-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                                     *panvimdoc-motivation-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 <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                                   *panvimdoc-motivation-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.

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 <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.


==============================================================================
6. Goals                                                     *panvimdoc-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.


==============================================================================
7. Features                                               *panvimdoc-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.


==============================================================================
8. Specification                                     *panvimdoc-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 |panvimdoc-usage| section.


==============================================================================
9. References                                           *panvimdoc-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/>


==============================================================================
10. Specification                                    *panvimdoc-specification*

See ./panvimdoc.txt <./panvimdoc.txt> for generated output of this file.


EXTERNAL INCLUDES                  *panvimdoc-specification-external-includes*

Use the following in your markdown file to include any other markdown file:

>markdown
    ```{.include}
    README.md
    ```
<

The path of the file is with respect to the working directory where `pandoc` is
executed.


CODEBLOCKS                                *panvimdoc-specification-codeblocks*

>
    Multi line Code blocks are indented 4 spaces and
    
    are formatted
    
    appropriately with > and <.
<

Alternatively, you can use `vimdoc` as the language for the code block to write
raw text that will be inserted into the final document.

For example, the following:

>
    ```vimdoc
    You can use codeblocks that have language as `vimdoc` to write raw vimdoc.
    ```
<

will be rendered verbatim in the generated documentation.

This can be used to write any custom whitespace formatted documentation in the
generated vimdoc (for mappings, options etc).


==============================================================================
11. Title                                                    *panvimdoc-title*

The first line of the documentation that is generated will look something like
this:

>
    *panvimdoc.txt*    For VIM - Vi IMproved 8.1       Last change: 2021 August 11
<


==============================================================================
12. Heading                                                *panvimdoc-heading*

Main headings are numbered.


SUB HEADING 2                                *panvimdoc-heading-sub-heading-2*

Sub headings are upper cased heading.

Notice that both headings and subheadings have tags.


SUB HEADING 3 ~

Sub headings are upper cased, but do not have tags. They are also not included
in the TOC. They are suffixed with `~` which highlights as **bold** text when
the file is viewed on GitHub.


MARKDOWN LINKS                              *panvimdoc-heading-markdown-links*

You can use markdown links in vimdoc.

>markdown
    You can link to the tags by using [sub heading 2](#sub-heading-2).
<

This way, any links will work in markdown README on GitHub or on the web using
anchors AND will work as tags and links in vimdoc. The anchors are simply
dropped in vimdoc inline. The onus is on the documentation writer to choose the
correct anchor for the appropriate Markdown link.

In vimdoc tags are created when anchors to the internal document are used. If
the target is an external link, the link is inlined.

If the external link is to the neovim documentation, an internal vim link is
generated. For example:

- |cursorcolumn|
- |`completeopt`|
- vim <https://github.com/vim/vim>
- neovim <https://github.com/neovim/neovim>

This is excluded from the links section.

Lastly, if the markdown text is a url, the link is not added to the links
section and instead is placed inline.


LINKING TO HELP TAGS                  *panvimdoc-heading-linking-to-help-tags*

Markdown doucments may suggest help tags via |help-tag|, which are converted to
`|help-tag|` "hot links" in vimdoc.


MAPPINGS                                          *panvimdoc-heading-mappings*

While you can use codeblocks with the language `vimdoc` to insert text in the
generated vimdoc, it can be useful to have a markdown friendly way to write
documentation for mappings.

Pandoc supports definition lists:
<https://pandoc.org/MANUAL.html#definition-lists>. This can be used to generate
documentation of mappings. All of the content in curly braces `{...}` that is
part of the header is dropped and a tag is created.

For example, the following in a markdown file:

>markdown
    :FnlCompileBuffer
    
    : Compiles current active fennel buffer
    
    :FnlCompile[!]
    
    : Diff compiles all indexed fennel files
    If bang! is present then forcefully compiles all `source` files
    
    :Fnl {expr}
    
    : Executes and Evalutate {expr} of fennel
    
         ```fennel
         :Fnl (print "Hello World")
    
         :Fnl (values some_var)
         ```
    
         Testing
<

becomes the following vimdoc:

>
    
                                                 *projectName-:FnlCompileBuffer*
    
    
    :FnlCompileBuffer                      Compiles current active fennel buffer
    
    
                                                       *projectName-:FnlCompile*
    
    
    :FnlCompile[!]                         Diff compiles all indexed fennel files
                                           If bang! is present then forcefully compiles all `source` files
    
    
                                                              *projectName-:Fnl*
    
    
    :Fnl {expr}                            Executes and Evalutate {expr} of fennel
                                           >fennel
                                               :Fnl (print "Hello World")
    
                                               :Fnl (values some_var)
                                           <
                                           Testing
<

Notice that the tag `*projectName-:Command*` is generated for you.
Additionally, content in square brackets `[...]` or curly brackets `{...}` is
also dropped for creating the tag name.

i.e. the term `### :[range]Command` becomes the tag `*projectName-:Command*`.

See following mappings as examples:


                                                              *panvimdoc-pv*


pv{motion}                             Command that operates over {motion} moved.




                                                             *panvimdoc-pvd*


pvd                                    Command that takes [count] lines.




                                                    *panvimdoc-:CommandName*


:[range]CommandName {doc=CommandName}  Command that operates over [range].




                                                              *panvimdoc-pv*


{Visual}pv                             Command that operates over highlighted lines.




TABLE                                                *panvimdoc-heading-table*

Support for markdown tables is also available:

  -----------------------------------------------------------------------------------------------------
  Option                               Background   Default   Description
  ------------------------------------ ------------ --------- -----------------------------------------
  lightness                            light        nil       Change background colors lightness.
                                                              Options: 'bright', 'dim'.

  darkness                             dark         nil       Change background colors darkness.
                                                              Options: 'stark', 'warm'.

  solid_vert_split                     both         false     Solid |hl-VertSplit| background.

  solid_line_nr                        both         false     Solid |hl-LineNr| background.

  solid_float_border                   both         false     Make |hl-FloatBorder| have a more
                                                              distinguishable background highlight.

  darken_noncurrent_window             light        false     Make non-current window background darker
                                                              than Normal.

  lighten_noncurrent_window            dark         false     Make non-current window background
                                                              lighter than Normal.

  italic_comments                      both         true      Make comments italicize.

  darken_comments                      light        38        Percentage to darken comments relative to
                                                              Normal bg.

  lighten_comments                     dark         38        Percentage to lighten comments relative
                                                              to Normal bg.

  darken_non_text                      light        25        Percentage to darken |hl-NonText|
                                                              relative to Normal bg.

  lighten_non_text                     dark         30        Percentage to lighten |hl-NonText|
                                                              relative to Normal bg.

  darken_line_nr                       light        33        Percentage to darken |hl-LineNr| relative
                                                              to Normal bg.

  lighten_line_nr                      dark         35        Percentage to lighten |hl-LineNr|
                                                              relative to Normal bg.

  darken_cursor_line                   light        3         Percentage to darken |hl-CursorLine|
                                                              relative to Normal bg.

  lighten_cursor_line                  dark         4         Percentage to lighten |hl-CursorLine|
                                                              relative to Normal bg.

  colorize_diagnostic_underline_text   both         false     Colorize the fg of DiagnosticUnderline*.

  transparent_background               both         false     Make background transparent.
  -----------------------------------------------------------------------------------------------------

MARKDOWN ONLY CONTENT                *panvimdoc-heading-markdown-only-content*

Sometimes you want to show content that is to be present in Markdown and on the
rendered view on GitHub but ignored in the generated vimdoc. This can be placed
inside `panvimdoc-ignore-{start/end}` blocks:

>
    <!-- panvimdoc-ignore-start -->
    
    <details>
        <summary>Vimdoc Ignored Section</summary>
    
    This section will ignored when generating the vimdoc file.
    This will only show up in the Markdown file.
    
    </details>
    
    <!-- panvimdoc-ignore-end -->
<

The following will only be present in the Markdown document.

The convenient advantage of using `<!-- panvimdoc-ignore-{start/end} -->`
blocks in a HTML comment syntax is that the comment will not rendered in HTML
or on GitHub, giving the documentation writers control to present the
information differently on GitHub and in vimdoc. If you want to see examples of
this, see the raw markdown version of this file.

The only thing to keep in mind is that you must leave new line spaces before
and after a comment tag. For example, **do not** do this:

>
    <!-- panvimdoc-ignore-start -->
    ![screenshot](./gif.gif)
    <!-- panvimdoc-ignore-end -->
<

because it may cause the rest of your document to be ignored. Do this instead:

>
    <!-- panvimdoc-ignore-start -->
    
    ![screenshot](./gif.gif)
    
    <!-- panvimdoc-ignore-end -->
<


VIMDOC ONLY CONTENT                    *panvimdoc-heading-vimdoc-only-content*

Inversely to |panvimdoc-markdown-only-content|, sometimes you want to show
content only present in Vimdoc and hidden when viewed on Github.

This can be placed inside `panvimdoc-include-comment` comments.

As with markdown only content, you must include a blank link before and after
the comment.

>markdown
    
    <!-- panvimdoc-include-comment You can include single lines  -->
    
    <!-- panvimdoc-include-comment
    
    Or multiple lines
    
    - with other
    - content
    - types
    
    # And vimdoc only headings
    
    ## That can include subheadings
    
    Infact you can include any kind of content in the comment.
    
    -->
<

Neovim is a great text editor.

Neovim supports |lua| plugins and is also:

- Multiplatform
- Open source


DETAILS AND SUMMARY                    *panvimdoc-heading-details-and-summary*

You can even use `<details>` and `<summary>` tags for your README.md.

Summary ~

This section is the details.

The `html` tags are dropped and the following output is generated in the vimdoc
file.

If you are using html `<b> ... </b>` tags, use them on new lines. Inline bold
tags will have a `~` appended to the text and that may not be what you want.


KEYBOARD HTML TAG                        *panvimdoc-heading-keyboard-html-tag*

Use `<kbd>CMD + o</kbd>` in markdown, for example CMD + o.


EXAMPLES                                          *panvimdoc-heading-examples*

First example


EXAMPLES                                          *panvimdoc-heading-examples*

Second example


REMOVE EMOJIS                                *panvimdoc-heading-remove-emojis*


:SPARKLES: FEATURES ~


:ZAP: REQUIREMENTS ~


:PACKAGE: INSTALLATION ~

==============================================================================
13. Links                                                    *panvimdoc-links*

1. *Docs*: https:/img.shields.io/badge/docs-dev-blue.svg
2. *Build*: https:/github.com/kdheepak/panvimdoc/actions/workflows/test.yml/badge.svg?branch=main
3. *Sponsor @kdheepak*: https:/img.shields.io/badge/GitHub_Sponsor-%E2%9D%A4-blue
4. *Donate*: https:/img.shields.io/badge/Donate_Via_Stripe-%E2%9D%A4-blue

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl: