How to use the simple-line-numbers NPM package to add line numbers to your code examples
There are some great code highlighting tools available, and some of them come with line-numbering functionality either baked in, or else available as a plug-in. If you're already using one of these, and you're perfectly happy with its features, then you can probably flag this article as TLDR and get on with the rest of your day.
If, on the other hand, you're looking for a tool that will provide you with just that standalone line-numbering, and without the bulk of additional features that you may not need, then the simple-line-numbers NPM package might be just what you're looking for.
It's lightweight, easy to use, and requires minimal modification to your markup, so if and when you do need to upgrade to a fully featured highlighting tool, the switch should be as simple as possible.
For most of the other articles on this site (at the time of writing), I'm using simple-line-numbers in conjunction with the very minimal highlight.js tool, but for our purposes here today, I'll focus on using simple-line-numbers without anything else involved.
By the end of this article, you should be able to:
- install the simple-line-numbers package using NPM
- configure the simple-line-numbers package, and produce line-numbering in a simple HTML document
- an existing NodeJs / NPM installation
- basic knowledge of front-end web development
Using the built-in test harness
I've included a handy-dandy test harness with the simple-line-numbers package, and we can use this to get up and running very quickly. The test harness is set up to run everything directly in the browser, so there's no need for any http server or complicated bundling config.
First of all, let's create a mini test project that we can use to try things out.
You should see the following files:
bundle.js: contains the code that will actually be run in the browser. This is the file that will be linked directly from our markup (see index.html), and has been created by transpiling the simple-line-numbers package using Browserify. I'll talk more about this below.
client.js: contains the instantiation of simple-line-numbers. We can pass this into Browserify in order to rebuild bundle.js using additional configuration options if necessary.
index.html: is our markup file that also contains a reference to bundle.js
Seeing the package in action
You should see a screen with code similar to the following:
We have two lines of code, along with corresponding line-numbers.
Let's have a look at what's going on in the code.
The magic attribute
Have a look in the markup, and you'll see a line-numbers attribute:
simple-line-numbers searches for pre tags that contain code tags, which in turn have the line-numbers attribute, and then applies the line numbers accordingly. The value of 1 that I've provided here isn't strictly necessary, as simple-line-numbers uses 1 by default, but I've included it for completeness.
A change of style
As mentioned previously, the client.js file deals with the instantiation of the simple-line-numbers package.
If you read the Styling Options section of the documentation, you'll see that we can use those parentheses to pass configuration options to the constructor.
If you refresh your browser then you'll notice that absolutely nothing has happened yet. To produce changes, we must first rebuild the bundle.
Rebuilding the bundle
In the client.js code above, notice that we're using the require method.
Also, if you look at the source code for simple-line-numbers (in simple-line-numbers_test / node_modules / simple-line-numbers / index.js), you'll see that at the bottom of the file there's this line of code:
We can perform this transpilation using Browserify.
Depending on which version of simple-line-numbers you're using (3.0.0 at the time of writing), you should see something like this:
Notice the updated config on lines 58 - 62:
If you refresh your browser now, you should see the following:
A little bit basic, but it illustrates how we can pass a configuration object into the constructor and then rebuild so that the changes will appear in a web browser.
So that's the quick and dirty on how you can get started with simple-line-numbers. The exact implementation will differ between projects, based on build tools and production platforms, but you should now be at a stage where you can play around with the config and experiment with a few of the features.
Be sure to read the documentation if you want to get the most out of the package, as I've done my best to make the config as flexible as possible whilst keeping things reasonably simple, and don't forget to check out the source code on Github.
simple-line-numbers is my first attempt at creating an NPM package, and is still pretty new as I'm typing this. I plan to maintain the package and make further improvements so long as there's still interest in the JS community, so please keep an eye out for more updates :)