[REQ] transform TOC url

[step-]

Hi, I use CommonMark in my published documents, which I edit with wiki.vim. I couldn't find a way to transform the link URL that :WikiTocGenerate makes, so I kindly request some way to do such transformation. I'm trying to fix the following issue. In CommonMark (therefore on GitHub and other sites that base their markdown flavor on CommonMark) this is not recognized as a markdown link:

*Contents*

* [Readme](#Readme)
    * [Debugging HTML](#Readme#Debugging HTML)

but this is:

*Contents*

* [Readme](#Readme)
    * [Debugging HTML](<#Readme#Debugging HTML>)               **within angle brackets**

visual example at CommonMark Dingus page

:WikiTocGenerate creates the first markdown block above. I would like to create the second one instead, so when I publish the TOC (not only on GitHub), the intended links turn out as such.

I do realize that if the URL is wrapped in angle brackets then wiki.vim won't be able to follow the link, and that is a problem. But for now I'm more interested in publishing online than navigating the markdown source, because I can also comfortably jump through the document with other vim commands. Thanks for your consideration.

[lervag]

Thanks; I'll look into this. I believe this should already be possible, but I will need to check it. If it is possible, I'll explain how; else I'll look into how I can add it.

[lervag]

Notice, though: The url will work if you use url encoding. I.e.:

*Contents*

* [Readme](#Readme)
    * [Debugging HTML](#Readme#Debugging%20HTML)

[lervag]

If you are in a rush, then I'd advice to look into g:wiki_link_creation and the url_transform key. See also :help wiki-advanced-config-2 for an example. But you are right - this is not affective for the toc generation. It probably should be, so I'll look into it when I get the time.

[lervag]

Oh, and finally: there are third-party tools for generating toc's for markdown files. In the meantime, I think you should consider using one of those. They are actually very good. For instance, see

• https://github.com/thlorenz/doctoc
• https://github.com/jonschlinkert/markdown-toc

Both of these can be used with the plugin https://github.com/stevearc/conform.nvim, which makes it quite convenient.

[step-]

Thank you for looking into this. If the URL can work with URL encoding that's a good alternative to angle brackets. The question remains, how to transform the URL in a TOC. I do use g:wiki_link_creation, so I was hoping it would work for TOC as well, but as you also say, it doesn't.

[lervag]

I do use g:wiki_link_creation, so I was hoping it would work for TOC as well, but as you also say, it doesn't.

I'll look into this. It may be straightforward, which means I will get it done relatively fast. But I need to think it through first - perhaps it makes sense to have a further option for this. TOCs are basically links with only anchors, so we need a proper transform of the anchors themselves. This will also require a similar resolve of the anchors. And the default anchor handling in wiki.vim is not really consistent with the standard Markdown or CommonMark spec.

[lervag]

I've recently made some changes that I believe might fix this. Or, at least that are relevant; they might not be what you want because of side effects.

In particular, I've

1. Changed so that markdown documents now have their own URL scheme md: which is implied by all markdown style links like [text](url).
2. When creating links with e.g. the <cr> mapping, the links will be partially URL encoded. That is, parantheses will be encoded. This is done by defining the url_transform function which is added by default - see the updated :help wiki_link_creation docs for the current default for md.
3. The :WikiTocGenerate command now does apply the url_transform function on the links while creating the TOC for Markdown documents.

Thus, you could now probably solve your original issue with something like this:

" Perhaps url encoding is enough?
let g:wiki_link_creation = {
      \ 'md': {
      \   'url_transform': { x ->
      \     wiki#url#utils#url_encode_specific(x, ' ()') },
      \ },
      \}

" If not, then I think _this_ does what you want
let g:wiki_link_creation = {
      \ 'md': {
      \   'url_transform': { x -> "<" .. x .. ">" },
      \ },
      \}

[lervag]

I'm closing this, I'll reopen if I can't make immediate updates to keep this issue resolved.

[lervag]

Also, this issue is clearly related to #386, which I'm currently working on now. I believe a fix for #386 would also immediately make the links with <...> work as expected.