block IALs do not work with GitHub Flavored Markdown

[adoyle-h]

Describe the bug

{:toc} and {: .no_toc } not work when change the markdown processor from Kramdown to GFM.

To Reproduce
Steps to reproduce the behavior:

1. Add markdown: GFM in _config.yml file.
2. build just-the-docs
3. It shows {:toc} and {: .no_toc } as text in page.

Expected behavior

Generate a Table of Contents in page.

Screenshots

Desktop (please complete the following information):

• OS: MacOS
• Browser: chrome 109.0.5414.119
• Version: actions/jekyll-build-pages@v1

[mattxwang]

Hi @adoyle-h, thanks for submitting this issue. {:toc} is not a feature in GFM, it's a kramdown-specific tag¹. In addition, the general idea of block IALs - the {: .no_toc } one, for example - is also a kramdown-specific feature, and is not a part of the standard markdown syntax (or GFM). To use many of the features in Just the Docs, you have to use kramdown as your markdown parser (or, something else that inspires from Marufuku, etc.).

So, with that in mind, this is not something that Just the Docs can't really help you do directly. However, you may gain some benefits from looking in to Jekyll plugins that do this for you, or using other command-line tools that automatically generate TOCs.

Hope this made sense / helps; let me know if you have any other questions!

(also, if I could ask, is there a specific reason you want to use GFM instead of kramdown?)

Footnotes

1. My understanding of this is from skimming the GFM spec and searching for toc. ↩

[adoyle-h]

@mattxwang Thanks for your detailed response. I get it now.

The reason for using GFM instead of kramdown is that kramdown has not supported Automatic URL Linking
since 2016. It is still a opening issue in kramdown/parser-gfm.
And I have not found any Jekyll plugin can make Automatic URL Linking.

[mattxwang]

Gotcha, thanks for the quick response. I don't have a stellar suggestion for you, though you could always use a tool like Rinku; this is probably a good candidate for a gem, since a quick Google seems to indicate that no Jekyll plugin exists yet (but, it should be pretty simple - just a wrapper for Rinku in Jekyll).

Honestly, I may eventually just make this in a weekend, but I'd encourage you to develop the plugin yourself! In the meantime, I will close this issue given that it's more related to GFM rather than kramdown.