Mike Higginbottom

Setting Up A Remote Hosted Jekyll Blog

Created 2026-06-14

WordPress is a great blogging platform but if you want something a bit lighter weight then Jekyll is a good bet. For me, I keep notes and todo lists and all that gubbins stored in plain text files formatted in Markdown. If I want to take a section of my notes and publish it online then I have to go into the admin section of WordPress and create a post and fill in boxes and reformat the text and it’s all a bit of a faff. Jekyll works the same way I do though. It stores articles in Markdown format in plain text files with no database complications, no worry about scripting complicated backups and I can easily write locally and deploy to my remote server with just a quick git push deploy master. Here’s how.

I’m doing this on Ubuntu Linux so you may need to tweak things a little if you’re on Windows or Arch or macOS or whatever.

1. Install Jekyll locally
2. Create a local bare-bones Jekyll site
3. ssh onto the remote machine
4. Create and add a key to authorized_keys on the remote machine.
5. Install Jekyll on the remote server.
6. Create a folder to store the git repo on the server. E.g. mkdir /home/user/Documents/blog-repo.git and cd into it.
7. Run git init --bare to create a bare git repo on the remote machine to receive your content when you git push to deploy to it. Note that this is just a repo to receive the source files for the site. It’s not where the actual site will be built to or served from.
8. Create a post-receive file.
9. Create a folder to receive the built site from the git repo once Jekyll has built it. This is where the web server will serve your site from. E.g. mkdir /var/www/blog
10. Add a git remote to your local machine. git remote add deploy user@example.com:/home/user/Documents/blog-repo.git
11. Execute git push deploy master to push your content up to the remote repo.
12. The post-receive git hook will spot the changes to your remote repo and build your site in your remote server’s web folder.
13. Go to your web site’s address in your browser and bask in the glory.
14. jekyll-diagrams is handy if you need to generate diagrams on your pages.

Install Jekyll

1. Install ruby using sudo apt install ruby-full.
2. Run gem install bundler jekyll to install the bundler and jekyll gems to the local repository.

Bare-bones Jekyll Site

1. Run jekyll new /home/user/Documents/blog to create a bare bones site.
2. Do cd /home/user/Documents/blog to get into your new site’s folder.
3. Run bundle exec jekyll serve to start the jekyll server and build your site.
4. Now browse to http://localhost:4000 and you should see your site rendered on your local machine; something like this:

Bare Site Screenshot

Create a Post-Receive File

Change directory into the remote repo folder and create a file hooks/post-receive.

#!/bin/bash -login

REPO=$HOME/Documents/blog-repo.git
SITE=/var/www/blog

TEMP=$HOME/tmprepo
git clone $REPO $TEMP
export PATH=$PATH:$HOME/gems/bin
BUNDLE_GEMFILE=$TEMP/Gemfile bundle install
BUNDLE_GEMFILE=$TEMP/Gemfile bundle exec jekyll build -s $TEMP -d $SITE
rm -rf $TEMP
exit 0

Do chmod +x hooks/post-receive to make it executable. If you forget this your remote repo will get updated when you push to it, but the site won’t get generated.

Jekyll Diagrams

1. Edit the Gemfile to include the following:

group :jekyll_plugins do
  gem 'jekyll-diagrams'
end

1. Then run bundle from a command prompt to install it.
   
2. Do sudo apt install graphviz to install dependencies.
   
3. Add some config to _config.yml:

diagrams:
  graphviz:
    engine: dot
    options: '-Tsvg'
  blockdiag:
    options: '-Tsvg --nodoctype'