diff --git a/_drafts/jekyll.md b/_drafts/jekyll.md new file mode 100644 index 0000000000000000000000000000000000000000..671b6e99777248531f8d27cf020e8329e4740661 --- /dev/null +++ b/_drafts/jekyll.md @@ -0,0 +1,185 @@ +--- +title: Yet another Jekyll post +layout: post +--- + +I'd shifted my personal site to Jekyll some time ago, but I hadn't yet fully +embraced it. Now that I'd decided to blog again, I set about using Jekyll to see +if it could provide support for the blogger Hyde in me. (Yes, yes, that was +terrible.) + +I needed to set it up so that the site would work across the three ways it can +be accessed: + +- [Github Pages](http://murukeshm.github.io) +- [Personal domain](http://murukesh.me) +- [CSE homepage](https://www.cse.iitb.ac.in/~murukesh) + +Github Pages, while decidedly convenient for starting out, is not so convenient +when it comes to expanding. Not that Jekyll is all that convenient either. + +1. You cannot easily publish your blog posts under a subdirectory +2. Posts cannot have a counter-based ID. The permalink can only be based on the + date and title. +3. You have to rely on external providers for comment support. Maybe Disqus, or + Facebook, or something else. + +But... + +1. Markdown is fun to write in. It is clear, logical and the source is easy to + read. +2. Jekyll seems to do a good job of templating, without too much boilerplate. +3. Having some things like code highlighting taken care of by Jekyll is quite + convenient. + +Setting up Jekyll is quite easy - the site has good instructions. I'll just +focus on things I had trouble doing. + +<!-- section --> + +# Page permalinks + +Jekyll on my local setup stripped of the extensions from generated pages. + +<!-- section --> + +# Code Highlighting + +Displaying code proved to be a tricky thing. I'm software guy, naturally my post +will include bits of code here and there. I want it to be pretty (syntax +highlighting, line numbers, the works). Jekyll offers two ways for prettifying +code: *Pygments* and *Rouge*. Pygments is written in Python, and Rouge in Ruby. +So, naturally, you might think Rouge is the way to go, since the whole damned +thing will be in Ruby. Nope. + +The thing is, sticking to what Github Pages offers really does constrain you. +And Pages doesn't support Rouge. So, Pygments is the way to go, and is the +default. + +The first time I tried it out, the result was some consternation. You see, back +when I first made this site for the CS699 course, I'd set `display: block` for +`span` tags. And Pygments relies heavily on `span` tags with CSS classes for +Highlighting. So, where I'd hoped to see something like: + + + +I got (without the colours): + + + +Flabbergasted, I decided to try out Rouge, and it seemed to work fine, except I +had barely any highlighting - the output was marked up, but I didn't have +corresponding CSS. The docs suggested picking up a sample `syntax.css` which is +purportedly close to Github's own style. Ah... But I wanted a dark theme, and I +wasn't too fond of Github's theme as it is. After a bit of going around in +circles, I realised Rouge wasn't supported by Github, and so I went back to +Pygments. A quick inspection showed me what the problem was, and just as quickly +I deleted the offending CSS rule. I had no idea why it was around, since I used +barely any `span` blocks - at least, I couldn't see any visible effect on the +site! With that problem solved, two remained: the colour theme conundrum, and +line numbers. + +<aside markdown="1"> +I could have gone the JavaScript way, but I wanted to see how much I could +accomplish server-side. I'd looked at a couple of code highlighting JavaScript +libraries back in the day, and I vaguely recall deciding them to be not worth +the effort. Plus, Pygments and Rouge both supported VimScript (or VimL, as you +may prefer to call it), whereas whatever library Stack Exchange used didn't. +</aside> + +Like with Rouge, the next problem was CSS. Thankfully, the step to get a CSS +file for Pygments was easy: + + pygmentize -S <theme> -f html > foo.css + +After a few trial, I chose the `normal` theme. + +Line numbering was harder. Oh, both could do numbering, but the numbers would be +selected too when you selected the code, and worse, copied. Apparently, Pygments +supported a `table` option to `linenos`, but it looked weird. There was a +delightful solution that involved using `lineanchors` instead of `linenos`, and +then applying a CSS counter to create the numbers. Unfortunately, `lineanchors` +doesn't work when Jekyll runs in `safe` mode, which it does on Github. However, +I applied the same technique to `linenos`, and hid the numbers generated by +Pygments :mask:: + +{% highlight css linenos %} +pre { + counter-reset: line-numbering; +} + +pre span.lineno::after { + content: counter(line-numbering, decimal-leading-zero); + counter-increment: line-numbering; + opacity: 0.4; + -webkit-touch-callout: none; + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; + visibility: visible; + margin-left: -1em; +} + +pre span.lineno { + visibility: collapse; + text-align: right; + display: inline-block; + min-width: 1em; +} +{% endhighlight %} + +<!-- section --> + +# Sectioning + +By default, the entire post content is stuffed into the `content` Liquid +variable. If you want to split your post into sections, tough luck. This +[StackOverflow post](http://stackoverflow.com/q/26395044/2072269) helped me out. +One of the answers talks about the `post.excerpt` feature, where you can use an +`excerpt_separator` to demarcate out the post blurb, in case you want something +different from the default. Turns out, the idea can be easily extended to a +generic separator. For example, add to your `_content.yaml`: + +{% highlight yaml %} +section_separator: "<!-- section -->" +{% endhighlight %} + +And create a new layout (say `_layouts/sectioned_posts.html`) containing (aside +from the boilerplate): + +{% highlight liquid linenos %} +{% raw %} +{% assign sections = content | split: site.section_separator %} +{% for section in sections %} +<section> +{{ section }} +</section> +{% endfor %} +{% endraw %} +{% endhighlight %} + +Your source will look like: + +{% highlight html linenos %} +Call me Muru. + +<!-- section --> + +I am an aspiring BOFH. Often called a psycho. Now in my third year of the Master +of Technology in Computer Science and Engineering course in IIT Bombay, and +working for the department as an RA in System Administration, I get plenty of +opportunity to hone my skills. :) + +<!-- section --> + +I share the hobby of the masses - reading. :P +{% endhighlight %} + +See my [front page](/) for the output. :) + +<!-- section --> + +# Comments + diff --git a/images/jekyll/proper.png b/images/jekyll/proper.png new file mode 100644 index 0000000000000000000000000000000000000000..b032450a9326f3e615de308b80b677a328ddce84 Binary files /dev/null and b/images/jekyll/proper.png differ diff --git a/images/jekyll/span.png b/images/jekyll/span.png new file mode 100644 index 0000000000000000000000000000000000000000..e5575fb5f490157a4f78bf1c403b77ba0c202b87 Binary files /dev/null and b/images/jekyll/span.png differ diff --git a/styles/style.css b/styles/style.css index fe7fe4cb3962d07aa2ea4f98bea9266a558895b8..a043855500f6c470eef7441e33404c24b9045c83 100644 --- a/styles/style.css +++ b/styles/style.css @@ -198,7 +198,6 @@ pre code strong { float: right; height: 15em; max-height: 18vw; - max-width: 10vw; } }