Switch to Octopress code highlighter

[imathis]

This PR will replace plugins in the plugins directory with external gems which now offer all the newest code highlighting goodies addressing #1485 and #1472.

[parkr]

Comment?

[imathis]

Fixing soon. Thanks for jumping on this so fast! You're the 💣.

[parkr]

Wooohoo! What I have in parkr/blogsource#9 is working for me.

[parkr]

Just out of curiosity, why are there so many different ways to highlight one's code? Maybe ship with one preferred one and add instructions on how to use the others?

[imathis]

@parkr That's awesome. It's nice to be able to break things up and externalize them finally. Perhaps the endgame for 2.x is that it has nothing in the plugins directory and just uses gems. That would be lovely.

All I have left on this PR is to replace the include_code plugin. I still have to write it. Perhaps tomorrow. Then I can finally remove the pygments.rb stuff.

Why so many ways? I agree. It's mostly about compatibility. I don't want to work on the codeblock plugin any more since I think it's inferior. I wrote it before I wrote the backtick plugin and honestly I have no idea if people are event using it. Thankfully because of the work I've done with octopress-code-highlighter it took me about 20 minutes to write octopress-codeblock. I did it because it will let me externalize the plugin and remove the cruft without disrupting people's blogs when they update.

It's really the only plugin that has a duplicate function. Gist, include_code, and codefence aren't ways of doing the same thing.

[parkr]

Perhaps the endgame for 2.x is that it has nothing in the plugins directory and just uses gems. That would be lovely.

That would be lovely! 😃

Why so many ways? I agree. It's mostly about compatibility.

Fair enough. I was just thinking about the overlap and was concerned but it's a MAJOR bump change to remove the duplication, not a MINOR change so it'll be for 3.0 instead of 2.5 or whatever this release ends up being. 😄

I did it because it will let me externalize the plugin and remove the cruft without disrupting people's blogs when they update.

You never fail to think of the user first. An exceptional quality in a software developer – tantamount to a virtue in engineering – and something most overlook. You rock! 🤘

[imathis]

With this update, Octopress's code stuffs will finally match the docs. 🍧

I shipped three new gems to make it happen. Feels good.

[parkr]

I shipped three new gems to make it happen. Feels good.

Fleet Admiral up in here! 🚢 🚢 🚢 🚢 🚢

[parkr]

Any reason you're being so specific here? Why specify the PATCH levels?

[imathis]

Good call, I should broaden these.

[parkr]

Hrm, I set $solarized: dark in my sass/_base.scss but get this tiny, tiny difference:

Looks like it's just that initial $ (belongs to the .gp class). Is that no longer part of the Sass highlighting? It's fine, I just noticed the difference and wanted to ask 😄

And yes, I use Opera. It's the best.

[imathis]

Good catch on the code style comparison. I've activated more solarized colors now and addressed the loosening the Gem version specificity.

[parkr]

I've activated more solarized colors now and addressed the loosening the Gem version specificity.

💥 ! I think this guy is ready to 🚢, then. What do you think?

[imathis]

Ok I think this is all working. I probably need to do a blog post before merging since people will need to either update their classic theme, or theme makers will need to update their stylesheets to work with the new html output from the code-highlighter.

[imathis]

I think all I have left to do is add a style for plain <code> elements to the code sass.

[parkr]

I think all I have left to do is add a style for plain <code> elements to the code sass.

👏 🐰

[ramsey]

Correct. I don't have to specify that for GitHub flavored markdown, and it's the desirable default—for me, at least. :-)

[imathis]

@ramsey I've done a bit of testing. If I set the default to be on, it doesn't error or anything. However, with startinline:true, if you are trying to do a typical PHP embedded in HTML example, it highlights the HTML as well. I'm not sure if that is a big deal or not.

The top example is with startinline:true the bottom is the standard PHP lexer.

What do you think?

[imathis]

@parkr Do you have any knowledge of how GitHub handles this on pages builds? If I'm using GitHub pages, is this option set to true in pygments?

[ramsey]

That doesn't bother me. Of course, I can't speak for everyone, but there is also the html+php lexer, if folks want to use that for proper HTML & PHP highlighting: http://pygments.org/docs/lexers/#pygments.lexers.templates.HtmlPhpLexer

[imathis]

I'll definitely enable the option, I'm not sure if I should default it to true yet though. Also here's one thing that bugs me. No matter what it seems that the PHP lexer fails to highlight the first thing, be it an HTML tag or a variable name.

Oddly enough though, it seems to highlight just fine here on GitHub. I wish I knew what they were doing differently.

[parkr]

@imathis I don't have any insights into how GitHub comments are rendered, but I don't think they use Pygments. They use the github-markdown gem, perhaps?

[imathis]

@parkr, it looks like GitHub uses Linguist which highlights with Pygments.rb. So somehow it's different but I can't see how.

[imathis]

Alright, so with the merge to the code-highlighter project, this is all good to go. The changelog is a pretty conservative view of what has happened since 2.0, but I don't want to have to figure out intermediary steps between now and 2.0. This project has been a failure in terms of semantic version, so I think it's probably easiest to set this as 2.1 and promise to do better in the future.

I'm thinking I'll do a blog post before merging this into master and try to get third-party theme creators to make the necessary updates to their themes to support the new code styles. Also I'll tease some of the stuff planned for the 3.0 release.

[parkr]

it looks like GitHub uses Linguist which highlights with Pygments.rb. So somehow it's different but I can't see how.

Linguist is used for files (blobs) but not for comments. They used to use Github-Flavoured Markdown but switched to HTML Pipeline stuff, I think.

[everything else]

👍 Woot! If you want any help writing/editing that blog post, I'm happy to help!

[garfieldnate]

👍 excited to pull this.

[parkr]

@imathis Looks like there's a small bug:

  Liquid Exception: uninitialized constant Jekyll::PullquoteTag::RubyPants in _posts/2013-04-30-an-afterlife.markdown
/Users/parker/code/blog/plugins/pullquote.rb:36:in `render': uninitialized constant Jekyll::PullquoteTag::RubyPants (NameError)

[parkr]

@imathis Also, there's a weird change with inline backticks:

They used to be wrapped in a nice little pocket:

[imathis]

@parkr I think this line should be doing that: https://github.com/parkr/blogsource/blob/e9d20fbb546fef1af5257c8b778370bf1e8b0410/sass/base/solarized/_code-highlight.scss#L5 I'm not sure why it wouldn't.

[parkr]

@imathis Interesting. I did this, and received a slightly different result:

vs

I personally prefer the second option. What do you think?

[imathis]

The first option is nearly a ripoff of what GitHub does for their inline code blocks. I can brighten the background though, I think it'd look better.

[parkr]

I guess it's just what I'm used to seeing on my blog.

I can brighten the background though, I think it'd look better.

I think that would make them pop better! I like it when they're a bit more intrusive – they're supposed to indicate a flip in the perception of the reader: not just prose, but contextual information about the program or procedure I'm describing.

[mbrgm]

Is there any progress on this PR? I'd love to see that feature in master.

[jmhwang7]

Wondering the same as mbrgm. Is there any progress on this?

[ramsey]

I've been using Octopress 3 with these migration instructions to use the new octopress-codeblock, among other things. It's working out quite nicely.

[jmhwang7]

Awesome! Thanks! I'll try that. :)