GFM Compliancy Issues

[tajmone]

As you can see from this markdown page:

• https://github.com/tajmone/lemon-grove/blob/f731ee9df4b/lemon/lemon.md

The generated TOC doesn't cope well with special characters in the heading (backticks in this case, for inline code in headings).

Setting autoanchor="true" doesn't help much on GitHub for in the preview all HTML anchors are stripped out.

In the above example, you can see various following commits that try other TOC configurations, but none worked — ultimately, I had to reduce the TOC levels to hide the broken links.

Inline code in headings is quite common (e.g. keywords in titles), and even with uri_encoding="flase" they get encoded.

I think that due to GitHub and GFM popularity, it might be worthy adding a dedicated setting targetting GitHub docs, and to make the package 100% GitHub compliant.

[naokazuterada]

@tajmone Hi, thank you for reporting!

The generated TOC doesn't cope well with special characters in the heading (backticks in this case, for inline code in headings).

I confirmed it. Sorry, I will treat this problem this weekend.

In the above example, you can see various following commits that try other TOC configurations, but none worked — ultimately, I had to reduce the TOC levels to hide the broken links.

OK, I will look!

Inline code in headings is quite common (e.g. keywords in titles), and even with uri_encoding="flase" they get encoded.

The value is invalid in your code, Please try "false".

I think that due to GitHub and GFM popularity, it might be worthy adding a dedicated setting targetting GitHub docs, and to make the package 100% GitHub compliant.

I agree and I've prepared this configuration for that.

[tajmone]

I've created some test files in an old tests repository of mine:

https://github.com/tajmone/github-tests/tree/master/MarkdownTOC

I've also invited you to the project, so you can experiment and push changes too.

I've tried various settings, but the problem seems to be that the spcial char % is preserved in the generated link.

Inline code in headings is quite common (e.g. keywords in titles), and even with uri_encoding="flase" they get encoded.

The value is invalid in your code, Please try "false".

Good catch! that typo went unnoticed, but even with false the problem persists.

I agree and I've prepared this configuration for that.

After the last major update, when I had to reconfigure MarkdownTOC settings, I had carried out various tests and finally opted to add the following inline settings to all GFM docs for GitHub:

<!-- MarkdownTOC autolink="true" bracket="round"
     autoanchor="false" lowercase="only_ascii"
     uri_encoding="true" levels="1,2,3"
-->

I can't remember why I had decided to add the uri_encoding="true" settings, but I'm quite sure it was because of tests with headings containing accented letters (which we use a lot in Italian). You might consider adding that setting to the guidlines at the above link.

But my proposal was to add a new setting like github="true" so that in the actual documents users could just add:

<!-- MarkdownTOC github="true" levels="1,2,3" -->

... and never have to worry about future changes in how GitHub handles creation of anchors, or changes in MarkdownTOC internals — the github option should always produce GitHub compatible links.

[tajmone]

Maybe, instead of github="true" you could introduce a setting like host="github" which could accept values like github, gitlab, bitbucket, etc.

This would allow a simple way to ensure that TOCs are generated in compliance with the major online Git services, and ensure that a document with these settings will always work in the future, by updating how MarkdownTOC implements them at save time.

Hiding the actual configuration details behind a value representing the destination platform/service is easier for end users, especially if these differ in the way the generate heading anchors, or change system in time.

MarkdownTOC should provide some default settings for github, gitlab, bitbucket, etc., but also allow end users to override them or create new ones.

[naokazuterada]

I looked into your problem and noticed id_replacements helps. Please add |% in the value of pattern key in the id_replacements values. Check here.

In this case, uri_encoding was not relevant. Just remove % in IDs.

Demo on GitHub: https://github.com/naokazuterada/MarkdownTOC-Tests/blob/master/example-for-issue139.md

Please close this issue if my answer solved your problem.

---

I create another issue for your suggestion(host="github"). I will consider carefully because it seems to contain many problems in the real.

https://github.com/naokazuterada/MarkdownTOC/issues/141

Thanks!

[tajmone]

Thanks, it worked:

• https://github.com/tajmone/lemon-grove/blob/master/lemon/lemon.md