Between Jekyll & Next.js

Intro

As I mentioned previously, Jekyll by default uses Kramdown render. I had no issues with it and had no inclination to step away from it. So, I let it enjoy its days. Later on, I was toying with Next.js and found out that I can create a blog based on a set of static files (one of the many options supported by Next.js), so naturally I thought: why not both? Why not write a post once and publish it in both Jekyll and Next.js?

The Markdown Renderers

Out of the box, Jekyll uses Kramdown as its default markdown renderer. As awesome as it was, it was too awesome. It is a ruby only renderer that supports some really cool features. Some really cool features that I couldn't find a drop in js renderer replacement. So, I decided to switch to a much simpler renderer; CommonMark here I come.

Changing Jekyll's Markdown Renderer

  1. Head over to Gemfile and find the section starting with group :jekyll_plugins do and add the new renderer to the loop. For my version, the results are as follows (I only added gem 'jekyll-commonmark') 

    group :jekyll_plugins do
    gem "jekyll-feed", "~> 0.12"
    gem 'jekyll-commonmark'
end

  2. For the changes to the Gemfile to take effect, a bundle install is required. This installs the necessary dependencies associated with the renderer.

  3. Head over to _config.yml and add markdown: CommonMark to instruct Jekyll on which markdown renderer to use. If another renderer is already in the file, then just change it to CommonMark. Having no markdown set will set the renderer to the default value of kramdown

  4. The final part; check all of your posts to make sure none broke. This part is really just going over the posts and various pages, changing the syntax from one renderer to another. For my case, kramdown support rendering direct html while CommonMark would escape the html and show it as it (as unprocessed/unrendered html tags). Pure manual work with the positive side effect of forcing you to get to know your new markdown renderer syntax and quirks.

Next.js Hosting Solutions

Stepping back a bit, Jekyll and Next.js are two different beasts. Jekyll generates the entire site at build time as html and hence any web server can be used to serve compiled Jekyll sites (since they are just html pages). Next.js - on the other hand - requires a node.js environment to run. As I was reading about Next.js, I found out about their own hosting environment; Vercel. I've already been using Netlify for Jekyll, and have still lots of learn there and didn't feel like switching just yet. But hey, for small loads, Vercel is free. So the next step is obvious: run Next.js on Vercel and keep Jekyll running on Netlify. The first part went smoothly - create a vercel account, integrate it with Github (or whichever of the supported source control providers) and follow the prompts. In no time you'll have a running next.js web app. Too smoothly, I felt like I needed something else to struggle with. So, I created another task for myself; why not run a copy of my Jekyll site on Vercel?

Same as before, from my Vercel dashboard initiate the import project process and selected my Jekyll project, next, next, next and baaaam! the build failed! What went wrong?

Retrieving list of deployment files...
Downloading 16 deployment files...
Installing build runtime...
Build runtime installed: 402.278ms
/ruby27/lib/ruby/2.7.0/rubygems.rb:275:in `find_spec_for_exe':
Could not find 'bundler' (1.17.3) required by your /vercel/5ccfaa4c/Gemfile.lock.
(Gem::GemNotFoundException)
To update to the latest version installed on your system, run `bundle update --bundler`.
To install the missing version, run `gem install bundler:1.17.3`
    from /ruby27/lib/ruby/2.7.0/rubygems.rb:294:in `activate_bin_path'
    from /ruby27/bin/bundle:23:in `<main>'
Error: Command "bundle install" exited with 1
Done with "_config.yml"

What does this mean? What do you mean cannot find bundler? Vercel, how did you plan to install Jekyll at the first place if you could not find bundler? To cut it short, my first clue was the version number mentioned in the logs. My Jekyll was using 1.17.3. Ok. What about the demo used by Vercel? Ooooh, it was using 2.1.4. I updated my used bundler and viola, it works.

Utilizing Subdomains

I already have my own domain that is used by my Netlify application. But, I could create subdomains and have them assigned to my Vercel applications.

  1. Head over to Vercel dashboard and select the desired project then Settings > Domains
  2. enter the desired subdomain and select Add. Note that here you can enter any subdomain of your choice; say your domain was amazingjoe.com, then here you could enter blogamazingjoe.com, splendid.amazingjoe.com or even superduperjoe.amazingjoe.com. In short anything.yourregistereddomain.whateverisalreadyyours should work.
  3. Vercel will spin for a few seconds and then complain Invalid Configuration. Now you do have a choice here:
    1. Change the nameserver to whatever Vercel is suggesting. Unless you are hosting everything related to your domain at Vercel, or you have nothing else hosted or at least you know what you are doing, avoid this path.
    2. Add a CNAME: Switch to the CNAME tab and copy that name listed as value. Then head over to where you have your domain DNS records (In my case it was Netlify), and add a new CNAME record with name = your new subdomain and value = the string you copied earlier.
  4. Give Vercel a few minutes to catch up and if you did everything right, your newly added subdomain will have a new badge of Valid Configuration. Go for it and hopefully your Vercel project will now be available at your new shiny subdomain.
← Back to home