How should we highlight code blocks? #2

Closed
wcaleb opened this Issue Jun 28, 2014 · 4 comments

Projects

None yet

2 participants

@wcaleb
Contributor
wcaleb commented Jun 28, 2014

@fredgibbs I'm preparing to use Pandoc to do a massive bulk conversion of all existing lessons into Markdown. Before doing so, I've been doing some thinking about how code blocks should be handled in the new site.

In the lessons you've already converted, you used Jekyll's preferred highlighting feature. But the problem with this method is that when you view the markdown files in Github, the Github browser itself doesn't recognize those highlighting codes, and instead interprets things that should be commented lines in a code block as level-1 headers.

I'm wondering if it might be better (and would make us less dependent on Jekyll in the long run) to instead use raw HTML tags like pre for code blocks, and then use CSS styling to handle the language-specific highlighting. That way they would look readable either on the site or on Github.

Thoughts on this issue? Here are a couple of (oldish) sites that outline some of the different possibilities:

@fredgibbs
Contributor

i'm all for less dependency with jekyll, and i'm not super thrilled about the pigments syntax highlighting--it's fine but nothing special. i agree it would be preferable to have things render properly in github, so perhaps the easiest solution is regular markdown formatting with syntax.js to take care of the language highlighting. my sense is that combo will provide both github viewing and nicely colored HTML. (so, option #2 in link #1)

@wcaleb
Contributor
wcaleb commented Jul 7, 2014

I think we might have to use raw HTML code blocks to get them to display properly in both Jekyll and on Github. Will Jekyll convert fenced code blocks written in regular markdown formatting?

@wcaleb
Contributor
wcaleb commented Jul 11, 2014

Actually, this may be easier than I thought, if we just change our markdown parser from kramdown to redcarpet. See stackoverflow.

@wcaleb
Contributor
wcaleb commented Jul 11, 2014

OK, after some experiments on the gh-pages branch, I think the best approach is to change our markdown parser to redcarpet, and then use Pandoc to produce fenced code blocks with back ticks followed by the highlighting language.

@wcaleb wcaleb closed this in f33f781 Jul 12, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment