Create a book
Menu

Help › Manuscript standards

Manuscript standards

A manuscript is the single Markdown file you upload. This guide describes what MarkdownBooks requires (errors stop the upload), what it recommends (warnings do not), and what it does not support.

The file

  • One file with the .md extension, several .md files named 01-intro.md, 02-setup.md and so on (see Multiple files), or one .zip. Other file types are not accepted.
  • Saved as UTF-8 text. Most editors do this by default. If you see an error about encoding, re-save the file as UTF-8.
  • At most 20 MB, and a book length within the limits on the limits page.
  • Not empty. A file with only front matter and no text is also rejected.

Front matter (optional)

Front matter is a block at the very top of the file, between two lines of three dashes. It sets the title page.

---
title: The Long Road
subtitle: A journey in four parts
author: A. Writer
date: 2026
---

# Chapter One

Rules:

  • It must start on line 1.
  • It must be closed with a second line containing only ---. A block that is opened and never closed is an error (E008).
  • Each line is key: value. MarkdownBooks reads title, subtitle, author and date.

If you leave out the title, the book uses your first # heading, and if there is none, the file name. You will see a note (I201).

Headings and chapters

You write It becomes
# Heading A chapter. Each one starts on a new page in the PDF.
## Heading A section
### Heading A subsection

Follow these habits:

  • Put a space after the # marks: # Chapter, not #Chapter.
  • Do not skip levels. A ### straight after a # gives a warning (W102).
  • Give every heading text. An empty heading is a warning (W108).
  • Keep headings unique. A repeated heading is renamed automatically (W106), which can break links to it.
  • Use at least one heading. A file with none becomes one long chapter (W105).
  • Text before the first heading is used as an introduction (I202).

Code blocks

Open a code block with three backticks and close it with three backticks on their own line. A block that is never closed swallows the rest of your book, so it is an error (E005).

```python
def hello():
    return "Hello"
```

Add the language after the opening backticks to label the block.

Tables

Every row needs the same number of columns as the header, and the second line must be the separator row.

| Name  | Qty |
|-------|----:|
| Apple |   3 |
| Fig   |  12 |

A row with a different number of cells gives a warning (W104). Colons in the separator row set the alignment.

  • Web links: [text](https://example.com).
  • Links to a heading in the same file: [see below](#setup). The target is the heading text in lower case with dashes. A link to a heading that does not exist gives a warning (W103).
  • Footnotes: put [^1] in the text and [^1]: The note. on its own line.

Images

Images must be public https:// links. MarkdownBooks downloads each one when it builds the book and places it in the PDF, EPUB, Word and HTML files. Both Markdown images and <img> tags work, including the ones GitHub generates when you paste a picture:

![A red door](https://example.com/door.png)
<img width="1536" height="1024" alt="image" src="https://github.com/user-attachments/assets/0fc8d24e-3bf2-4631-8d1f-6bf4513bb5e3" />
  • If an image cannot be loaded, the book is not made and you get an Image not found error with the link and line (E010).
  • Images need to be PNG, JPEG, GIF or WebP, up to 10 MB each, at most 100 per book.
  • Relative paths such as images/door.png work when you upload a zip that contains the image. A path that is not in the zip is an error (E010). Without a zip they cannot be found, so they become a warning and are replaced by their alt text (W101).

Write meaningful alt text either way, so the book still reads well:

![A red door at the end of a corridor](door.png)

What is not supported

These are removed or shown as plain text, for safety and consistency:

  • Raw HTML such as <div> or <b>. It is removed (W107). Use Markdown instead. HTML comments (<!-- note -->) are fine.
  • Raw LaTeX and raw Typst blocks.
  • Dollar-sign math such as $x^2$.
  • Attribute syntax such as {.class}, and ::: fenced divs.
  • @name citations. They are treated as ordinary text.
  • Headings inside block quotes or lists. They become bold text.

Checklist before you upload

  • [ ] The file ends in .md and is saved as UTF-8
  • [ ] Front matter, if present, is closed
  • [ ] Every code block is closed
  • [ ] Headings have a space after #, are not empty, and do not skip levels
  • [ ] Table rows all have the same number of columns
  • [ ] There is no raw HTML
  • [ ] Images have alt text

Tip: paste your draft into the manuscript checker or the Markdown linter to test most of this in your browser.

Something unclear? Tell us and we will improve this guide.