Jekyll basics tutorial, index.html autogen and Liquid not rendering

Hello. I’m very, very new to Jekyll and most of the related things. I’m going through the step-by-step tutorial on the website, and I’m stuck quite early on with two primary issues.

  1. When I try to implement Liquid filters, such as the downcase example, nothing is processed on the actual html file, it just says the code itself sans the html code. I made sure to include the front matter dashes at the top of the page.

  2. When I want to see the website in my browser, I use the following command in the Terminal:

jekyll -s [custom path to root folder] -d [custom path to already existing _site folder]

I can now see my website using the localhost:4000 address, but when I do this, my tutorial document “index.html” will be overwritten by the default “index.html” file, every time.

I just assume I’m going about this the wrong way.

This is all going on on a 2012 Macbook running macOS 10.13.6.
I’m using Jekyll v4.1.1
and Ruby v2.3.7

Thank you in advance.


Possibly you are accidentally editing files in the _site folder? That would explain the overwriting. The _site folder is where Jekyll puts the built site – everything in _site is deleted with each build.

That would make sense. But then I’m left with a very basic question: how do I add my own index.html page to the _site build? Does it only autogenerate the default index.html page when it cannot find any files already named that?

The source index.html would go in the root folder. When building/serving, Jekyll will copy and process (if it has YAML front-matter) the source index.html and place the result in the _site folder.

   index.html <-- edit this file
      index.html <-- don't edit! Overwritten with every build!

At the end of step 2 in the tutorial, your index.html should look like this, with (empty) YAML front-matter and downcase filter:

# front matter tells Jekyll to process Liquid
<!doctype html>
    <meta charset="utf-8">
    <h1>{{ "Hello World!" | downcase }}</h1>

That’s how I’ve done it so far, yet it doesn’t place the source index.html file I’ve placed at root level in the _site folder when serving/building, only the default “Welcome” one. My folder structure seems to mimic the one you suggested.

And my index.html file contains exactly what you wrote, yet no liquid rendering.

To repeat, I use the

jekyll serve -s [root folder] -d [_site folder]

command to do this.

Thanks so far.

With the tutorial, you should only see “Hello World”, not “Welcome”. If you’re seeing “Welcome to Jekyll”, then maybe you’ve run the jekyll new command at some point? The jekyll new command initializes the source directory to use the Minima theme with a Markdown index file ( and some dummy pages/posts. The “Step by Step Tutorial” doesn’t use jekyll new.

In case it is useful, here are the commands I ran to follow the tutorial step 1 (with just an abbreviated index.html):

mkdir myproj
cd myproj
bundle init
chmod +w Gemfile # not sure why Gemfile is created read-only
echo 'gem "jekyll"' >> Gemfile 
bundle install
echo '<h1>Hello World</h1>' > index.html
bundle exec jekyll serve

At this point you should be able to edit myproj/index.html and Jekyll will rebuild when you save, and you can see the change by reloading in the browser. E.g. change “Hello World” to “Hello Universe” and observe the change.

It isn’t clear in the tutorial, but all Jekyll command should be run in the myproj folder, and should be prefixed with bundle exec. This ensures that the correct Jekyll gems are used for the project. When following the tutorial, you shouldn’t need to use -s and -d because Jekyll automatically uses the current directory as the source, and ./_site as the destination. So, the Jekyll serve command should be run as:

bundle exec jekyll serve

make sure you don’t have both and index.html in the root/src folder. You can only have one - if there are more than one they will over write each other in the _site folder.

1 Like

@chuckhoupt that did the trick. I think I used the j"ekyll new" command at some point. Very helpful, thanks.

@rdyar I did happen to have that in the folder. Deleted everything and started over.

1 Like