fix(docs): Use Kramdown processor

[charlottetan]

What does this PR do?

Related to PR #5810. Fixes #6508.
Using GFM causes issues with anchor tags, using Kramdown would solve the issues with anchor tags, but results in issues with links, see discussion in kramdown/parser-gfm#28. So the link was manually added, i.e., using [url](url) instead of just url.

Checklist:

• Read our contributing guidelines
• Search for duplicates.
• Include author(s) and platform where appropriate.
• Put lists in alphabetical order, correct spacing.
• Add needed indications (PDF, access notes, under construction)

Follow-up

• Check the status of GitHub Actions and resolve any reported warnings!

[davorpa]

NOTES

Apply this PR first than #6625 to resolve conflicts there.

ABOUT HELP WANTED...

To compare results between GitHub Preview (GH) and GitHub Pages + Jekyll (GHP), post here your hosted fork at github.io/[user]/free-programming-books making the GHP settings point to your PR branch

We need mount versioned environments using different config parameters:

• markdown: GFM
• markdown: kramdown
• markdown: kramdown + kramdown.input: GFM (default)
• markdown: kramdown + kramdown.input: commonmark (this is more compatible with remark, the library we use back fpb-linter although it not fully compatible with GH and GHP)
• ...

For more info see docs at:

• https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll
• https://jekyllrb.com/docs/configuration/markdown

[charlottetan]

Nice catch ❤️ . It's fine remove those bunch of trailing spaces.

There are two more. I'll fix it with moving all links refs definitions to bottom

Thanks! Removing the trailing spaces was actually required for the parsing, otherwise it wouldn't render right

[charlottetan]

• markdown: GMF
• markdown: kramdown
• markdown: kramdown + kramdown.input: GMF (default)
• markdown: kramdown + kramdown.input: commonmark (this is more compatible with remark, the library we use back fpb-linter although it not fully compatible with GH and GHP)

Typo here, you probably meant GFM. We don't need to try the first two options -

• markdown: GFM

This is what the main repo has today, which works except for the issues with rendering anchors that have special characters (#6508)

• markdown: kramdown

This is the option in this PR/branch, I've added it back in to make it explicit but it doesn't need to be there. This works for both the RTL text parsing and the anchor rendering, but requires that plain URLs be marked up too, i.e., written as [url](url).

So we only need to test these two:

• markdown: kramdown + kramdown.input: GFM
• markdown: kramdown + kramdown.input: commonmark

Not sure what the goal is here, you'd like to test them so that we can avoid having to change the URLs? What should be tested when changing the different processor configurations?

[charlottetan]

I tested these two other configurations:

markdown: kramdown + kramdown.input: GFM

PR #6679 - this renders the same specifying just markdown: kramdown in PR #6677.
Which also renders the same as not specifying any markdown processor at all and using the default.

markdown: kramdown + kramdown.input: commonmark

PR #6680 - this results in a build error because the commonmark processor is not supported:
github-pages 223 | Error: kramdown has no parser to handle the specified input format: commonmark

[charlottetan]

Here are some other discussions about linking:
barryclark/jekyll-now#459 (comment)
kramdown/parser-gfm#17

[davorpa]

Previewing I realize now that #6662 is broken.

To solve, it needs add markdown="1" attribute to <div> too

free-programming-books/README.md

Lines 6 to 11 in 7fdc28d

	<div align="center">
	[](https://github.com/sindresorhus/awesome)
	[](https://creativecommons.org/licenses/by/4.0/)
	</div>