chore(docs): enabled syntax highlighting

[0xflotus]

... for better readability

[danielgustafsson]

I don't have a problem with going down this route, but I think we should change codesnippets in all the files under docs/ if we decide to. Assuming there are no -1's to this: @0xflotus would you be interested in expanding this PR, or would you like help on that part?

[0xflotus]

I don't have a problem with going down this route, but I think we should change codesnippets in all the files under docs/ if we decide to. Assuming there are no -1's to this: @0xflotus would you be interested in expanding this PR, or would you like help on that part?

For sure, I will go through the docs and will enable code highlight where possible, right?

[danielgustafsson]

On 7 Dec 2020, at 20:27, 0xflotus ***@***.***> wrote: For sure, I will go through the docs and will enable code highlight where possible, right?

Correct. Let's wait a little while to see if other reviewers have differing opinions before spending all that time, but if not let's go. Feel free to tag me in a comment when there is an updated PR so I don't miss the notification to review it.

[bagder]

I'm all for it. Just two things to keep in mind:

1. Many people will read the file as text and not rendered so it is important that we don't sacrifice that readability
2. Some of the docs/ files are also rendered on the website, and they're unfortunately not using the exact same renderer version!

[0xflotus]

I'm all for it. Just two things to keep in mind:

1. Many people will read the file as text and not rendered so it is important that we don't sacrifice that readability

2. Some of the `docs/` files are also rendered on the website, and they're unfortunately not using the exact same renderer version!

If we only think about markdown files, code highlighting on GitHub will propably increase the readability.
If on the website a renderer doesn't support code highlighting, the rendering will not affect the result, right?

[bagder]

It shouldn't be any problems, no. I'm just being cautious so that we don't run ahead and make a lot of changes that don't work well on the site. I presume code highlighting won't be a problem. On the website we use the github-markup tool (on Debian Linux from the package ruby-github-markup version 1.7.0+dfsg-2) and it does for example not support tables the way the GitHub site does...

[0xflotus]

I think I went through all Markdown files in the docs/ directory and enabled the syntax highlighting feature where it was possible. 😬 Are there more relevant sources? Any other thoughts?

[bagder]

The CODE_STYLE.md changes render like this on the website with this change applied. Example partial screenshot:

[0xflotus]

So the renderer takes the c from the

```c
// c code

not as code highlight hint? So we can't use this PR, without tuning the renderer? :/

[bagder]

I think it would be unfortunate to use a markdown format we cannot convert to HTML ourselves. I can't say I know for sure that the website's representation for these documents is more important than GitHub's right now, but as a project policy I think its a bad precedent to assume GitHub for something like this. I think we as a project should live and work as if GitHub dies tomorrow, we still host our main documents on the site and we could switch to and use another source code service in jiffy.

Thus, "proprietary" GitHub markdown format should be avoided until we can use them outside of GitHub.

The questions then become:

1. why doesn't GitHub itself remedy this situation?
2. what alternative tools can we dig up that does the job (better) for us on the site?

[bagder]

Jan pointed out there's an API for this: https://docs.github.com/en/free-pro-team@latest/rest/reference/markdown

... which seems to want the document in JSON as input!?

[Frederik-Baetens]

pandoc -s -f gfm CODE_STYLE.md -o test.html should also work. You can even select the highlighting style: https://pandoc.org/MANUAL.html#option--highlight-style

[bagder]

Thanks @Frederik-Baetens. With pandoc and this PR, the same piece I showed above looks fine. I'm pretty sure it can also be further polished by tweaking the CSS:

[bagder]

As of curl/curl-www@d79508c just pushed, the website is now rendering markdown with pandoc.

[danielgustafsson]

LGTM. Once it lands and renders onto the website we'll see if we need to tweak anything.

[bagder]

Thanks!