Skip to content

Markdown Basics ​

A Typoteka book is written in Markdown: plain text files where a few marks (#, *, -, …) say what is a heading, what is emphasised or what is a list. This page is the Markdown you need to write a book. What Typoteka adds on top of it, for book layout, is in Markdown Conventions.

How each element looks is up to the style you choose: the same text can be a novel or a role-playing manual.

Files ​

A book can be one Markdown file or several. They are read one after another as if they were a single text, in the order files.content lists them in typoteka.json, or in alphabetical order without that list (01-arrival.md, 02-the-cloister.md, …). One file per chapter is a common way to work.

Paragraphs and line breaks ​

Text separated by a blank line is a new paragraph. Lines that follow each other without a blank line between them are the same paragraph, so you can break your lines wherever you like while writing:

markdown
This is one paragraph,
written over two lines.

This is a second paragraph.

To break a line inside a paragraph (in a poem or an address), end it with a backslash, or with two spaces:

markdown
Roses are red,\
violets are blue.

Headings ​

A line that starts with # is a heading; more # make a lower level:

markdown
# Chapter One

## A section

### A subsection

#### A smaller heading

In a book, the levels mean something:

  • # is the largest heading: a chapter's title, and the one running heads take as the chapter's.
  • ##, ### and #### are sections inside it, each smaller than the one above.

A chapter starts on a new page. There are two ways to start one, and the book chooses:

  • A chapter block, the default: the chapter goes between ::: chapter and :::, and its headings can be any level.

    markdown
    ::: chapter
    # Chapter One
    
    The text of the chapter.
    :::
  • Every # heading, when the book turns on Every # heading starts a chapter (Project Settings → Basic → Book structure, or chapterHeadings in typoteka.json). Then a # is enough, and no block is needed.

With the setting off, a # outside a chapter block is a heading like any other, and does not start a page. Some styles start a chapter on a right-hand page.

Keep the levels in order: a ### belongs under a ##, not straight under a #.

Emphasis ​

markdown
*italic* or _italic_
**bold**
***bold italic***
~~struck through~~

Typographic quotes and dashes ​

Write plain keyboard characters; Typoteka sets them as a printed book does:

You writeYou get
"quoted" and 'quoted'“quoted” and ‘quoted’
it'sit’s
--– (en dash)
---— (em dash)
...… (ellipsis)

Lists ​

Lines that start with - (or *) make a list; numbers followed by a full stop make a numbered one. Indent an item to put a list inside another:

markdown
- Rope
- Lantern
  - Oil for the lantern
- Rations

1. Open the door.
2. Light the lantern.

Quotations ​

Lines that start with > are a quotation:

markdown
> It was the best of times,
> it was the worst of times.

How a quotation looks (indented, in italics, in a box) depends on the style.

markdown
[the text you read](https://example.com)

A web address written out, https://example.com, becomes a link by itself. On paper only a link's text remains, so write the address out when the reader will need it.

Images ​

markdown
![A caption for the image](images/map.png)

An image on a line of its own, with text between the brackets, becomes a figure with that text as its caption. The path is relative to the book's folder. Images has the rest.

Tables ​

Columns are separated by |, and a line of dashes separates the header from the rows. Colons in that line align a column to the left, centre or right:

markdown
| Item    | Weight | Cost |
|:--------|:------:|-----:|
| Rope    | 10 lb  | 1 gp |
| Lantern |  2 lb  | 5 gp |

The columns do not need to line up in the file; that only makes it easier to read.

A break between scenes ​

Three dashes on a line of their own, with blank lines around them, mark a break in the text, between scenes or sections. The style decides what it looks like: space, an ornament, a rule.

markdown
The door closed behind them.

---

Morning came late to the valley.

Footnotes ​

Mark the place with [^1] and write the note anywhere in the file, on a line of its own:

markdown
The cloister was built in a single winter.[^1]

[^1]: Or so the abbot claimed.

Notes are numbered in order. For now they are gathered at the end of the book, not at the foot of each page.

Code ​

Text between backticks, `like this`, is set as code, letter for letter. A block between two lines of three backticks keeps its line breaks and spaces, which is useful for anything that must be copied exactly:

markdown
```
10 PRINT "HELLO"
20 GOTO 10
```

Writing a mark as itself ​

To write *, #, _ or another mark without it doing anything, put a backslash before it: \*not italic\*.

HTML ​

Markdown can hold HTML for what it has no mark for, and Typoteka keeps it: <span style="color: darkred">, for example. Comments, <!-- like this -->, are left out of the book, so you can use them for notes to yourself. Prefer the layout blocks when one does what you need: they look right in every style.