TLDR: I commit the output of jekyll build and use a symbolic link to point /blog/ to /jekyll/_site. Works great!

I recently set up this blog using Jekyll hosted on GitHub pages. It was a lovely experience getting started and gave me exactly what I was looking for - a full featured blog framework that gets out of my way and lets me just write.

But there was one gotcha that almost made me abandon ship. I really wanted to host the blog at danpaz.me/blog, while keeping the same splash page at danpaz.me that I already have in place.

I took the first step of adding the /blog baseurl in my jekyll configs.

...
baseurl: "/blog" # the subpath of your site, e.g. /blog
...

Then I saw this in the jekyll docs:

Source Files Must be in the Root Directory

GitHub Pages overrides the “Site Source” configuration value, so if you locate your files anywhere other than the root directory, your site may not build correctly.

Meaning that in order for GitHub to properly build the jekyll site I would have to keep all jekyll files at the root of the repo, and the site’s index.html would be generated by the jekyll build. So I would lose my splash page! One workaround is to replace the jekyll theme’s index.html with my own, but then I’d lose the nice blog post list the theme provides.

Instead, I decided to commit the output of jekyll build in the _site/ directory. But to make sure the blog is served at danpaz.me/blog and not danpaz.me/blog/_site/ the built files need to be in a blog directory in my github repo. I considered copying the built files into a blog directory every time I build with jekyll, but I decided to try using a symlink to avoid the manual copy step.

$ ln -sv jekyll/_site blog

I wasn’t sure if GitHub would support symbolic links in this way, but turns out it works fine!

Now my workflow is to keep a terminal open with jekyll build watching to rebuild the site:

$ cd jekyll
$ jekyll build --watch

Now I can add and edit posts to the jekyll/_posts/ directory without thinking about building the output. If I need to view my blog locally I instead use jekyll serve.

Any thoughts on this approach? Get in touch and let me know!

-D