Problem:
Flow layout looks better on neovim.io. Nvim-owned help files should
switch to the new layout. Also lua-bit.txt doesn't use the same format
for function documentation as the other docs (such as api.txt).
Solution:
Switch to new layout. Tweak the function documentation to be in line
with the other docs style.
Problem:
List items separated by blank lines are wrapped in "blocks", then the
html generator does not treat them as contiguous list-items, and the
browser shows the list as "1. 1. 1." instead of "1. 2. 3.".
Solution:
- When generating a list-item, check if the last child of the previous
block was a list-item, and merge them together.
- Massage the help source.
fix#37220
Problem:
helptag.html is used to search for the online help documentation of a
specified tag. The previous URL was `/doc/user/helptag.html` but that
switched to `/doc/user/helptag/` in
https://github.com/neovim/neovim.github.io/pull/437. The alias of the
.html page was added to all other doc pages but forgotten for the
helptag.html page
Solution:
Add the alias to the helptag.html page too
Problem:
Descriptions of plugins often contain taglinks which are generally
concealed. This misaligns them by 2 characters with descriptions that
don't have a taglink in them.
Solution:
Don't count "bar" characters (`|`) for the description width.
Example:
Actual buffer content:
```
myplugin.txt |lsp| is cool
myplugin.txt this is a nice plugin
```
Rendered as:
```
myplugin.txt lsp is cool
myplugin.txt this is a nice plugin
```
Problem:
The html and css of the website's documentation pages are defined in
long strings in gen_help_html.lua, making it hard to maintain and
improve them. E.g. adding in headers that state the documentation is for
nightly Nvim has been a long standing feature request.
Solution:
Move the inlined css and html (e.g. the <head>, <nav>, etc.) to Hugo.
Now that the website is build with Hugo, we can use its templating
system to generate the full html/css from the Tree-sitter tree:
https://github.com/neovim/neovim.github.io/pull/437
Call `vim.treesitter.language.add()` before `get_helptags` (which
triggers filetype=help). And do this in the main routine, instead of
each gen/validate task.
Problem:
scripts/check_urls.vim manually matches urls in the help pages and then
synchronously checks them via curl/wget/powershell. This is extremely
slow (~5 minutes for Nvims runtime on my machine) and prone to errors in
how the urls are matched.
Solution:
- Use Tree-sitter to find the urls in the help pages and `vim.net.request` to
check the responses.
- Add a `lintdocurls` build task and check it in CI (every Friday).
- Reopens a dedicated issue if it finds unreachable URLs.
- Drop the old check_urls.vim script.
Problem:
fe4faaf81a added an invalid "redirect" item, which caused the
assert() to fail, which then caused the neovim/doc/ CI to fail:
https://github.com/neovim/doc/actions/runs/18830779387/job/53721736276 :
The previous commit e69beb9b1a tried to fix a different issue, which
has gone hidden because the "invalid tags" failure has been present on
the neovim/doc/ but was silently failing.
invalid tags: {
["g:netrw_keepdir"] = "usr_22.txt",
netrw = "vi_diff.txt",
...
plugins = "editorconfig"
}
Solution:
- Fix the invalid redirect.
- Improve the redirects assertion.
Problem:
The doc/ repo CI is failing
https://github.com/neovim/doc/actions/runs/18830779387/job/53721736276 :
invalid tags: {
["g:netrw_keepdir"] = "usr_22.txt",
netrw = "vi_diff.txt",
["netrw-P"] = "usr_22.txt",
...
["netrw-v"] = "usr_22.txt",
plugins = "editorconfig"
}
Solution:
Add the "generate netrw tags" hack to the `gen()` step. Previously it was only
in the `validate()` step. (idk why it only started failing 3 days ago...)
It helps to have plugins living in one common area, because it signals
to users the mechanisms for controlling them, which are typically driven
by keymaps and autocmds rather than builtin options.
We can always revisit if plugins.txt gets "too big" (for example, we may
want to introduce "project.txt" for the project concept, where
editorconfig and 'exrc' are relevant), but for now it's rather unusual
for editorconfig.txt to have its own dedicated helpfile.
- Problem: It's not clear for new plugin developers that `:help` uses
a help-tags file for searching the docs, generated by `:helptags`.
- Solution: Hint to the |:helptags| docs for regenerating the tags
file for their freshly written documentation.
Co-authored-by: Yochem van Rosmalen <git@yochem.nl>
Problem:
No way to know the html page with the docs of a tag when you only have
the tag name.
Solution:
Generate a helptags.json that maps tags to their locations.
Generate a helptag.html page that redirects to the HTML page of the given tag.
Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
Problem:
gen_help_html.lua script misinterprets parts of ASCII diagrams as help tags
(e.g., `|_________|` in `usr_28.txt`). This incorrectly triggered
special alignment-fixing logic that is meant for columnar text.
Signed-off-by: Shashwat Agrawal <shashwatagrawal473@gmail.com>
Problem:
Despite the name, `builtin.txt` only includes Vimscript functions, which
is confusing, especially to people who only use Lua to configure Nvim
Solution: From justinmk's suggestion
- Rename `builtin.txt` to `vimfn.txt`
- Rename `eval.txt` to `vimeval.txt`
- The tags `*builtin.txt*` and `*eval.txt*` should be kept for Vim-patches
Closes#33743
Problem:
"make lintdoc" is not validating vimdoc (:help) tags.
Solution:
- Call `lang_tree:parse()` to init the parser.
- Load netrw 🤢 explicitly, since it was moved to `pack/dist/opt/`.
- Fix invalid help tags.
Problem:
Indenting text is a common task in plugins/scripts for
presentation/formatting, yet vim has no way of doing it (especially
"dedent", and especially non-buffer text).
Solution:
Introduce `vim.text.indent()`. It sets the *exact* indentation because
that's a more difficult (and thus more useful) task than merely
"increasing the current indent" (which is somewhat easy with a `gsub()`
one-liner).
- Move all generator Lua scripts to the `src/gen/`
- Add a `.luarc.json` to `src/gen/`
- Add a `preload.lua` to `src/gen/`
- Add `src` to `package.path` so it aligns with `.luarc.json'
- Fix all `require` statements in `src/gen/` so they are consistent:
- `require('scripts.foo')` -> `require('gen.foo')`
- `require('src.nvim.options')` -> `require('nvim.options')`
- `require('api.dispatch_deprecated')` -> `require('nvim.api.dispatch_deprecated')`
