Code

Lots of Leanpub authors write about computer programming. Here are some instructions and tips for using code in your Leanpub book.

Code Samples

If you are writing a programming or technical book you may want to add code blocks.

There are three ways to insert code blocks into a Leanpub book.

First, you can just type in the code directly. To indicate that you are writing a code block, indent each new line of code with 4 spaces.

1 This is the first line of code.
2 This is the second line of code.
3 And this is the third line of code!

1     This is the first line of code.
2     This is the second line of code.
3     And this is the third line of code!

Second, you can also make code blocks by adding a set of 8 tildes above and below the code block.

(Actually, we support any number of tildes for code blocks as long as the number of tildes before and after the code-block is the same, but we recommend using 8 as best practice).

Third, when you’re writing you can refer to external code samples in a ‘code’ folder in the ‘manuscript’ folder for your book.

1 Here is a code sample:
2 
3 <<(code/sample1.rb)

You can also put titles on your code samples:

1 <<[This Code Sample Has A Title](code/sample2.rb)

Actually there’s one more way to format lines of code. For short chunks, less than a line in length, you can put the code between back-ticks `.

Here is some code between back-ticks

1 `Here is some code between back-ticks`

Overriding The Default Syntax System

Leanpub attempts to guess the language for syntax highlighting. However, sometimes you will want to specify the language yourself, for example if Leanpub guesses wrong.

When things don’t work, you can force the language by doing this:

1 {lang="js"}
2     Error: Something terrible has happened!

We use Pygments for our syntax highlighting. You can see the list of languages supported here: http://pygments.org/languages. It includes Java, bash, JSON and HTML.

If you have a code block for which you want no syntax highlighting, you can use lang="text".

1 {lang="text"}
2     Error: Something terrible has happened!

Vim Syntax Fix for Code Markup

Here’s how to make sure your code snippets will work with the official Markdown syntax provided by the Vim text editor.

Just create a markdown.vim file in your .vim/after/syntax dir and add the following lines:

1 syn match markdownLeanCode '^<<(.*)$'
2 
3 hi def link markdownLeanCode   markdownH1

Line Numbers in Code Samples

On the Book Theme tab for your book there is a setting called “Show line numbers on code samples” that sets whether or not we show line numbers on your code samples.

You can also turn line-numbers on or off for an individual code-sample by setting the linenos attribute to either on or off. This will force line-numbers to be on:

1 {linenos=on}
2     def hello
3       puts "Hello, world"
4     end

While this will force line-numbering to be off:

1 {linenos=off}
2     def hello
3       puts "Hello, world"
4     end

Setting First Line Number

Sometimes you may want to begin a code sample with number that shows it is a continuation of a previous code sample. You use the starting-line-number attribute to do this. Like so:

1 {line-numbers=on,starting-line-number=32}

…. though of course you can choose whatever number you like.

Here’s an example of how this looks, followed by the text as it is written in Markdown:

32 module Leanpub
33   module Generate
34 
35     class Leanpub::Generate::BinaryLatexGenerator
36 
37       attr_reader :start_chapter, :end_chapter
38       attr_accessor :results
39 
40       ...
41 
42     end
43   end
44 end

 1 {line-numbers=on,starting-line-number=32}
 2 ~~~~~~~~
 3 module Leanpub
 4   module Generate
 5 
 6     class Leanpub::Generate::BinaryLatexGenerator
 7 
 8       attr_reader :start_chapter, :end_chapter
 9       attr_accessor :results
10 
11       ...
12 
13     end
14   end
15 end
16 ~~~~~~~~

Displaying only part of a code file

You can use the crop-start-line and crop-end-line attributes to set the start and end line of a code sample to display. This is useful if you have a large file and you only want to display parts of it. For example, if you have a large file called books_controller.rb and only wanted to show lines 15–30 of it, you would do this:

1 {crop-start-line=15,crop-end-line=30}
2 <<[BooksController](code/books_controller.rb)

Code Samples In Asides

This will work if you put the A> before every line in the code sample. Note that you’ll have a few less characters to work with due to the indentation in the aside.

Like this:

 1 A> ^[r1184]^ This behaviour makes it hard to execute VCL code from the
 2 `OnStop` so revision 1184 introduced another variation of `OnStop` that
 3 accepts a delegate with an `IOmniTask` parameter.
 4 A>
 5 A> {lang="pascal"}
 6 A> ~~~~~~~~~~~~~~~
 7 A>   TOmniTaskStopDelegate = reference to procedure (const task: IOmniTask);
 8 A>
 9 A>   IOmniParallelLoop = interface
10 A>     ...
11 A>     function  OnStop(stopCode: TOmniTaskStopDelegate):
12 IOmniParallelLoop; overload;
13 A>   end;
14 A> ~~~~~~~~~~~~~~~
15 A>
16 A>^[r1184]^ Using this version of `OnStop`, the termination handler can use
17 `task.Invoke` to execute some code in the main thread. This, however,
18 requires the `ForEach` abstraction to stay alive until the `Invoke`-d code
19 is executed so you must store the `ForEach` result

Code Sample Titles

A code block without a title looks like this:

1 class Book
2 
3   def initialize(title, subtitle)
4     @title = title
5     @subtitle = subtitle
6   end
7 
8 end

You can give a codeblock a title using the title attribute. Adding a title styles it a bit differently. Here is an example of what it looks like, followed by the actual text written in Markdown that produces the title and code block:

Example 12: Creating a class in Ruby
1 class Book
2 
3   def initialize(title, subtitle)
4     @title = title
5     @subtitle = subtitle
6   end
7 
8 end

 1 {title="Example 12: Creating a class in Ruby", lang=ruby}
 2 ~~~~~~~
 3 class Book
 4 
 5   def initialize(title, subtitle)
 6     @title = title
 7     @subtitle = subtitle
 8   end
 9 
10 end
11 ~~~~~~~

You can specify multiple attributes (like the title and the language for syntax highlighting) like this:

{title="Some Title", lang=coffeescript}

Here’s an example:

Example 13: Creating a class in CoffeeScript
1 class Book
2   constructor: (@title, @subtitle) ->
3     # Other initialization code goes here

Here’s the text in Markdown that produced the code sample above:

1 {title="Example 13: Creating a class in CoffeeScript", lang=coffeescript}
2 ~~~~~~~
3 class Book
4   constructor: (@title, @subtitle) ->
5     # Other initialization code goes here
6 ~~~~~~~

Marking lines as deleted or added to a code block

If you are building up an example while writing your book, you will probably want to emphasise lines of code that have been added to your book and strike-out lines of code that have been removed. This is done by adding comment lines to your code. The special words that can be used are leanpub-start-delete, leanpub-end-delete, leanpub-start-insert and leanpub-end-insert. Note that any line containing these strings will be removed completely from your code before being inserted in the book. This should allow you to use any comment syntax you require.

Also, please note that if you use leanpub-start-delete or leanpub-end-delete in a code sample that you are showing in a book, then it will turn off any syntax highlighting; otherwise the bolded text gets hidden by syntax highlighting.

For example, the following code has leanpub-start-delete before def old_stuff and leanpub-end-delete after it, and leanpub-start-insert before def new_stuff and leanpub-end-insert after it. (It’s hard to put this inline as we strip it out, so I’ll just have to describe it).

 1 def nochange
 2   "No change here"
 3 end
 4 
 5 def old_stuff
 6   "Old"
 7 end
 8 
 9 def new_stuff
10   "New"
11 end
12 
13 def unmoving
14   "No change here either"
15 end

Up next

Poetry