DEV Community

Cover image for Switching from a CMS to Jekyll
Ajay Karwal
Ajay Karwal

Posted on • Originally published at

Switching from a CMS to Jekyll

Back in February, I shipped a new version of my website. Only a very slight update to the design but a complete overhaul on how it was built.

Everything was originally built using Umbraco – a CMS powered by .NET – and hosted on Microsoft Azure. This setup of course was reliant on Windows for developement.

I'm a Mac user so in order for me to update my website I needed to run Windows in VMmare Fusion, fire up the project in Visual Studio, setup my localhost and IIS Express, log into the Umbraco dashboard and then make my updates.

When it came to deploying my changes, I would then have to FTP my Views, DocumentTypes (Templates), DataTypes, DLLs and static assets.

Just kill me now. 😭

Up steps Jekyll

I first heard about Jekyll and other SSGs on the Toolsday podcast (exactly one year before I launched my site update) and it had been on my 'things-I-want-to-try-one-day' list ever since.

I started by creating a blank Jekyll site.

jekyll new myblog --blank

If you follow the quick-start guide you end up with a simple blog theme which I didn't want as I was going to be importing my existing design.

The problem with this process is that the command bundle exec jekyll serve won't work as the installation doesn't have a Gemfile or a _config.yml file. More on this later.

Once installed, Jekyll creates the basic folder structure required to organise your site.

├── _drafts
├── _layouts
├── _posts
└── index.html

Notice how the folders begin with an underscore. Any folders named this way are not outputted to the compiled _site folder.

Migrating my content

I started by coping over all my Views from my Umbraco project into my Jekyll _layouts folder. Luckily both systems use similar concepts of layout templates, page templates and partial views (_includes in Jekyll), so it was relatively painless to get my file structure right.

Next I converted my View logic from C#/Razor into Liquid, the templating engine that Jekyll uses (which was developed by Shopify). All of the logic has a like-for-like replacement as my site wasn't doing anything too complex.

Jekyll has Sass pre-processing built in so it was just a case of copying over my sass folder and adding an underscore to have it ignored from the build. I continued to add the remainder of my assets, includes and templates. You can see the full site structure on my GitHub repository.

Where the magic happens

The most important files you will need to create are a Gemfile and a _config.yml file in your project root.

The Gemfile lists any Ruby Gems which are needed to build your project. At the very least this file should contain,

source ''
gem 'jekyll'

The _config.yml file is where the magic happens. It contains all the site settings and you can add any custom settings which are then available to your liquid templates using {% raw %}{{ site.SETTING_NAME }}{%endraw%}. You can use my config file as a template for your own project or follow the Jekyll documentation.

Building your static site

Now that the basic file and folder structure is in place, simply run,

bundle exec jekyll serve --watch

This will bundle any Ruby Gems defined in your Gemfile, generate your static files to a _site folder, serve up your site on localhost:4000 and watch for any changes you make from now on.

That's it, you're done.

Congratulations on converting your CMS driven website to a static website powered by Jekyll. 🎉


Overall the process of moving from Umbraco to Jekyll was relatively simple. The documentation is very clear and there is plenty of support available on Stack Overflow for scenarios where custom logic is required in your Liquid templates.

Every use case is going to be different so take this with a pinch of salt, but the over-arching pros and cons which I feel would apply to all are:


  • The output is just static HTML, CSS and JavaScript so the resulting site loads extemely fast. It can also take advantage of browser caching to make return visits even more rapid.
  • No complex hosting package or server-side processing is required which could dramatically reduce the cost of running your website. You can even host it for free via GitHub Pages.
  • Writing your content in Markdown results in clean, semantic markup and encourages a more structured approach to your content.


  • There is a dependency of using the command-line to generate your site each time you make an edit, so some development expertise is needed. This means Jekyll is probably not a great solution for a client project where content is being managed by the client themselves.
  • Not really suited for sites which are updated very frequently.

Final thoughts

I would highly recommend that you try out Jekyll. Set up a test project and get a feel for how the content is structured. The Liquid templating engine is a joy to work with and has a very low barrier to entry.

If you're using Jekyll for your website, I'd love to hear about your experiences.

Top comments (14)

that__anna profile image

I'd like to update this thread to mention the existence of Netlify CMS. The author writes in the OP that

"There is a dependency of using the command-line to generate your site each time you make an edit, so some development expertise is needed. This means Jekyll is probably not a great solution for a client project"

but that is simply not true anymore!

After the site is done, you create an admin folder with an index.html (which contains a script that loads Netlify's admin panel UI) and a config.yml (in which you specify the fields that will be available in the UI). You can then manage multiple users using Netlify identity.

For the end user/content creator the experience is the same as using a standard CMS but the benefits of using a SSG remain.

maxwell_dev profile image
Max Antonucci

Really like the article! I had a similar moment several years ago, I was running my own site on WordPress and it was a pain. Managing the database, paying for and dealing with hosting services, and dealing with security and updates constantly. Moving to Jekyll was more than worth it to make my own site cheaper, easier, and more fun to manage.

One extra point I'd add on is that it's great to pair Jekyll with an asset tool like Gulp or Webpack. It's allowed me to included autoprefixing for my CSS and use Browserify for compiling my site's JavaScript. The scripts for running both Jekyll and Webpack can be defined and run simultaneously with NPM, so I get it all going with a simple npm start command. But that's more of an advanced Jekyll step, so it'd be better for a separate article anyway.

ajaykarwal profile image
Ajay Karwal

Thanks for the appreciation.
Having the Jekyll scripts bundles with npm start is a great idea. You should write up an article about your process.

atyborska93 profile image
Angelika Tyborska

I have been running my modest dev blog for 1,5 years now, using Jekyll (comments with Disqus), and I am now sure that was an excellent choice for my needs. Writing dev posts in markdown fits my writing process very well, it's the way I document my code at work too. And I can keep the whole content of my blog on GitHub.

docsbydesign profile image
Bob Watson

You might check out Github Pages. It offers all of the benefits of Jekyll that you list here with none of the command-line build and host technical issues.

I haven't tried it, yet, but if I'm reading their documentation correctly, you don't have to host the resulting site on if you want to have your own host URL.

Another thing I haven't tried, but seems to be described in the documentation, is connecting triggers to Git events that will automate the build and publish commands.

What I can, say from first-hand experience is that hosting documentation on using GitHub Pages has made documentation and updates a no-brainer.

ajaykarwal profile image
Ajay Karwal

The command line is still needed for local testing even if using GitHub pages.

You're right about the hosting. They provide it for free.
The only limitation is that with GitHub pages, Jekyll plugins are not available so if you're relying on any of these you'll have to host yourself else where.

Luckily though, I've also written an article about how to automate the build and deploy of a Jekyll site to any FTP host using Travis CI.

docsbydesign profile image
Bob Watson

Not being able to test intermediate (or local) builds was a problem I had earlier and I also thought that auto building would be the only way.

But, then I had a simpler idea: fork my own repo.

Now, the "published" documentation (what I want the world to see) is in my main account in the github pages doc folder of the project repo. I then created a separate, development account into which I forked the published repo. From the forked repo, I can test and publish (to another URL that I don't tell people about) as github pages automatically builds the work-in-progress docs under the development repo. When I like my changes, I send a pull request to the published repo to update it.

With that scheme, no hosting is required, no building is required, and you get instant (and manageable) documentation with no need to spin up (and manage) a server.

Yes it has some Jekyll limitations, but for the minimalist case where you don't want to manage any build or hosting servers, the tradeoffs might be worth it.

Thread Thread
ajaykarwal profile image
Ajay Karwal

That's a good workflow you have there. You should consider writing up an article on about your process and the reasons why. I'm sure it'll be really useful for people.

rubelhossain profile image
Rubel Hossain

I Love Jekyll, It's Very Fast And Easy To maintenance. I Have 3 Years Working Experience In Jekyll Theme Development. If Any One Need Jekyll Website Just Knock Me Here,

bcnzer profile image
Ben Chartrand

Nice article! Jekyll is also in my to-learn basket. I love the thought of a pure HTML /JS/CSS site served up by a CDN. I was thinking of using Jekyll, Cloudflare (free tier to handle DNS, CDN and TLS) and something like Amazon S3 for storage. Would be cheap and fast.

The cons listed are significant. Not sure I'd want to use it to, say, build a page for my friend's business. While their needs are simple I'd like to empower my friend to manage it themselves, hence why I've pushed friends down the path of products like WordPress. Likely the reason why I may end up keeping Jekyll on the to-learn list.

ajaykarwal profile image
Ajay Karwal

Totally agree. That slight dependency of knowing how to code and use the terminal means its not really suited for (most) clients to manage their own sites.

You could also rely on GitHub for free hosting...

jsalvador profile image
Juanjo Salvador

I've been using Jekyll since 3 years ago at my website ( It is very powerfull, extensible, secure and clean, but, as Tom (Jekyll creator) says... it's just for hackers.

ssteinerx profile image
Steve Steiner

What do you use for commenting, if anything? That's just about the only thing that keeps me in WordPress at this point.

ajaykarwal profile image
Ajay Karwal

I use Disqus. Just include the embed script in my Page template and then in the front matter I have an option to set 'comments: false' if I want to turn them off on a particular page.