Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): enabled syntax highlighting #6286

Closed
wants to merge 8 commits into from
Closed

Conversation

@0xflotus
Copy link
Contributor

@0xflotus 0xflotus commented Dec 7, 2020

... for better readability

... for better readability
Copy link
Member

@danielgustafsson danielgustafsson left a comment

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
Copy link
Contributor Author

@0xflotus 0xflotus commented Dec 7, 2020

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
Copy link
Member

@danielgustafsson danielgustafsson commented Dec 7, 2020

@bagder
Copy link
Member

@bagder bagder commented Dec 7, 2020

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
Copy link
Contributor Author

@0xflotus 0xflotus commented Dec 7, 2020

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
Copy link
Member

@bagder bagder commented Dec 7, 2020

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
Copy link
Contributor Author

@0xflotus 0xflotus commented Dec 7, 2020

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
Copy link
Member

@bagder bagder commented Dec 9, 2020

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

Screenshot_2020-12-10 Code style

@0xflotus
Copy link
Contributor Author

@0xflotus 0xflotus commented Dec 9, 2020

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
Copy link
Member

@bagder bagder commented Dec 10, 2020

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
Copy link
Member

@bagder bagder commented Dec 10, 2020

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
Copy link

@Frederik-Baetens Frederik-Baetens commented Dec 10, 2020

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
Copy link
Member

@bagder bagder commented Dec 10, 2020

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:
Screenshot_2020-12-10 Code style(1)

@bagder
Copy link
Member

@bagder bagder commented Dec 10, 2020

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

docs/INSTALL.md Outdated Show resolved Hide resolved
@bagder bagder requested a review from danielgustafsson Dec 10, 2020
Copy link
Member

@danielgustafsson danielgustafsson left a comment

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

@bagder
Copy link
Member

@bagder bagder commented Dec 11, 2020

Thanks!

@bagder bagder closed this in 5253444 Dec 11, 2020
@0xflotus 0xflotus deleted the 0xflotus:patch-1 branch Dec 11, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants