DEV Community 👩‍💻👨‍💻

C. Plug
C. Plug

Posted on • Originally published at

How to include secondary Jekyll website using submodule


The technique explained in this article expects that you own an HTTP server that you can run ruby/bundler on and build your Jekyll site on.
This technique is not available for GitHub Pages.

The problem

After several month of Jekylling, I found it tedious to build my site locally and to upload it with scp, rsync, or something. I wanted my site to be built on the server, so that's what I did.
Then I realized I had another website which was hosting a blog at the "root directory" of your website while serving another Jekyll site at the different directly inside that.

Specifically, I had my dev blog and it also had product pages in the subdirectory and that page took advantage of _data directory and so on. It would be less confusing if you could source-control the two blogs separately by isolating them into different repositories.  # A Jekyll site (A)
|- /2022/06/20  # Root level blog for site (A)
|- /another_product  # Separate Jekyll site (B)
Enter fullscreen mode Exit fullscreen mode

I have tinkered around the Jekyll configuration and managed to pull it off, which I'll share with you here.


  • Create a source directory in your root blog project and move source there. Remember the dir name, you will use that later
  • Include your secondary site as a submodule at the project root
  • Edit your root site _config.yml to exclude that submodule from root site build procedure
  source: ["src"]  # The source directory you have created.
Enter fullscreen mode Exit fullscreen mode
  • Build the submodule site
  cd submodule_site
  JEKYLL_ENV=production bundle exec jekyll build
  cd ..
Enter fullscreen mode Exit fullscreen mode
  • In the output directory of your root Jekyll site, create a symlink (e.g., submodule_site) pointing to the output directory of secondary Jekyll site
  cd $PROJECT_ROOT/_site
  ln -s ../submodule_site/_site submodule_site  # This will be a part of your actual link!
Enter fullscreen mode Exit fullscreen mode
  • Edit your root site _config.yml to include this line
  keep_files: ["submodule_site"]
Enter fullscreen mode Exit fullscreen mode
  • Build both sites
  • Profit

First thing first

When you do something like this, you should consider moving your website source into a directory of your choice, as including another Jekyll website as a submodule may confuse Jekyll.
This is because, by default, most of the stuff in the project root is considered the source for the blog. Having another Jekyll project in such place can mangle everything.
Consult my another post on how to do this:

Jekyll wants to play clean

If you put a symlink to the output directory of your submodule site into your source directory (by default it is your project root,) everything blows up at build time for some reason.

Now, the only thing we could possibly do is to create a symlink to the output dir of the submodule site into the output dir of the root site.

cd root_site/_site
ln -s ../submodule_site/_site submodule_site
Enter fullscreen mode Exit fullscreen mode

But this does not work as everything in _site directory is wiped clean every build.

There is, however, a configuration key to stop this behavior.

The keep_files key

Configuration Options | Jekyll • Simple, blog-aware, static sites

The tables below list the available settings for Jekyll, and the various options (specified in the configuration file) and flags (specified on the command-line) that control them.


You can use keep_files key to tell Jekyll to leave specific files/directories behind before performing a clean on build. This key works for symlinks, too!

keep_files: ["submodule_site"]
Enter fullscreen mode Exit fullscreen mode

Time to build

By building both the submodule site and the root site, you will have created a working site in the _site directory. By symlinking the output dir of the root site to your webroot, you can serve the website!

Top comments (0)

We are hiring! Do you want to be our Senior Platform Engineer? Are you capable of chipping in across sysadmin, ops, and site reliability work, while supporting the open source stack that runs DEV and other communities?

This role might just be for you!

Apply now