Use "source" Jekyll configuration to avoid deployment mistake

Read the article on

Are you troubled with the cluttered project root for your jekyll site? Read on.

By default, Jekyll includes into the website whatever exists at the project root minus some files and directories that has special meanings.

|- GemFile  // safe by default
|- GemFile.lock  // safe by default
|- _config.yml  // safe by default
|- .gitignore  // safe by default
|-  // included
|- _posts  // included (parsed and then included)
 |- ...

There is one problem with this setup. If you add a script file here, you are going to expose that file!

|- Gemfile
|- ...
|-  // uh oh, you're exposing this file!

There can be multiple reasons for creating a non-Jekyll related scripts, examples being:

  • Automated build script for the server to publish your site
  • Yarn/Webpack config for your javascript needs

You could specify exclude key in your _config.yml, but this is merely a manual denylist - you may forget to add stuff until it is too late.

exclude: ["webpack.js"]

There is even better way:

The source key

This tells Jekyll to stop looking at the project root for the content to build; instead, it will use the directory you have specified.

source: "_src"

In this example, you put everything into _src directory and everything will work just as fine. No more need to update your exclude key!

One small notice is if you’re generating stuff outside of Jekyll, e.g., transpiling your typescript, you need to point the input and output into the source directory.