Miscellaneous

Escaping Markdown Syntax Characters

Sometimes you’ll want to use a character or set of characters that is a part of the Markdown syntax. To make the character show up in your text, instead of acting as a Markdown formatting marker, just put the backslash \ character in front of it.

For example, if you just type “# Header” at the beginning of a line, it will appear as a header, and you won’t see the number sign “#”.

If you want “# Header” to show up at the beginning of a line, type “\# Header”, and you’ll see the number sign:

# Header

\# Header

How To Exclude Lines From Your Book

If you have some lines in your .txt files that you’re working on, but don’t want to appear in your book, you can hide or ‘comment out’ the lines by adding two ‘%’ characters:

1 %% You won't see this text!

Please note the ‘comment out’ line must be preceded by a blank line.

Any line that meets these requirements will not show up in the published PDF, EPUB or MOBI files.

To ‘comment out’ like this in Book.txt, type a # at the beginning of a line.

Mathematical Equations

You can put mathematical equations in your book.

You use LaTeX math syntax, surrounded by {$$} and {/$$}. You can do both inline and block math. Here is a full example:

Equations

You create a block equation by putting it by itself:

1 {$$}
2 \left|\sum_{i=1}^n a_ib_i\right|
3 \le
4 \left(\sum_{i=1}^n a_i^2\right)^{1/2}
5 \left(\sum_{i=1}^n b_i^2\right)^{1/2}
6 {/$$}

Inline equations are written inline. For example:

The four kinematics equations are \(d = v_i t + \frac{1}{2} a t^2\), \(v_f^2 = v_i^2 + 2 a d\), \(v_f = v_i + a t\) and \(d = \frac{1}{2}(v_i + v_f) t\).

1 The four kinematics equations are {$$}d = v_i t + \frac{1}{2} a t^2{/$$},
2 {$$}v_f^2 = v_i^2 + 2 a d{/$$}, {$$}v_f = v_i + a t{/$$} and {$$}d =
3 \frac{1}{2}(v_i + v_f) t{/$$}.

Please note that if you are going to include a percent sign % in an equation, you need to “escape” it with a backslash, like this:

1 {$$} value  = (1 x 4) \% 5  = 4 \% 5 = 4{/$$}

Curly Quotes

Ideally you should just have “straight” ‘quotes’ in the Markdown. We auto-produce curly quotes for you. We change curly quotes into straight quotes and then make them curly again.

Figure Captions and Labels

In technical books, is common to have figures with a label and a corresponding reference in the text.

Here’s how you can do something like this in Leanpub:

1 # Chapter 1
2 See [figure 32](#figure-32) for an example.
3 # Chapter 2
4 {#figure-32}
5 ![Figure 32](images/figure32.jpg)

What we don’t do (yet) is provide auto-numbering of figures and captions.

Links In Footnotes

Currently, a link mentioned within a footnote doesn’t generate a new footnote (in the PDF), and doesn’t have a clickable URL either. We’ll implement a solution to this soon.

Why can’t I put section commands in Book.txt?

After a lot of thought and experimenting, we’ve decided to make Book.txt just a list of files. That means you can’t put section commands in the Book.txt file, like

1 {frontmatter}
2 Introduction.txt
3 {mainmatter}
4 Chapter1.txt
5 {backmatter}
6 Appendix1.txt

Instead, we recommend you make a separate .txt file for each section command, and then refer to it in Book.txt. So e.g. you’d make a frontmatter.txt file that only has this content:

1 {frontmatter}

… and do the same for mainmatter and backmatter. Then, your Book.txt file will look like this:

1 frontmatter.txt
2 Introduction.txt
3 mainmatter.txt
4 Chapter1.txt
5 backmatter.txt
6 Appendix1.txt

… and you can still see your book’s structure in Book.txt.

This is an easier thing to explain and understand than if we’d turned Book.txt into a DSL. We had started down that approach many years ago, and it was confusing.

Now, since Book.txt is just a list of files, you could in theory write an entire book in one file. We don’t recommend this, since if you did that, you couldn’t give away a subset as Sample.txt, since it’s also just a list of files. Also, splitting your book up into different .txt files actually makes it easier to find and edit content, and to reorganize or delete sections. So we still recommend one file per chapter, both for clarity and for ease of creating book samples.

Trouble With Accents? Forcing Text Editors To Save As UTF-8

Normally, to get things like letter accents to work if you’re having troubles, you can force the encoding by putting this at the top of your text file:

{:: encoding="UTF-8" /}

However, you may still have problems if the text editor you’re using is not set to save to UTF-8. Normally you can change this setting by doing ‘Save As’, and finding the ‘Encoding’ option.

I don’t understand how things get added to a Table of Contents

By default, all headers are added to the Table of Contents. A header looks like this:

# Chapter One

… where you put the number sign # at the beginning of the line, and follow the number sign with the text you want for the header.

Also by default, all ‘Part’ titles are added to the Table of Content. You create a Part by typing -# like this:

­# Part One

You can choose to have the Table of Contents include sections as well. To do this, go to your book’s Settings page and select the “Book Theme” tab under “Writing” in your book tools menu, and then scroll down to the Table of Contents section. There, you can select ‘Parts, Chapters and Sections’ or ‘Everything’.

Then, sections will also appear in the Table of Contents. A section is subordinate to a heading, so you type two or more number signs, like this:

## This is a section subordinate to a heading. ### This is a section subordinate to ## sections #### This is a section subordinate to ### sections

What encoding should I use to write files in Markdown? Should I write in ASCII or UTF-8?

We translate everything to UTF-8 internally, so if you start with UTF-8 everything will work smoothly.

How Can I Add Blank Lines To My Text?

While there is no official way to add a larger space between paragraphs, adding a blank table (two vertical pipes separated by a space, like this | |) works. For example:

This is a line.

This is a second line. It has a larger space after it.

This is a third line.

This is a fourth line.

1 This is a line.
2 
3 This is a second line. It has a larger space after it.
4 
5 |  |
6 
7 This is a third line.
8 
9 This is a fourth line.

Adding a motto or epigraph to the beginning of a chapter

There is no special feature for adding a motto or epigraph to the beginning of a chapter, but one nice way to do this is to use text centering.

So, if you type this:

1 C> *It was the best of times, it was the worst of times*
2 C>
3 C> -- Charles Dickens
4 
5 It was a dark and stormy night...
6 
7 Suddenly, a shot rang out!

You’ll see this:

It was a dark and stormy night…

Suddenly, a shot rang out!

Disabling Line Numbers While Nesting Code Blocks In Lists

For the indentation method:

1. There must be a blank line between the list item and the code.
2. The {line-numbers=off} line should be indented by four characters.
3. The code should be indented by 3 more characters than the {line-numbers=off} line.

* with no line numbers:

  {line-numbers=off}
      def foo
        "foo"
      end

* with line-numbers on:

      def foo
        "foo"
      end

For the tildes method

1. There must be a blank line between the list item and the first line of the code block
2. The tildes and the code should be indented to match the indentation of the list.

* with no line numbers:

  {line-numbers=off}

def foo “foo” end

• with line-numbers on:

  1 def foo
  2   "foo"
  3 end
  

Indentation

If you are looking to indent some text you can use the Unicode character ‘figure space’ (U+2007) to add as many spaces as you need. You can add this character to your clipboard by selecting the blank space between the following quotes and copying it.

“ ”

Hanging Indents

Scholarly works sometimes need bibliographical entries to be formatted with hanging indents. So, we’ve added this to Leanpub.

To use it, you use the directives {begin-hanging-paragraphs} to start using hanging paragraphs, and {end-hanging-paragraphs} to end it. These should be on lines by themselves, with blank lines above and below them. Here’s a quick example, showing first what you would type in your text file, and second how this would look when published:

 1 This is a normal paragraph.
 2 
 3 
 4 {begin-hanging-paragraphs}
 5 
 6 Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec hendrerit tempor tel\
 7 lus. Donec pretium posuere tellus.
 8 
 9 Aliquam erat volutpat. Nunc eleifend leo vitae magna.
10 
11 Pellentesque dapibus suscipit ligula. Donec posuere augue in quam. Etiam vel tortor \
12 sodales tellus ultricies commodo. Suspendisse potenti. Aenean in sem ac leo mollis b\
13 landit. Donec neque quam, dignissim in, mollis nec, sagittis eu, wisi. Phasellus lac\
14 us.
15 
16 Pellentesque dapibus suscipit ligula. Donec posuere augue in quam. Etiam vel tortor \
17 sodales tellus ultricies commodo. Suspendisse potenti. Aenean in sem ac leo mollis b\
18 landit. Donec neque quam, dignissim in, mollis nec, sagittis eu, wisi. Phasellus lac\
19 us.
20 
21 {end-hanging-paragraphs}
22 
23 This is a normal paragraph again.

This is a normal paragraph.

This is a normal paragraph again.

Long strings of characters running off the right-hand side of the page / the right margin

Sometimes very long strings of characters will run off the right-hand side of the page, without a line-break happening automatically. Unfortunately there’s not much we can do to fix this. Usually, we see it with long Java class names. The only fix that we know of is to manually insert a line-break before the problematic code-span by putting two-spaces followed by a carriage return right before it. Sorry we don’t have a better answer!