Introduction

Leanpub Flavoured Markdown vs. Markua

On Leanpub, there are two ways to write in plain text:

1. Leanpub Flavoured Markdown (LFM)
2. Markua 0.10

Leanpub Flavoured Markdown came first; Markua is its replacement. Both LFM and Markua are dialects of Markdown. Markua is newer and better than LFM, but there are still some advanced features in Markua that aren’t finished yet.

The version of Markua that Leanpub uses is Markua 0.10. It is documented here.

To write in LFM or Markua, you need to be in Dropbox, GitHub or Bitbucket writing mode, or you need to be writing in the Leanpub In-Browser Text Editor. The Leanpub Visual Editor, Google Docs and Bring Your Own Book mode do not support LFM or Markua formatting.

There are six good reasons to write a book in Markua:

1. Markua is better than LFM. A lot better. Markua fixes the many mistakes we made with LFM.
2. Markua is the future of Leanpub.
3. Markua has more features than LFM.
4. If you want to create a course on Leanpub, you need to use Markua.
5. The Leanpub In-Browser Text Editor is better with Markua now, and it’s going to be way better soon. (We’re working on an upgrade to the Leanpub In-Browser Text Editor which will only be available for Markua books.)
6. The Markua Manual is newer and better than the Leanpub Flavoured Markdown Manual.

There are two good reasons to write a book in LFM:

1. You already started your book in LFM and you don’t want to convert it yet.
2. You are writing a translation of a book which is written in LFM.

Switching Writing Modes

If you have an existing Leanpub book and you want to switch writing modes, you go here:

Author > Books > (your book) > Settings > Writing Mode

Again, Google Docs, our Visual Editor and Bring Your Own Book do not support Markua or LFM formatting.

Once you’ve chosen an appropriate writing mode, you then can switch between the Markua and LFM dialects of Markdown here:

Author > Books > (your book) > Settings > Markdown Dialect

Scope of this Manual

This manual explains how to write in Leanpub Flavoured Markdown, or LFM for short.

This manual does not explain how to use Leanpub, just how to write in LFM.

To learn more about how to use Leanpub, you can see The Leanpub Manual.

If you can’t find the answers there, there are 3 ways to get help…

1. Search our Help Center at https://help.leanpub.com/
2. Join the Leanpub Forum at https://community.leanpub.com/c/authors and post your question there. Our authors enjoys helping each other out! Please ask all general questions here.
3. If you have a specific problem that you don’t want to post on the forum, email us at [email protected] and we’ll be happy to help you.

To learn more about Leanpub Flavoured Markdown, read on…

Book.txt, Sample.txt and Manuscript Files

Your book will consist of a bunch of text files. Typically they have the file extension .txt. You can write them using any program you like; just save the files as plain text.

To illustrate, we’re going to write an epic fantasy novel together. Let’s give it a suitably epic title: The Cliché Chronicles.

This is the content of the file called chapter1.txt:

 1 # Chapter 1: A Stormy Beginning
 2 
 3 Lord Char, black cloak flapping around him in the rising storm, rubbed his hands tog\
 4 ether in anticipation as he strode to the middle of the circle of stones. He had bee\
 5 n years in preparation for this, his moment of triumph.
 6 
 7 It was time to use the knowledge he had gained through years of patient planning. No\
 8 w The Unnamed One would pay!
 9 
10 ***
11 
12 And this is the content of the file called chapter2.txt:
13 
14 ***
15 
16 # Chapter 2: You Are Not My Father!
17 
18 ## A Horrible realization
19 
20 Suddenly, he realized who his father had to have been.
21 No wonder the dark riders had chased him half way across the continent!
22 
23 ## The Horror Grows
24 
25 With growing horror, he pulled the dark pulsing amulet from his cloak.
26 If The Unnamed One was truly his father, he shuddered, then the amulet must be The J\
27 ewel of Rak Crasha!

See those number # signs? They’re an example of what it’s like to write in the formatting style called Markdown. If you want to write a chapter heading, just put a # at the start of the line, instead of hunting for ‘styles’ like you would in Microsoft Word. And if you want a sub-heading, just type two number signs ‘##’. We chose Markdown as our formatting system (even typewriters have a formatting system!) because it was created to make sense and let you focus on writing words instead of overly complex formatting stuff.

Anyways, back to the book we’re writing!

When Leanpub converts this text into a book for you, the # headings will start new chapters and the ## headings will start new sections. So, there are two chapters here - “Chapter 1: A Stormy Beginning” and “Chapter 2: You Are Not My Father!”. Chapter 2 contains two sections: “A Horrible Realization” and “The Horror Grows”.

The Book.txt File

As mentioned above, the content of your book is all tied together by the Book.txt file. This is a list of all the files you want in your book, in the correct order.

The text you’d type in the Book.txt file for The Cliché Chronicles would look like this:

1 chapter1.txt
2 chapter2.txt

Yup, that’s it. It’s just a list of the names of the files in your manuscript folder that you want to appear in your book, in the order you want them to appear. Think of it as your Table of Contents.

Making a Sample Book for Readers to Browse for Free

(Please note that if you are using our in-browser editor with LFM, it’s currently not possible to make a sample book, sorry. It is possible with Markua books.)

If you want prospective customers to read a sample of your book for free, you can make a file called Sample.txt in your manuscript folder. This file works exactly like Book.txt. Just list all of the files that you want to be included in your book sample.

(Please note that a new Sample Book file will be created for you to review every time you make a new preview of your book. However, the Sample Book available to customers will only be updated when you publish a new version of your book.)

OK, let’s let potential readers of The Cliché Chronicles browse the first chapter for free. Once they read that, they’ll be hooked and will rush to buy the book so they can read the rest.

To do this, just type this in the Sample.txt file:

1 chapter1.txt

Next time you Preview or Publish your book, Leanpub will create a separate sample ebook containing just chapter one, because that’s the only chapter listed in Sample.txt.

Adding Images or Pictures to Your Book

It’s easy to add images or pictures to your book. To do this, you need to:

1. Put the images or pictures in your images folder (it’s in your manuscript folder).
2. Tell Leanpub where you want the image to appear in your book. You do this by typing the image name directly into your text, with a little help from Markdown formatting.

So, to add images to your book, first put them in the images folder inside your book’s manuscript folder.

Then, you need to tell Leanpub where to put the images in your book.

Let’s say we want to put an image in our book that we’ve saved as ‘Sword.png’. Just put the ‘Sword.png’ file in your images folder, and then type this in your .txt file, in a line on its own, wherever you’d like the image to appear:

1 ![An awesome sword](images/Sword.png)

Now, the next time you create a Preview, the image will appear with the caption ‘An awesome sword’. If you don’t want a caption, just leave that part of the instruction empty, like this:

1 ![](images/Sword.png)

A Note About Character Encoding

Depending on the text editor you are using and its settings, sometimes you may see weird characters appear in your text, and some characters may fail to appear at all. If you are experiencing this issue, you can try forcing the character encoding to be UTF-8.

To edit character encoding, go to Author > Books > your book > Settings > Generation Settings.

How Markdown is Used in Leanpub

Even if you know Markdown, you need to learn a few things about how we use it at Leanpub.

Importing Markdown Files

To import Markdown files to Leanpub, you can just save them as .txt files, put them in your book’s manuscript folder, and refer to them in Book.txt (the list of files to be included in your book, in the order you’d like them to appear), and generate a new Preview of your book.

Heading Levels Become Chapters and Sections

First, we use # chapters, ## for sections and ### for sub-sections. (You can also use #### for sub-sub-sections, but don’t get carried away! Most technical books are good with just #, ## and ###, and most business and fiction books are good with just # and possibly ##.)

So, if you look at the top of the Markdown.txt file you’ll see that it has one #, meaning it is a Chapter.

Another thing this means is that one file can contain as many chapters or sections as you want: every # makes a new chapter; it has nothing to do with what file it is in. However, we strongly recommend having one file per chapter (or one file per chapter section), since it makes creating sample books easier and keeps your book directory cleaner. Since we recommend this, that’s what we’ll do in this example book.

Links Become Footnotes

We support Markdown syntax for links, as well as normal HTML links. Both of these are converted into functioning footnotes in the PDF. Here’s an example of a link to Leanpub.

And here’s what it looks like in Markdown (i.e., this is what you type in the text file to get that link):

1 [Leanpub](https://leanpub.com)

Markdown Extensions in Leanpub

We’ve made a few additions to Markdown for use in Leanpub. Two of the most important are tables and crosslinks. Furthermore, since Leanpub is so good for technical books, we also support extensions for external code samples, special directives for code syntnax highlighting, etc.

We use almost all of the Kramdown extensions (see https://kramdown.gettalong.org/syntax.html for a list of them). Two exceptions are:

1) HTML blocks – we don’t support HTML elements in our Markdown.

2) << becoming a left guillemet. We took this out when we created the external code sample syntax.

Formatting Email Links

Email links are formatted by simply surrounding the address with < and >.

Just click on [email protected] to send us an email.

1 Just click on <[email protected]> to send us an email.

Attributes

You can set various ‘attributes’ directly in your book files, like setting the code language, or line numbering. You do this by adding the syntax on their own separate lines in the text.

To be clear, each attribute should be alone on a line, with blank lines above and below it (unless it’s at the beginning of the file, in which case you just need a blank line below it!).

In general, the syntax works like this:

1 {some-attribute=value}
2 
3 {some-attribute="some attribute value"}

Quotes are only necessary if there are spaces.

You can have multiple attributes too. Separate them with commas.

1 {language=ruby,line-numbers=off}

Spaces are not significant, so you could also write:

1 {language=ruby, line-numbers=off}

or

1 id: {#some-id}

So, for example, if you want a file or section to be front matter (like an introduction, which will have roman numerals for page numbers), at the top of the file or section just type:

1 {frontmatter}

Or if you want to turn on line numbering just for that section, type:

1 {line-numbers=on}

Here are the attributes supported:

general: id code blocks: language, line-numbers files: encoding

special names:

1 {pagebreak}
2 {frontmatter}
3 {mainmatter}
4 {backmatter}

Creating A New Book

How To Set The Book’s Structure

To set the structure for your book - that is, what content you want to appear and in what order - you use the Book.txt file in your book’s ‘manuscript’ folder.

‘Book.txt’ is a list of the files that you want included in your book, in the order that you want them to appear.

So if you have .txt files in your ‘manuscript’ folder called ‘chapterone.txt’ and ‘chaptertwo.txt’ and you want them to appear one after the other in your book, open Book.txt and type:

chapterone.txt chaptertwo.txt

This means that you can actually have content in your ‘manuscript’ folder that isn’t included in your ebook. Only the files listed in ‘Book.txt’ will appear in your book. This is useful if you’re working on new chapters that you don’t yet want to include in the latest version of your book, for example. You don’t have to take the file out of ‘manuscript’; you can just take it out of the list of files in ‘Book.txt’.

Sample Books

Why Sample Books?

Leanpub lets you create a sample book, which readers can download for free to help them decide whether they want to buy the real book.

To do this, you create or edit a file called Sample.txt in the ‘manuscript’ folder for your book. Note that, like Book.txt, the Sample.txt file is just a list of files. It’s supposed to be a smaller list than what is in Book.txt, or else you’re giving your whole book away! If you don’t want a sample book, just delete the Sample.txt file.

(Please note that a new Sample Book file will be created for you to review every time you make a new preview of your book. However, the Sample Book available to customers will only be updated when you publish a new version of your book.)

Consequences for Manuscripts

One consequence of this approach to specifying a sample book is that it’s an “all or nothing” decision to include a file. If you include a file in the list in Book.txt, all the chapters and sections in that file are inserted in your book. Because of this, we recommend a couple things:

1. Either use a separate text file for each chapter, or
2. Never let a section span multiple text files.

These two guidelines mean that your sample book is a lot less likely to have problems. If you don’t follow them, things can still work, but you can sometimes create a situation where your book will be created fine but your sample book will not.

So, if you use the “separate text file for each chapter” approach, things will just work.

Images

How To Insert An Image

This section shows how you can insert images into your Leanpub book.

First, you need to put the image in the ‘images’ folder in the ‘manuscript’ folder for your book.

Second, type in a reference to the image like this:

1 ![This is the Image Caption](images/LeanpubLogo1200x610_300ppi.png)

Then you’ll see the image appear:

That’s it! (See this web page for details on images in Markdown.)

Note: Captions will only appear if an image is on a line all by itself.

Image Format And Resolution

We support PNG, JPEG and GIF formats for images.

There are notes about the sizes of images at Author > Books > your book > Settings > Image Sizing Help.

Positioning An Image On The Page

You can ‘float’ your image on the page, aligning it to the right and left as your prefer. (You can also use {float=inside} or {float=outside} rather than {float=left} and {float=right} in your Markdown).

For example, if you type this (using the name of your image and not the Leanpub logo, of course):

1 {width=60%,float=left}
2 ![This is the Image Floated Left](images/LeanpubLogo1200x610_300ppi.png)

Then you willl see the image floated to the left, with text wrapping around it, like this:

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Please note that it is not currently possible to set images side-by-side.

Languages and Letter Accents

Setting the Main Language Used in the Book

In the General Settings page in your book tools, you can set the main language used in the book.

When you create a book, to set the language, click on “Writing” in the menu on the left and then click on “General Settings”. There, you will see a dropdown where you can set the main language used in the book. Once you’ve selected a language, click the blue “Update Book” button at the bottom of the page.

By default, the main language is English.

This helps us to set up the fonts that we use in your book. If you are writing with a mixture of languages that includes Chinese, Japanese or Korean, then you should check out the language switcher section (right below here). If you have troubles with characters not showing up properly, please let us know at [email protected].

Overriding Leanpub Language Defaults

You can tell Leanpub what encoding a file is in via a snippet of text that you put at the top of the file:

1 {:: encoding="utf-8" /}

This will let you over-ride our encoding guessing.

Switching back and forth between language fonts

You can switch back and forth between language fonts by indicating the font in curly brackets.

For example, you can switch to a Chinese font by typing {chinesefont} and back to latin characters again by typing {latinfont}.

Here’s an example:

Here is some Chinese text 办事去了 and here’s some English.

Here is some Chinese text {chinesefont}办事去了{latinfont} and here's some English.

There are also equivalent switches for Japanese {japanesefont}, Korean {koreanfont} and Thai {thaifont}.

A note about writing Leanpub books in Japanese, Korean and Chinese

If you are writing with a mixture of languages that includes Chinese, Japanese or Korean, then you should select Chinese, Japanese or Korean as the main language for your book.

A note about writing Leanpub books in right-to-left (RTL) languages

If you are writing in a right-to-left language such as Arabic or Hebrew, please use Markua. Our right-to-left language support is not perfect, but we will not be fixing any more bugs in Leanpub Flavoured Markdown mode with it. So, if you want to have any chance of being happy with Leanpub’s right-to-left language support, use Markua.

Parts, Chapters and Sections

Parts

To start a new “Part” in your book, you start a line with -# followed by the title of the Part.

1 -# Part 1

Chapters, Sections and Sub-sections

Chapters are started by a single #. Sections with two ##, sub-sections with three ### all the way down to sub-sub-sub-sections #####.

1 # Chapter 1
2 
3 ## Section 1.1
4 
5 ### Sub-section 1.1.1
6 
7 #### Sub-sub-section 1.1.1.1
8 
9 ##### Sub-sub-sub-section 1.1.1.1.1

Please note that only lines of text with one or more number signs will show up in the Table of Contents (you can control what level of hierarchy you want to show up in your Table of Contents in the Settings section for your book).

Table of Contents

Leanpub automatically generates a Table of Contents for you. It will show Chapter headings in bold in a large font.

Front Matter, Main Matter and Back Matter

Authors often want their books to be composed of distinct front, main, and even back ‘parts’. For example, an Introduction will be numbered separately from the main chapters of the book. So an Introduction might be numbered (if you want numbering) 1, and then for Chapter One the numbering will start over at 1.

To format sections as front matter (like an introduction), main matter (the chapters of your book) and back matter (an appendix, say), you just need to type the following at the point where you want the front matter, main matter or back matter section to begin:

 1 {frontmatter}
 2 
 3 # Preface
 4 
 5 Blah blah...
 6 
 7 {mainmatter}
 8 
 9 # Some Chapter Title
10 
11 The chapter content...
12 
13 # Another Chapter
14 
15 Yada yada...
16 
17 {backmatter}
18 
19 Some stuff...

Each instruction should be on a line by itself, with blank lines above and below it. Unless the instruction is the first line in a .txt file, in which case you just need a blank line below it.

We do generally recommend that each instruction for a part should have its own file, so things are clear in book.txt. That means you should have a separate file that contains only the e.g. backmatter instruction and is called “backmatter.txt”.

Introduction & Acknowledgments

These sections are usually included at the front of the book as front matter. Files designated as front matter will be numbered as a separate set of files and their page numbers will be roman numerals (i.e. 5 is V). This means that when you start the next section, the numbering starts over.

To designate that a section is front matter, at the beginning of the section, just type:

1 {frontmatter}

on a separate line, with blank lines above and below it.

When you want the ‘mainmatter’ section to start, just type:

1 {mainmatter}

at the start of the main matter section (or at the end of the front matter section) on a separate line, with blank lines above and below it.

One easy way to do this is to make a separate text file that just contains the syntax indicating the start of the section.

So you could create a new text file, and just type:

1 {frontmatter}

and nothing else! If you save the file as frontmatter.txt in your Book.txt file, it might look like this:

1 frontmatter.txt
2 introduction.txt

and Leanpub will know to format the content of introduction.txt as front matter.

Front matter has no section numbering, even if you have turned on section numbering for the rest of your book.

Also, you only need to give each instruction once, and that instruction applies to everything that comes after, unless you type a new instruction. So if you type {frontmatter} in one file, everything after it will be frontmatter until you type {mainmatter}.

Appendix, Appendices, Index

These sections are usually included at the back of the book as back matter. Back matter has no section numbering, even if you have turned on section numbering for the rest of your book. However, page numbering continues unchanged.

To designate that a section is back matter, at the beginning of the section, just type:

1 {backmatter}

on a separate line, with blank lines above and below it.

Front Matter, Main Matter, and Back Matter Example

 1 {frontmatter}
 2 
 3 # Preface
 4 
 5 This is the first front matter section.
 6 
 7 # Introduction
 8 
 9 This is the first front matter section.
10 
11 {mainmatter}
12 
13 # Chapter One
14 
15 This is the first main matter section
16 
17 # Chapter Two
18 
19 This is the second main matter section
20 
21 # Chapter Three
22 
23 This is the third main matter section.
24 
25 {backmatter}
26 
27 # Appendix One
28 
29 This is the first back matter section.
30 
31 # Appendix Two
32 
33 This is the second back matter section.

Styling Text

Bold, Emphasis/Italics, and Underlining

You can emphasise text by putting * or _ (one underscore) before and after the text.

1 I am *emphatic*

You can make bold text by putting ** or __ (two underscores) before and after the text.

1 I am **bold**

You can do bold-italic with *** or ___ (three underscores) before and after the text.

1 I am ***bold-italic***

You can underline text with ____ (four underscores) before and after the text.

1 I am ____underlined____

Please note that some ebook viewers don’t display underlining. For example, you can see underlines on Kindle for Mac and on the Kindle Paperwhite, but Adobe Digital Editions doesn’t display them. Older Kindles may fail to display underlines as well.

Superscripts

Surround something in carets ^ to make it superscript. Like 1^st or 2^nd.

1 1^st^ or 2^nd^

Monospaced Text

Use backticks to make text monospaced (it looks red here, but won’t in your book).

1 I am `monospaced`!

Non-Breaking Spaces

You can add non-breaking spaces with  . This is useful for e.g. numbers that would be confusing if they were split onto more than one line. Here’s an example: 120 000 €

1 120 000 €

Blocks Of Text

Paragraphs

Paragraphs are consecutive lines of text. You can separate paragraphs from each other by putting a blank line between them.

You can also separate paragraphs, or blocks of text, by adding two spaces at the end of the paragraph. This is useful when you are going to follow a paragraph with another kind of text block, like a numbered list, or any of the other kinds listed in this section.

1 Paragraphs are consecutive lines of text.
2 
3 You can separate paragraphs from each other by putting a blank line between them.
4 
5 You can also separate paragraphs, or blocks of text, by adding two spaces
6 at the end of the paragraph. This is useful when you are going to follow
7 a paragraph with another kind of text block, like a numbered list.

Centering Paragraphs Or Lines Of Text

You can center paragraphs or lines of text by putting C> (followed by a space) at the start of the line.

Just type this in your .txt file:

1 C> This is a centered sentence on its own.

…and you’ll see this in your Leanpub book:

You can also group together blocks of centered text. Just type something like this in your .txt file:

1 C> This is a centered sentence.
2 C> Another centered sentence, in the same paragraph as sentence one.
3 C>
4 C> This sentence will be in a new paragraph.

…and you’ll see this in your Leanpub book:

Numbered/Ordered Lists

Numbered lists are easy to make.

1. This is the first item in the numbered list.
2. Each number (plus a period) should be followed by a space.
3. Once you start a numbered list, it doesn’t matter what number you put at the beginning of the line. This line starts with 1. as it is written, but appears in the ebook as 3.

1 1. This is the first item in the numbered list.
2 2. Each number (plus a period) should be followed by a space.
3 1. Once you start a numbered list, it doesn't matter what number you put at the begi\
4 nning of the line. This line starts with 1. as it is written, but appears in the ebo\
5 ok as 3.

Unordered/Bulleted Lists

To make a list without numbers, where items are separated by bullets, you add an asterisk * followed by a space at the beginning of a line.

• This is the first item in a bulleted list.
• This is the second item in a bulleted list.
• You can also use hyphens - to indicate you are making a bulleted list

1 * This is the first item in a bulleted list.
2 * This is the second item in a bulleted list.
3 - You can also use hyphens - to indicate you are making a bulleted list

Nested Lists

If you want nested lists, then you indent by two spaces:

• one
• two
• three
  • three.one
  • three.two

1 * one
2 * two
3 * three
4   * three.one
5   * three.two

Putting Code Blocks Inside Lists

To put a code block in a list, do something like this:

• one

  1   #!/usr/bin/env ruby
  2   puts "hiya"
  3   10.times {|n| puts n}
  

• two
• three

Some notes:

1. The code is indented by 8 spaces, not the usual 4.
2. There must be a blank line before and after the code block
3. Tilde delimited code blocks do not work.

1 * one
2 
3         #!/usr/bin/env ruby
4         puts "hiya"
5         10.times {|n| puts n}
6 
7 * two
8 * three

Putting Paragraphs Into Lists

If you’d like to add a paragraph in the middle of a list, and have the list numbering continue afterwards, you can indent the paragraph by four spaces.

1. This is the first one
2. The second

   A whole lot more info about the above item.

3. This is the third item
4. This is the 4th item

1 1. This is the first one
2 1. The second
3 
4     A whole lot more info about the above item.
5 1. This is the third item
6 1. This is the 4th item

Putting Images Into Lists

You can put images in lists, like this:

1. One thing.
2. Second thing.

   

3. Third thing.
4. Fourth thing.

1 1. One thing
2 2. Second thing.
3 
4    ![Leanpub Logo](images/LeanpubLogo1200x610_300ppi.png)
5 
6 3. Third thing
7 4. Fourth thing.

Definition Lists

Put the thing you want to define on a line by itself. On the next line, or after a blank line, type a colon followed by the definition. For a more detailed example that explains how to nest definitions and have multiple paragraphs in definitions, see https://kramdown.gettalong.org/syntax.html#definition-lists.

Ruby

A wonderful language.

JavaScript

Lovely little language that really shines when you add CoffeeScript to the mix. This is a longer entry to see what it looks like when it wraps to a second line.

Haskell

Messes with my head.

 1 Ruby
 2 
 3 : A wonderful language.
 4 
 5 JavaScript
 6 
 7 : Lovely little language that really shines when you add CoffeeScript to
 8 the mix. This is a longer entry to see what it looks like when it wraps to
 9 a second line.
10 
11 Haskell
12 : Messes with my head.

Putting Footnotes Into Definition Lists

You can include a footnote text in a list by putting two spaces before the line where you define the footnote. Here’s an example:

item1

some explanation without a footnote

item2

some explanation¹.

item3

more

 1 item1
 2 : some explanation without a footnote
 3 
 4 item2
 5 : some explanation[^foot].
 6 
 7   [^foot]:note
 8 
 9 item3
10 : more

Blockquotes

This is a blockquote

A blockquote should be indented.

The second paragraph should be indented as well.

And the third!

You can also have blockquotes inside blockquotes

1 > **This is a blockquote**
2 >
3 > A blockquote should be indented.
4 >
5 > The second paragraph should be indented as well.
6 >
7 > And the third!
8 >
9 > > You can also have blockquotes in blockquotes

Nesting Lists In Blockquotes

You can put lists in blockquotes. To do this, just add two spaces before each list item, and don’t type a > sign:

This is a blockquote

1. This is a list item.
2. This is another list item.
3. This is a third list item.

Now this is regular text in the same blockquote.

1 > **This is a blockquote**
2 >
3 >  1. This is a list item.
4 >  2. This is another list item.
5 >  3. This is a third list item.
6 >
7 > Now this is regular text in the same blockquote.

Asides/Sidebars

The code for the aside is:

1 A> This is an aside.
2 A>
3 A> This is also sometimes known as a sidebar.
4 A>
5 A> To make one of these, put `A>` at the beginning of the lines of
6 A> the aside, similar to the `>` that you use for a blockquote.

This is what the aside will look like:

If you want to title an Aside, you do it like this:

1 A> ## Your title goes here.
2 A>
3 A> This is also sometimes known as a sidebar.

This is what the aside with a title will look like:

If you want to cross-link to your aside, you can name your aside like this:

1 A> ## Your Aside title {#your-aside-title}
2 A>
3 A> This is also sometimes known as a sidebar.

Please note that headers ## that are inside of quotes, asides, etc. are not included in section numbering.

More Text Block Types

In addition to asides, there are warnings (W>), tips (T>), errors (E>), information (I>), questions (Q>), discussions (D>) and exercises (X>). There are also generic text blocks (G>) where you can pick an icon from a large selection. There’s more info below on how to do that.

Please note that these types of text blocks are meant to be short. While asides (defined with A>) carry over multiple pages, warnings and such do not.

Below you’ll find examples of each block type.

Warning!

Here’s the code for a Warning:

1 W> ## This is a Warning
2 W>
3 W> Warnings are generated by using `W>` at the beginning of lines.

And here’s what it looks like:

Tips

Here’s the code for a Tip:

1 T> ## This is a Tip
2 T>
3 T> To make a tip, put `T>` at the beginning of the lines of
4 T> the tip, similar to the `>` that you use for a blockquote.
5 T>
6 T> To make paragraphs in a tip, you need to put lines
7 T> with just `T>` between your paragraphs.

And here’s what it looks like:

Errors

Here’s the code for an Error:

1 E> ## This is an Error
2 E>
3 E> Describe a common Error here.

And here’s what it looks like:

Information

Here’s the code for an Information box:

1 I> ## This is an Information box
2 I>
3 I> Put some special information here.

And here’s what it looks like:

Questions

Here’s the code for a Question box:

1 Q> ## This is a Question box
2 Q>
3 Q> Ask & answer a common question here.

And here’s what it looks like:

Discussions

Here’s the code for a Discussion box:

1 D> ## This is a Discussion box
2 D>
3 D> You can discuss aspects of the main text in a Discussion box.

And here’s what it looks like:

Exercises

Here’s the code for an Exercise:

1 X> ## This is an Exercise
2 X>
3 X> Exercises are generated by using `X>` at the beginning of lines.

And here’s what it looks like:

Generic Boxes

If you want a different icon, you can take a look at the icons available from Font Awesome. Find one you like on that page, and then note the text beside it. For example, the first one has the text fa-automobile. Leaving out the fa-, we do the following to use an automobile icon:

1 {icon=automobile}
2 G> ## Vrooom!
3 G>
4 G> The freedom of the road!

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: https://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:

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:

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

Poetry

You can write poetry in Leanpub books. Here are a couple of tips:

Poetry Stanzas in Regular Markdown

To make stanzas, you have to put two blank spaces at the end of each line (i.e. press the space bar twice). Then you can get poems to look like this:

In Xanadu did Kubla Khan A stately pleasure dome decree: Where Alph, the sacred river, ran Through caverns measureless to man Down to a sunless sea.

Spacing Control for Poetry

For more powerful spacing control, for example to put letters wherever you like in the line, we have made a special block of text for poetry. This is necessary in order to produce poetry in a reasonably uniform way in many different e-formats with one click.

To make a block of poetry, you need to indicate where you are starting and stopping the block of poetry. Your readers will not see the instructions to start and stop the block of poetry; they will only see the poetry. Here is an example of what you need to do:

1 {style=poem}
2 ~~~~~~
3 In Xanadu did Kubla Khan
4    A stately pleasure-dome decree:
5       Where Alph, the sacred river, ran
6          Through caverns measureless to man
7             Down to a sunless sea.
8 ~~~~~~

If you type the above example into your text file, and then generate a Preview, in the ebook you will see this:

In Xanadu did Kubla Khan
   A stately pleasure-dome decree:
      Where Alph, the sacred river, ran
         Through caverns measureless to man
            Down to a sunless sea.

Please note the poem needs to have a line of six tildes ~ above and below it. This indicates that it’s a special block of text. And don’t forget to type {style=poem} where the poem starts, to indicate that the following block of text is a poem. Don’t worry, the tildes and {style=poem} won’t be visible in the book!

If you write using our special poem block of text, you don’t have to worry about putting the two spaces at the end of your lines.

Line Lengths

If a line of poetry is too long to fit in the margins, you will have to manually edit the line. You can also try changing the size of the book page, in the “Book Theme” tab under “Writing” in the book tools menu.

One last thing: you can actually copy and paste poetry from Microsoft Word in between the tilde lines, and the spacing of your words will be retained.

Links

Formatting Links

We support Markdown syntax for links, as well as normal HTML links. Here’s an example of a link to Leanpub:

Leanpub

1 [Leanpub](https://leanpub.com)

You can also create links like this:

https://leanpub.com

1 <https://leanpub.com>

Please note that we do not support reference-style links. Our opinion is that while they are a great idea for shorter texts like blog posts, they are generally a bad idea for longer texts, like books. This will be explained explicitly when we implement Markua (the successor to Leanpub-flavored Markdown).

Long Hyperlinks

If you have particularly long hyperlinks in your text, you may prefer to make the long link show up only in the footnote in the PDF.

To do this, first you should make sure you have ticked ‘Show links as footnotes in PDFs’ on the “Book Theme” tab under “Writing” in your book tools menu (and then scrolled to the bottom of the page and clicked ‘Update Book’ to save the change).

Then you can format the link with a custom name, so only that name shows up in the body of your text, and the link shows up in the footnote.

For example, instead of doing this:

https://groups.google.com/group/leanpub/browse_thread/thread/9dd1391e6d9899c9

1 [https://groups.google.com/group/leanpub/browse_thread/thread/9dd1391e6d9899c9](http\
2 s:https://groups.google.com/group/leanpub/browse_thread/thread/9dd1391e6d9899c9)

You can do this:

add a link name here

1 [add a link name here](https://groups.google.com/group/leanpub/browse_thread/thread/\
2 9dd1391e6d9899c9)

The part inside of the square brackets becomes a clickable link followed by a footnote number. The part in parentheses becomes a footnote, which is also clickable.

Footnotes and Hyperlinks in PDF

If you select “Book Theme” under “Writing” in your book tools menu, you will see a section called “Links”. The options here allow you to choose whether links are rendered only as links in the body of your text, or to also show them as footnotes or html-style-links in PDFs. The latter option only affects normal links (links where the displayed link text in the body of your book is different than the URL).

Footnotes and Endnotes

Footnotes

To add a footnote, you insert a footnote tag like this².

Then you add the footnote content later in the text, using the same tag, with a colon and a space:

That’s it. You can keep writing your text after the footnote content.

To add a footnote, you insert a footnote tag like this[^foo].

Then you add the footnote content later in the text, using the same tag, with a colo\
n and a space:

[^foo]: This is the footnote content.

That's it.  You can keep writing your text after the footnote content.

Please note it is best to put the lines with footnote content at the end of the text file (this helps avoid problems when you are e.g. using code blocks in your book).

In response to author feedback, we’d like to be very explicit about a few things:

1. There needs to be a blank line before and after the footnote content.
2. The ^ caret symbol is required.
3. Each footnote will need its own unique tag. So the first one might be [^foo1], the second [^foo2], etc.
4. The tag doesn’t have to have foo in it. It can be anything, like [^note1] or [^tag1].
5. At the moment, we don’t support periods in footnote tags, like this [^55.3].

Footnotes will format themselves correctly over multiple lines. However, if you want to continue the footnote on a second line using a line break of your own choice, you indent the second line (and any following lines) by 4 spaces.

Like this:³

[^foo2]: This is the footnote text. We are now going to add a second line
    after typing in four spaces.

Endnotes

We don’t have specific support for endnotes, but you can achieve this with crosslinks.

Remove Footnotes

If you want to remove footnotes for a specific section, and not for your entire book, you can put the following on a line by itself (with blank lines above and below it):

{footnotes-off}

To turn them back on, do this:

{footnotes-on}

Crosslinks

Crosslinks link one part of your book to another part of your book.

There are two steps to making a crosslink:

1. Give the thing you want to crosslink to an ID.
2. Create a crosslink to that ID.

Quick Explanation

Crosslinks are just like other links in Markdown, except that instead of linking to a web page, you link to an ID name you’ve created.

So, if you want to link the words ‘a previous chapter’ to a chapter heading in your book, you would type something like:

As we discussed in [a previous chapter](#chapter-32)...

… if you have already assigned an ID name to the chapter heading, like this:

# Chapter 32 {#chapter-32}

A Quick Note About Crosslinks

The ID can be on the same line as a chapter or section header, like this:

# Chapter 32 {#chapter-32}

But it can’t be on a line of text. So, for example, this won’t work:

{#SirHDavyResults} Sir H. Davy, a British chemist

To make it work, the ID should be above the text, with no blank line between the ID and the text, like this:

{#SirHDavyResults}
Sir H. Davy, a British chemist

In order to crosslink to an image, you will need to use the following syntax:

{id="cat-picture"}
![A picture of a cat](images/cat.jpg)

Then crosslink to it like this:

Remember that [picture of a cat](#cat-picture)?

It’s important not to have any blank lines between the id and the image, and the image needs to be by itself on the line.

The exact same thing works for a code-block, you just need to add an id:

{id='something-amazing',line-numbers=off,lang=ruby}
~~~~~~
def something
  puts "something, something, something"
end
~~~~~~

Longer Explanation

To link from one word (or set of words) to another, you first need to identify the word (or words) you want to link to. To do that, you need to give the word you want to link to an ID name. The ID name will not be visible to the reader.

You can create an ID name by adding some text enclosed in { and }, plus a number sign #, like this:

{#IDname}

You can call the ID anything you like, which is why we just wrote ‘IDname’ in this example.

So, for example, if you want to link to the start of a chapter, you can add an ID to the line at the start of the chapter, like this:

# Chapter 32 {#chapter-32}

Crosslinking to something with an ID

Now that the item you are crosslinking to has an ID, you can link to it from anywhere in your text.

To do that, surround the word or words you want to turn into a link with [ and ], and then follow that with a section in ( and ) which includes the ID name you made up.

To complete the example, here’s what you would type if you wanted the words ‘a previous chapter’ to become a link to the ID {#chapter-32}:

As we discussed in [a previous chapter](#chapter-32)...

Some Crosslink Details

Here we give an ID of shopping-list to a list.

{#shopping-list}
* Bananas
* Cream
* Pie Crust

Make sure not to put the ID within an element, like a list or a code block, however. The ID should come before or after the element. So you can do this:

{#anchor}
- `test`

    abc

but not this:

- `test`
{#anchor}

    abc

Here are some further technical details:

This Markdown:

{#anchor}
- `test`

    abc

Produces this HTML (and similar LaTeX):

<ul id="anchor">
  <li><code>test</code>
    <p>abc</p>
  </li>
</ul>

Breaks

Here’s how you can create line breaks and page breaks on Leanpub.

Pagebreaks

You can force a page break by adding {pagebreak} on a line by itself, with blank lines before and after. For example:

1 And the winner is....
2 
3 {pagebreak}
4 
5 Ta-dah!

Line Breaks

In Markdown, in order to indicate a line break, you type two spaces after a line and press return.

Also, in your book Settings you can select the option: “No indent, small vertical space between paragraphs”.

Tables

To make a table, you use vertical bars (|) to separate the columns of your tables. Here are a few examples.

This results in a very simple table with two columns of ingredients:

1 | 2 cups old fashioned oats          | 1 1/2 tsp vanilla              |
2 | 1 cup sunflower seeds              | 1/4 tsp salt                   |
3 | 1 cup shredded coconut             | 1/2 cup chopped pitted dates   |
4 | 1/2 cup toasted wheat germ or bran | 1/2 cup chopped dried apricots |
5 | 3 tbsp unsalted butter             | 1/2 cup dried cranberries      |
6 | 2/3 cup honey                      |                                |
7 | 1/4 cup packed brown sugar         |                                |

If you want the first line to be formatted as a heading, then do something like this:

1 |Verb   |Action                                          |Idempotent?|
2 |-------|------------------------------------------------|-----------|
3 |GET    |Responds with information about the resource    |Yes        |
4 |POST   |Creates a sub-resource of the resource POSTed to|No         |
5 |PUT    |Creates or updates the resource being PUT to    |Yes        |
6 |DELETE |DELETES the resource                            |Yes        |
7 |HEAD   |Gets metadata about the resource                |Yes        |

Table Width

Your book has a default table-width setting. By default, it’s set to “default”, which stretches tables to 80% of the page width.

The other two settings are “narrow” and “wide”. Narrow makes the table as narrow as possible, wide makes it take up the full page width.

You can set the default table-width on the “Book Theme” tab under “Writing” in your book tools menu.

The major drawback to narrow is that we do no automatic word-wrapping in PDFs, so the table may go off the side of the page. We recommend using default or wide mode.

You can also over-ride the width of individual tables by setting a width attribute. For example, if your book had a default table width of “wide”, the table below would be narrow:

1 {width="narrow"}
2 | one | two | three |
3 |-------------------|
4 | a   | b   | c     |
5 |-------------------|
6 | d   | e   | f     |

Here it is with {width="default"}:

You can use “wide”, “default” or “narrow”, or a percentage for the width parameter. The following table would take up exactly half the page-width

1 {width="50%"}
2 | one | two | three |
3 |-------------------|
4 | a   | b   | c     |
5 |-------------------|
6 | d   | e   | f     |

Multi-line rows

Here is that table from above reformatted to be narrower by using multi-line rows. The first dashed line makes the line before it a heading. The rest of the dashed lines just result in a larger vertical gap than a plain newline.

 1 |Verb   | Action                                   |  Idempotent?   |
 2 |-------|------------------------------------------|----------------|
 3 |GET    | Responds with information about the      |  Yes           |
 4 |       | resource                                 |                |
 5 |-------|------------------------------------------|----------------|
 6 |POST   | Creates a sub-resource of the resource   |  No            |
 7 |       | being POSTed to                          |                |
 8 |-------|------------------------------------------|----------------|
 9 |PUT    | Creates or updates the resource being    |  Yes           |
10 |       | PUT to                                   |                |
11 |-------|------------------------------------------|----------------|
12 |DELETE | DELETES the resource                     |  Yes           |
13 |-------|------------------------------------------|----------------|
14 |HEAD   | Gets metadata about the resource         |  Yes           |

IF you want to put line breaks in table cells, you can do the following:

 1 |Verb          | Action                                 |
 2 |--------------|----------------------------------------|
 3 |Multiline     | You can have multiple-lines in a       |
 4 |              | table, and line-breaks are respected.  |
 5 |              |                                        |
 6 |              | This is a second paragraph             |
 7 |-------------------------------------------------------|
 8 |continued!    | You create new table cells with a      |
 9 |              | line of dashes surrounded by pipes     |
10 |              |                                        |
11 |              | (Pipes are the vertical lines, "\|")    |

Alignment and footer rows

You can also do fancy things with alignment and footer rows. Here is an example.

1 | Default aligned |Left aligned| Center aligned  | Right aligned  |
2 |-----------------|:-----------|:---------------:|---------------:|
3 | First body part |Second cell | Third cell      | fourth cell    |
4 | Second line     |2nd line    | **strong**      |                |
5 |-----------------|------------|-----------------|----------------|
6 | Second body     |            |                 |                |
7 | 2 line          |            |                 |                |
8 |=================|============|=================|================|
9 | Footer          | footer2    | footer3         | footer4        |

Table Titles

You add a title to a table by adding a title attribute to the table, like this:

{title="Figure 32"}
| City          | Annual Rainfall (inches) |
|------------------------------------------|
| Rome          | 23                       |
| London        | 29                       |

Here’s what that looks like:

If you want to set both the title and the width, it looks like this:

{title="Figure 32",width="60%"}
| City          | Annual Rainfall (inches) |
|------------------------------------------|
| Rome          | 23                       |
| London        | 29                       |

HTML Tables

If you try putting an HTML table in a .txt file, you’ll find that it works in the epub and mobi version but is missing in the PDF. Here’s why:

Markdown normally just generates HTML. So it could “support” using HTML tables and any other HTML construct by just not parsing the HTML. But we need to actually parse the Markdown (we use a slightly modified Kramdown parser), in order to generate LaTeX and then PDF.

A note on combining attributes

To combine attributes for a table, add a comma and a space between the attributes, like this:

{title="table title", width="wide"}

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.

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:

1 # 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:

1 -# 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:

1 ## This is a section subordinate to a heading.
2 ### This is a section subordinate to ## sections
3 #### 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!

Notes