Problems installing and modifying a theme


I’m a total newbie when it comes to Jekyll. I have to say I like the idea behind it - how to use liquid, layouts, includes and data files. After reading the tutorial to install and create a few simple sites to try it out, I’m learning fast. The really nice thing is to develop on a local server machine and also that Jekyll is generating a final version in the _site folder ready to be uploaded to a web host.

I’ve encounter a big problem though, that sadly has dampen my enthusiasm a little bit. I’m probably doing something wrong or missing something, but what?
I find it very confusing trying to install the “Agency Jekyll Theme” which is my first theme I’m trying out. Mostly because there are several ways to do it, the commands doesn’t add up and there is a lot “you can do this” embedded into what you actually have to do to install it.

When I run command jekyll serve (in my site folder) it creates _site folder and in there content in the subfolders css, img and js.
But nothing else is created, not index.html and other files needed directly under _site folder.
In my site root folder, there is only _config.yml and Gemfile, after completing the initial steps.
There seem to be a problem to actually download the full theme into my root folder. Shouldn’t this be performed when running command gem install jekyll-agency and bundle (init)?

When I manually download the and extract the entire content in my root site folder, there is index.html, _data folder etc. However, in the assets folder there is only an img folder. Where does the css folder and its content come from that generates under _site?

As a result, when I open localhost:4000/agency-jekyll-theme-starter/ in a browser there is only a directory listing with the folder “assets

As a workaround, I’m running the command jekyll build so that the site in its entirety is placed under _site folder.
However, with this process the whole point of using Jekyll is lost because I have to edit the generated html files, and css files etc. To change simple stuff like renaming the page/navigation “Services” to another word I have to go through the html file and replace all occurrences

These are the guides I’ve been following:

Basically I’ve tried all the 3 possible ways to install, without success.

I’m running on Windows.

Thanks in advance for any response!

As with pretty much any theme for any technology, you are going to be held to how the designer created the template. For example, they might use older technology or plugins GitHub Pages does not support, so please be aware if you are not building it for yourself, there is some risk in using a custom-built theme.

:gem: Gem-based themes

I did go to this page to see the installation instructions for Agency. Those steps to create a new blank site will create a Gem-based theme. You can think of it like this: You will never see the theme… Jekyll will get the details for the theme when it builds or serves your site, but you cannot modify them.

If you want to see and have access to the theme files so you can learn from it or modify the files, then you follow these steps to “override” the theme, which essentially means you will see all the theme files.

Themes vs. content

Depending on the developer, a theme might just include styles and formatting. You then have to create the content based on that.

:+1: Solution for what I think you are looking for

I went through the steps to get the entire website up and running. Here are the resultant screenshots from my local browser and VS Code:

Get the starter template

  1. Go to the Agency starter template:

  2. Select the Use this template option and then select Create a new repository

  3. You will now have your very own GitHub repo that contains a fully functional Agency-themed website with index and other files. Go to the settings for your repo and enable GitHub Actions to deploy from the master branch (you can rename it to main if you like, but currently it is set to master) and the /root folder

  4. Test out the new site to make sure it works by using your [githubusername][reponame]. In my case, it is:
    (note: no gaurantees this will be up and running. I will likely delete the repo)

  5. On your local computer, git clone your newly created repo

  6. Open the _config.yml file and modify the url and baseurl settings. In my case, the settings are as follows:

url    : "" # the base hostname & protocol for your site, e.g.
baseurl: "/agency-theme-test" # the subpath of your site, e.g. /blog
  1. After you save the _config.yml file, I recommend you install and update your bundle (which may or may not be required, but it is a force of habit for me):
bundle install
bundle update
  1. Run your site for the first time by typing:
`bundle exec jekyll serve --livereload`
  1. You can then go to the URL and test your site locally as you make changes

  2. When you are happy with your changes, commit and push them back up to your repo. Sometimes it takes a few minutes (or a few long minutes) to publish and then you can see your changes on GitHub Pages

Hope that helps!

Thank you enormously BillRaymond!

I have, in some unexplained way, managed to get my site with the Agency theme running locally.
However, there is something that is still not right. I extracted all the files from the biggest zip file of the theme, which seem to cover all files.

First I must point out that I’m not using github at all for my site. Using only local resources on my Windows machine (afaik), and I’m developing by browsing http://localhost:4000.

I get this warning in my command prompt:

       Jekyll Feed: Generating feed for posts
          Conflict: The following destination is shared by multiple files.
                    The written file may end up with unexpected contents.
                     - assets/css/agency.scss
                     - C:/web/assets/css/agency.css

                    ...done in 0.1660095 seconds.

This creates a strange behaviour however. I run these commands:
bundle update
bundle exec jekyll serve

… The site works perfectly, until I make some changes which make the style of the page go bananas. I assume it has to do with the warning of the css file. It’s like it reverts back to some default css and my latest changes won’t show.

When running the serve command everything auto-updates anyway. The css warning conflict never goes away though.

And when looking at my _confg.yml file I get confused.
I could run any of these lines and it will work:
theme: raviriley/agency-jekyll-theme
remote_theme: raviriley/agency-jekyll-theme

And I can also comment they both, and it will work.
I’m still confused in general how jekyll works and what might have happen in my case.

Hope someone can help me solve the conflict thing?

These types of issues where you make a change and then the site reverts usually occur when you are modifying the files in the _site folder rather than the root folder (think of the _site folder as a hands-off zone because that is the destination where Jekyll builds your site). I have done this many times not even thinking about it and I know better :slight_smile:

Hope that helps

I think you may have 2 agency css files? inside assets/css ? one is .css and the other is .scss? if so that is bad as the scss one will end up as .css and one will over write the other.

1 Like