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 headingIn 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
::: chapterand:::, 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, orchapterHeadingsin 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 write | You get |
|---|---|
"quoted" and 'quoted' | “quoted” and ‘quoted’ |
it's | it’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.
Links
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
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.