Formatting your markdown project for import

Help This Book supports the entire GFM markdown syntax, excluding tables. This means you can include things like fenced code blocks and footnotes in your manuscript.

To prepare your manuscript for import, double-check:

1. All chapter titles should use Heading Level 1 format (eg: # Chapter title )
2. If using images, check they are in the same folder as your markdown manuscript and package your project as a single zip file

Choosing what to upload

Help This Book accepts both single markdown files (.md ) and markdown project zip files (.zip ) .

Single file upload

If your manuscript is contained in a single markdown file (.md ) and includes no images, then you're ready to upload. Just make sure you document is following our formatting conventions.

Zip file upload

If your project has more than one markdown file or uses images, you'll need to bundle it as a zip file for upload. You can do this using the "Compress" menu item on MacOS, or "Send to > Compressed (zipped) folder" menu item on Windows.

Your zip file must contain at least one markdown file and all referenced images, like this:

Markdown Project.zip
├─ chapter 1.md
├─ chapter 2.md
└─ images/
   ├─ fig1.png
   └─ fig2.jpg

All markdown files must end in .md .

All images should use relative paths, not absolute. For example, the correct markdown syntax to embed fig1.png in chapter 1.md would be:

![Example title](images/fig1.png)

Formatting your markdown project

Help This Book supports GFM markdown, but there are a few style conventions you need to follow and a few exceptions you need to be aware of.

Chapter titles must use the Heading Level 1 style

Help This Book uses Heading Level 1 blocks to denote chapter titles. A chapter title must be contained in a single Heading Level 1 block.

Here is a correctly formatted chapter title:

# Chapter 1 - Welcome to the book (CORRECT)

On the other hand, the following incorrect example would be detected as two separate chapters:

# Chapter 1 
# Welcome to the book (INCORRECT)

Using filenames as chapter titles

If you are using an editor that uses filenames as titles, like Obsidian, it can be inconvenient to have to copy your note's title into the document again, effectively duplicating the work.

For this case, Help This Book supports an alternative mode where each file represents a chapter.

When this mode is enabled:

• The filename will be used as the chapter title
• Heading Level 1 blocks in the markdown files will be treated as subheadings in the chapter

To enable this mode, just toggle it on before you upload your markdown project zip file:

If this option is enabled for the example structure below would result in two chapters named "chapter 1" and "chapter 2", respectively (with any Heading 1s treated as sections within each chapter):

Markdown Project.zip
├─ chapter 1.md
├─ chapter 2.md
└─ images/
   ├─ fig1.png
   └─ fig2.jpg

Code blocks

Help This Book fully supports markdown code blocks, including syntax highlighting. To enable syntax highlighting, be sure to annotate the language in the fenced code block, eg:

``` js
function hello() {
  return "hi";
}
```

Mathematics

Help This Book parses and renders LaTeX mathematics included in markdown manuscripts. We support both MathJax and GitHub style block and inline math:

• For block equations, surround mathematics with $$...$$ or \[...\]
• For inline equations, surround mathematics with \(...\) or $...$

Where ... is the math your want to display. We recommend using the \(...\) style syntax for inline equations to ensure there is no confusion with other $ characters in a block.

Please note, Help This Book only supports LaTeX formatted math.

Tables are not supported

Help This Book does not currently support tables.

If your manuscript includes tables, the best workaround is to create an image of them and include that image in your text, directly above or below the table. The table will be ignored and the image imported, providing the correct flow for your beta readers.

Thematic breaks are not supported

Help This Book does not support thematic breaks (eg: *** or —-- ).

HTML must be wrapped in a code block

For security purposes, Help This Book automatically removes any unescaped HTML. If you wish to include reader-legible HTML in your document, make sure to enclose it in a fenced code block:

``` html
<h1>Readers will see this!</h1>
```

Feedback and bug reports

If you run into any issues with markdown import, please let us know what happened, which software you exported from, and anything else that might be relevant so that we can track it down. Many thanks.