Troubleshooting Guide

Let’s look at common errors/issues. Most of the trouble tends to be from not getting the folder paths right in the argument switches or in the Markdown specs.

I’ve defined a variable (replacer, keyword etc.) but it says it can’t find it!

Variables in settings files are case sensitive! Check that you are typing exactly as defined. Also watch out for indentation—use spaces to indent, not tabs.

I’m getting some “YAML” errors!

Check your chapter frontmatters. Do you have “hanging” keywords at the beginning of the line? Lines in frontmatter require you to have a keyword: optional value - for e.g.,

this is bad

myChapter

---

but this is good

name: myChapter

---

Also check spacing and indentation. Don’t use tabs to space.

Document doesn’t show some images

This is usually due to one of these reasons

a) the image doesn’t exist

b) or the path you’ve specified in the Markdown document is incorrect or NOT RELATIVE to where the script is being run from.

c) your resources option in the globals file points to an incorrect location

includeExternal document isn’t getting inserted

The warnings on the result should usually tell you why. It’s usually for two reasons

a) the file is not of type md or txt

b) the file doesn’t exist (or you named it wrong)

c) the file exists but your path is incorrect—it must be RELATIVE to where the script is being run from.

I’m seeing some “pandoc” warnings and errors

The warnings/errors usually tell you what the problem is. Either you have a malformed document, your paths are incorrect or files don’t exist. Pandoc is the software that does the final conversion of a processed file to Word or ePub.