Introduction

Leanpub Flavoured Markdown vs. Markua

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

Leanpub Flavoured Markdown (LFM)

Markua

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.

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:

Markua is better than LFM. A lot better. Markua fixes the many mistakes we made with LFM.

Markua is the future of Leanpub.

Markua has more features than LFM.

If you want to create a course on Leanpub, you need to use Markua.

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.)

The Markua Manual is newer and better than the Leanpub Flavoured Markdown Manual.

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

You already started your book in LFM and you don’t want to convert it yet.

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.

Lord Char, black cloak flapping around him in the rising storm, rubbed his hands together in anticipation as he strode to the middle of the circle of stones. He had been years in preparation for this, his moment of triumph.

It was time to use the knowledge he had gained through years of patient planning. Now The Unnamed One would pay!

And this is the content of the file called chapter2.txt:

# Chapter 2: You Are Not My Father!

## A Horrible realization

Suddenly, he realized who his father had to have been.
No wonder the dark riders had chased him half way across the continent!

## The Horror Grows

With growing horror, he pulled the dark pulsing amulet from his cloak.
If The Unnamed One was truly his father, he shuddered, then the amulet must be The Jewel 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.

Book.txt and the manuscript Folder

You may have noticed that the list of files in Book.txt does not have to include all of the files in your manuscript folder. When Leanpub creates a Preview or a published version of your book, it only uses the files listed in Book.txt, not all the files in your manuscript folder. That way, if you think a chapter is not ready yet, you can keep working on it in your manuscript folder, but just leave it out of the list in Book.txt until you think it’s ready.

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.)

The Sample Book

Making a sample of your book available to potential customers is a great way to promote your book. It’s the virtual equivalent of what customers do in brick-and-mortar bookstares: they browse the shelves and take down books and read bits of what’s inside, to find the book they’re looking for.

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:

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:

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:

![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:

![](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.

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):

[Leanpub](http://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.

Formatting Email Links

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:

{some-attribute=value}

{some-attribute=”some attribute value”}

Quotes are only necessary if there are spaces.

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

{language=ruby,line-numbers=off}

Spaces are not significant, so you could also write:

{language=ruby, line-numbers=off}

or

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:

{frontmatter}

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

{line-numbers=on}

Here are the attributes supported:

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

special names:
{pagebreak}
{frontmatter}
{mainmatter}
{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:

Either use a separate text file for each chapter, or

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.

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):

Floating images and lists

Because of the way that we create floated images using LaTeX,
floated images and lists do not mix. If you have a floated image
and place a list beside it, the float will not stop where you would expect
it to.

There’s no real fix for this, but the workaround is to avoid using lists
next to floated images.

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 hello@leanpub.com.

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.

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 #####.

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:

{frontmatter}

{mainmatter}

{backmatter}

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:

{frontmatter}

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

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

{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:

{frontmatter}

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

frontmatter.txt

introduction.txt

and Leanpub will know to format 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:

{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 1st or 2nd.

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 &nbsp;. 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&nbsp;000&nbsp;€

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:

This is a centered sentence on its own.

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:

This is a centered sentence.
Another centered sentence, which will be in the same paragraph as sentence one.

This sentence will be in a new paragraph.

Numbered/Ordered Lists

Numbered lists are easy to make.

This is the first item in the numbered list.

Each number (plus a period) should be followed by a space.

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

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 http://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.

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

This is a list item.

This is another list item.

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:

This is an aside.

This is also sometimes known as a sidebar.

To make one of these, put A> at the beginning of the lines of
the aside, similar to the > that you use for a blockquote.

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:

Your title goes here.

This is also sometimes known as a sidebar.

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.

Your Aside title

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:

This is a Warning

Warnings are generated by using W> at the beginning of lines.

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:

This is a Tip

To make a tip, put T> at the beginning of the lines of
the tip, similar to the > that you use for a blockquote.

To make paragraphs in a tip, you need to put lines
with just T> between your paragraphs.

This is a Question box

Discussions

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:

This is a Discussion box

You can discuss aspects of the main text in a Discussion box.

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:

This is an Exercise

Exercises are generated by using X> at the beginning of lines.

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:

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:

[r1184] Using this version of OnStop, the termination handler can use
task.Invoke to execute some code in the main thread. This, however,
requires the ForEach abstraction to stay alive until the Invoke-d code
is executed so you must store the ForEach result

Code Sample Titles

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:

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).

Poetry

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:

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:

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.

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

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:

There needs to be a blank line before and after the footnote content.

The ^ caret symbol is required.

Each footnote will need its own unique tag. So the first one might be [^foo1], the second [^foo2], etc.

The tag doesn’t have to have foo in it. It can be anything, like [^note1] or [^tag1].

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.

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):

<ulid="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.

Multi-line rows

Multi-line rows are only necessary if you are using
the “narrow” table-width. If you find yourself spending time
manually wrapping text in tables, it’s probably better to use either
the “wide” or “default” table widths instead.

They are useful, however, if you want complete control over what text goes where or if you find that Leanpub’s line-wrapping is making some table columns too narrow.

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.

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:

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

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 about a year ago, and it is 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 the best of times, it was the worst of times

– Charles Dickens

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:

There must be a blank line between the list item and the code.

The {line-numbers=off} line should be indented by four characters.

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

There must be a blank line between the list item and the first line of the code block

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:

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!