Line numbering code in posts
June 28, 2007 at 4:37 PM by Dr. Drang
Many of my blog posts contain source code and a description of what the source code does. When the block of code is long, I sometimes have trouble pointing out which lines I’m referring to in the description (e.g., “the section that starts with if length of tnum is 10 then”). So, starting with this post, I’ve decided to number the lines in longer sections of code.
If you search the internet for ways to get line numbers in HTML, you’ll find several solutions. This one wants you to put your code in an ordered list instead of a <pre> block. This one, called List Injection for Pre Tags (LIPT), adopts the same philosophy, but uses JavaScript to transform your <pre> block into an <ol> block. LIPT seems especially good if you don’t want line numbers in your source documents, but do want line numbers for everything wrapped in <pre><code>…</code></pre> sections. Initially, I thought LIPT was perfect for my needs, but after some thought I decided against it.
First, I don’t want every <pre><code> block to have line numbers, just the blocks with many lines. And I want to decide how many is “many” on a case-by-case basis. I figured this would be relatively easy to get around by altering the LIPT code to only handle certain classes of <pre><code> blocks—say <pre><code class="ln">. I write my posts in Markdown, and although standard Markdown won’t add the class attribute to code blocks, it does allow you to add HTML tags directly. So this was not the deal-breaker.
More important was the philosophy of Markdown, a philosophy I have taken to heart: the source document should be easily readable as is. If I was going to refer to portions of the code by line number, then the line numbers had better be in the source document. There’s also a more practical, less principled issue: how would I know what the line numbers were if the lines weren’t numbered in the source document?
Numbering the lines in a block of plain text isn’t a big deal. With TextMate, I can select the lines I want numbered, filter them through the Unix line numbering utility nl, and then indent them according to the Markdown rules. The generated HTML will then have the line numbers in a <pre><code> block. Unfortunately, those line numbers will have the same font color and size as the code, and I’d rather have them be less obtrusive—not so dark and somewhat smaller.
It turns out that wrapping the line numbers in <span> tags and applying a CSS style to those elements will do the trick. Of course, I don’t want the Markdown source document to include the <span>s.
So, my goal was now set. I needed:
- A shell script that I could use to number lines of code according to my picky aesthetic sensibilities.
nlhas many options—leading zeros? number the blank lines? what to put between the line number and the code?—and once I’ve settled on the set that I like, I want to be able to invoke it with a single, no options, command. - A JavaScript function that goes through my HTML document and puts
<span>tags around all the line numbers. - A bit of CSS to style the line numbers to my liking.
I see that I started this post too late in the afternoon to finish it before being interrupted by other responsibilities. I’ll do a followup post late tonight that describes these three parts in detail.
Update The followup came a day later than I anticipated.
