search

pseudomuto / protoc-gen-doc

Documentation generator plugin for Google Protocol Buffers
MIT License
2.59k stars 462 forks source link

Escape special characters in Markdown anchors #460

Closed derlin closed 2 years ago

derlin commented 2 years ago

Using the full name (with dots and slashes) in markdown anchors may be problematic in some rendering engines. For example, BitBucket won't accept this kind of anchors (with special characters), making the inner links and navigation broken.

Since the template defines its own anchors (with a tags), changing the inner links format has no impact on e.g. GitHub or Gitlab.

This commit adds a new sprig filter, anchor, and ensures it is used throughout the markdown template. The filter first replaces all / with _, then all remaining special characters with -.

It has been tested both using the examples in this repo and other, more complex examples. It has been proven not to impact the result on GitHub in any way, and the navigation now works on BitBucket as well.

This could be a minor release (not sure if I have to add the label myself or not).

see #457

derlin commented 2 years ago

@pseudomuto , @sunfmin : as per the contributing guide, here is a little ping :)

pseudomuto commented 2 years ago

Hey @derlin this LGTM 👍 Thanks for the PR!

derlin commented 2 years ago

Wow, wasn't expecting such a fast response, thank YOU !

Do you think it could be possible to tag this contribution with the label hacktoberfest-accepted (see Hacktoberfest) ? It of course perfectly fine if you don't, this repo is great and I would have contributed to it anyways :)

pseudomuto commented 2 years ago

Tagged! Thanks again for the PR!