The Basics

Welcome to the Leanpub Browser book writing editor! This page is where you will be writing your book. This file is a working, real example of how to write a book chapter in plain text with Markdown formatting (which we’ll explain briefly below).

This is a paragraph. You just write.

Blank lines are used to separate paragraphs.

To make italic text you surround it with single asterisks. To make bold text you surround it with double asterisks.

Creating ebook files from this manuscript is really easy to do! Just click on the Versions tab in the menu at the top of the page, to go to the Preview page. You can then click the Create Preview button to preview your book.

(Yes, these instructions are not just help text: they are also a book manuscript!)

Once the book has been generated, you can download it in PDF or EPUB format to see what it looks like.

You can start new chapters by starting a line with a # sign and a space, and then typing your chapter title, just like you can see at the top of this page, where you see # The Basics on a line by itself.

You can create multiple chapters in one file, but we recommend one chapter per file. This way, your manuscript files will be easier to navigate. So, for example, this chapter is contained in the file named “The Basics” that you can see listed under the “Manuscript” menu to the left. “The Basics” is in bold in the menu, because it is the file that is currently selected.

(If you start typing in here, the Manuscript menu and all the other menus will go away, so that you can relax and focus on your writing! Just click outside of this text area, and all the menus will come back.)

You can make a thematic break with three asterisks, like this:

By the way, the above formatting is actually all you need to know to write a typical novel using Markdown formatting! To write a technical book, however, you’ll need to know a bit more Markdown, and learn a bit about Markua.

Markdown and Markua

The dialect of Markdown used at Leanpub is called Markua.

Markdown is great, but it doesn’t have support for certain things that many books need. These include index entries, crosslinks, endnotes, external code samples, etc. So, we’ve added these to Markdown, by extending Markdown in an open specification called Markua.

The Markua spec is here.

However, that spec is really long, and there are a few advanced things in the spec which aren’t fully supported in Leanpub yet.

So, if you want to learn how to get started writing in Markua on Leanpub, see the next chapter, Writing in Markua, by clicking the Writing in Markua chapter under the Manuscript menu to the left.

This chapter will show you everything you need to know about how to use all the important parts of Markdown and Markua to create a technical book, including how to use…

• lists
• images
• code samples
• tables
• math
• resource attributes
• document settings
• asides and blurbs
• index entries
• crosslinks

Seriously, unless you already know everything about Markua, you should strongly consider looking at that chapter. It may save you a bunch of time!

Generate a preview version of your book

You should probably generate a preview of this version of your book next, to save a copy of these helpful instructions. (The Writing in Markua chapter can come in handy!)

Click on the Versions tab above to go to the Preview page, and then click Create Preview to do that.

Either read a tutorial, or just go for it!

At this point, there are two good ways to proceed. You can either read a tutorial and follow along, or you can just go for it!

(If you’re feeling adventurous, just go for it. The tutorial is linked on the Help > Getting Started page, so you can always read it later…)

Read the tutorial…

If this is your first time writing a Leanpub book in our Browser writing mode, after you’ve read the Writing in Markua we recommend you read our full tutorial here. That tutorial will guide you through every step, including previewing versions for your review, and even publishing the first version of your book when you’re ready!

…or just go for it!

Once you’re ready to start writing your book, simply select all the text in this file, delete it, and then start writing!

Start with # Your Chapter Name and then a blank line, and then write your first paragraph.

You can create new files by clicking the + button in the menu on the left, and you can delete the other chapter files by mousing over them, clicking the settings gear icon, and clicking the red Delete File button.

Thanks for being a Leanpub author!

On behalf of everyone at Leanpub, we really hope that you enjoy the experience of writing and publishing in-progress books on Leanpub. We are a bootstrapped startup which is entirely supported by our authors, and we’re really grateful that you have chosen to write your book using Leanpub…

{sample: true}

Writing in Markua

Writing in Markua is easy! You can learn most of what you need to know with just a few examples.

To make italic text you surround it with single asterisks. To make bold text you surround it with double asterisks.

Section One

You can start new sections by starting a line with two # signs and a space, and then typing your section title.

Sub-Section One

You can start new sub-sections by starting a line with three # signs and a space, and then typing your sub-section title.

Including a Chapter in the Sample Book

At the top of this file, you will also see a line at the top:

{sample: true}

Leanpub has the ability to make a sample book, which interested readers can download or read online. If you add this line above a chapter heading, then when you publish your book, this chapter will be included in a separate sample book for these interested readers.

Links

You can add web links easily.

Here’s a link to the Leanpub homepage.

Images

You can add an image to your book in a similar way.

First, add the image to the “Resources” folder for your book. You will find the “Resources” folder under the “Manuscript” menu to the left.

If you look in your book’s “Resources” folder right now, you will see that there is an example image there with the file name “palm-trees.jpg”. Here’s how you can add this image to your book:

If you want to add a figure title, you put it in quotes:

If you want to add descriptive alt text, which is good for accessibility, you put it between the square brackets:

You can also set the alt text and/or the figure title in an attribute list:

{alt: “a picture of palm trees against a blue sky”, title: “Palm Trees”}

Finally, if no title is provided, and the alt-title document setting is the default of all, the alt text will be used as the figure title instead of as alt text.

You can set the important document settings at Settings > Generation Settings.

Lists

Numbered Lists

You make a numbered list like this:

1. kale
2. carrot
3. ginger

Bulleted Lists

You make a bulleted list like this:

• kale
• carrot
• ginger

Definition Lists

You can even have definition lists!

term 1

definition 1a

definition 1b

term 2

definition 2

Code Samples

You can add code samples really easily. Code can be in separate files (a “local” resource) or in the manuscript itself (an “inline” resource).

Local Code Samples

Here’s a local code resource:

{format: ruby}

Inline Code Samples

Inline code samples can either be spans or figures.

A span looks like puts "hello world" this.

A figure looks like this:

puts "hello"

You can also add a figure title using the title attribute:

{title: “Hello World in Ruby”}

puts "hello"

Tables

You can insert tables easily inline, using the GitHub Flavored Markdown (GFM) table syntax:

Tables work best for numeric tabular data involving a small number of columns containing small numbers:

Definition lists are preferred to tables for most use cases, since reading a large table with many columns is terrible on phones and since typing text in a table quickly gets annoying.

Math

You can easily insert math equations inline using either spans or figures.

Here’s one of the kinematic equations d = v_i t + \frac{1}{2} a t^2$ inserted as a span inside a sentence.

Here’s some math inserted as a figure.

{title: “Something Involving Sums”}

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

Headings

Markua supports both of Markdown’s heading styles.

The preferred style, called atx headers, has the following meaning in Markua:

{class: part}
# Part

This is a paragraph.

# Chapter

This is a paragraph.

## Section

This is a paragraph.

### Sub-section

This is a paragraph.

#### Sub-sub-section

This is a paragraph.

##### Sub-sub-sub-section

This is a paragraph.

###### Sub-sub-sub-sub-section

This is a paragraph.

Note the use of three backticks in the above example, to treat the Markua like inline code (instead of actually like headers).

The other style of headers, called Setext headers, has the following headings:

{class: part}
Part
====

This is a paragraph.

Chapter
=======

This is a paragraph.

Section
-------

This is a paragraph.

Setext headers look nice, but only if you’re only using chapters and sections. If you want to add sub-sections (or lower), you’ll be using atx headers for at least some of your headers. My advice is to just use atx headers all the time. (The {class: part} attribute list on a chapter header to make a part header does actually work with Setext headers, but it’s really ugly.)

Note that while it is confusing and ugly to mix and match using atx and Setext headers for chapters and sections in the same document, you can do it. However, please don’t.

Block quotes, Asides and Blurbs

Block quotes are really easy too.

–Peter Armstrong, Markua Spec

A> Asides are useful A> for longer text. A> A> But typing them like this A> isn’t fun.

{aside} Asides can be written this way, since adding a bunch of A> stuff at the beginning of each line can get annoying with longer asides. {/aside}

B> Blurbs are useful

{blurb} Blurbs are useful {/blurb}

There are many types of blurbs, which will be familiar to you if you’ve ever read a computer programming book.

D> This is a discussion.

You can also specify them this way:

{blurb, class: discussion} This is a discussion {/blurb}

E> This is an error.

I> This is information.

Q> This is a question. (Not a question in a Markua course; those are done differently!)

T> This is a tip.

W> This is a warning.

X> This is an exercise. (Not an exercise in a Markua course; those are done differently!)

Good luck, have fun!

If you’ve read this far, you’re definitely the right type of person to be here!

Our last piece of advice is simple: once you have a couple chapters completed, publish your book in-progress!

This approach is called Lean Publishing. It’s why Leanpub is called Leanpub.

If you want to learn more about Lean Publishing, read this or watch this.