Troubleshooting

Jekyll Throws Errors about JavaScript File

Official article on the matter—Could not find a JavaScript runtime. (ExecJS::RuntimeUnavailable).

Suggested solution: Install execjs and therubyracer gems.

Commands to run:

gem install execjs

gem install therubyracer

Note that therubyracer gem may alert an issue about an installation failure. Disregard it and try building the Jekyll site again.

Jekyll Fails to Locate Valid web.config

Issue: $ jekyll build throws an error that it cannot locate valid web.config in the target output directory.

Cause: This error typically occurs when you are running $ jekyll build without specifying --destination or if you are running the command for the first time and the output directory does not exist.

Workaround: Run $ jekyll build --destination <Target Output Directory>. If the operation fails again, copy web.config from the root of the documentation repository to the target output directory and run $ jekyll build again.

Jekyll does not Generate a Site from my Markdown File.

Issue: I created my *.md file, but Jekyll won't create the corresponding HTML page.

Cause: The encoding of the file. The file might be created using UTF-8 with BOM encoding. BOM is a sequence of binary characters, located at the beginning of the file (0xEF,0xBB,0xBF). It instructs the engines that this is a string with UTF-8 encoding. Jekyll fails to read the file, and thus, the generation of HTML is terminated.

Solution: Open the file in Notepad++, change the encoding to UTF-8 without BOM (this will automatically remove the BOM from the string) and save the file.