Questions about Jekyll and GitHub Pages (folder structure and other questions)

I’m thoroughly new at Jekyll, so I’d like to ask you some specific questions.

  1. I’m hosting my page (a personal one) at GitHub Pages. Can I deploy single page web app, let’s say a weather app connected to external APIs, in that hosting service using Jekyll? My thinking is that is possible, but I’d like to know if anyone knows something about this I should consider.

  2. What’s the best folder structure I can use at GitHub Pages? When I use the command Jekyll new my-site I get this template as a result:


Is there anything else I need for that hosting? Or for any Jekyll project for that matter really. I’m a little confuse about what’s the best folder structure I can use for my site, and where should I place my scripts (Javascript) and styling (sass, and css).

  1. I’ve seen some projects at GitHub pages where the files are stored at inside a secondary branch, usually named gh-pages. Do they do that just for keeping the code from the project repo separated from the code that belongs to their GitHub site?

  2. When deploying the site, I know that the files I’m going to use are sent to the _site folder, by default. Are these the files that I’m going to publish in the server? For any Jekyll project. What’s the workflow I have to follow. On the other hand, I’ve know that any compilation and deployment at GitHub Pages is made from the remote repository. Any comments on this?

  3. What dependencies for Jekyll can I use at GitHub Pages? Where’s their documentation? I remember reading somewhere about this, but I lost track where it was that I did so.

Answering your questions point by point

  1. Jekyll is a static site generator. If you want to display the weather based on a visitor’s location you probably want to use a dynamic site generator instead.

  2. The javascript and CSS is kept under the assets directory as you can see here from my Jekyll website:

    $ tree --dirsfirst --filelimit 20
    ├── assets
    │   ├── css
    │   │   └── style.scss
    │   ├── img
    │   │   ├── ask_ubuntu.png
    │   │   ├── Ask Ubuntu profile.png
    │   │   ├── Blog_Project-Management-101.png
    │   │   ├── earth-from-space.jpg
    │   │   ├── Edm Temperature December 7, 2021.png
    │   │   ├── github pages themes.png
    │   │   ├── Inspectocadt.jpeg
    │   │   ├── Jekyll.png
    │   │   ├── octojekyll-opt.jpg
    │   │   ├── Pippim Post More Button Working.gif
    │   │   └──
    │   └── js
    │       ├── copyCode.js
    │       └── post_fm.js
    ├── _includes
    │   ├── copyHeader.html
    │   ├── head-custom.html
    │   ├── image.html
    │   ├── posts_by_tag.html
    │   ├── posts_by_vote.html
    │   └──
    ├── _layouts
    │   ├── default.html
    │   └── post.html
    ├── _plugins
    │   └── insert_git_code.rb
    ├── _posts
    │   ├── 2016 [183 entries exceeds filelimit, not opening dir]
    │   ├── 2017 [163 entries exceeds filelimit, not opening dir]
    │   ├── 2018 [448 entries exceeds filelimit, not opening dir]
    │   ├── 2019 [269 entries exceeds filelimit, not opening dir]
    │   ├── 2020 [72 entries exceeds filelimit, not opening dir]
    │   └── 2021 [36 entries exceeds filelimit, not opening dir]
    ├── _sass
    │   ├── jekyll-theme-cayman.scss
    │   └── toc.scss
    ├── sede
    │   ├── QueryResults.csv
    │   ├──
    │   ├── StackQuery
    │   └──
    ├── _config.yml
    ├── LICENSE
    15 directories, 36 files
  3. I’m not sure of putting your website in a place other than <YOUR_NAME>

  4. I don’t know about publishing to _site directory directly. It is all automatically updated whenever I change a file in the repo. In about 2 minutes (it used to be 20 seconds with only a few files) GitHub Pages rebuilds the website to _site.

  5. Here is the Jekyll Documentation


Feel free to visit the home page of my website linked above for methods to programmatically publish third party website data into your own website. For example the 1,200 blog posts on the Pippim Website were actually written on the Stack Exchange Website and converted into Jekyll Format.

Jekyll only runs while it is generating / building a site.
A web app on the other hand needs a constantly running program to render real-time state.

Jekyll is configurable. So, you’re free to customize the folder structure.
Refer Directory Structure | Jekyll • Simple, blog-aware, static sites and Default Configuration | Jekyll • Simple, blog-aware, static sites for details.

You’ll need a CNAME file if you need to set up a custom domain. Regardless refer GitHub Pages | Jekyll • Simple, blog-aware, static sites for helpful tips.

Firstly, this site would be accessible at `
Secondly, in majority of the cases, it is not to separate project code from GitHub site code. The repository is an entirely different project and not necessarily a Jekyll site source.

That said, at times you may see different code in a main branch and gh-pages branch.
In such cases, gh-pages is for all intents and purposes, the generated HTML files served by GitHub.

You have two choices. Either have GitHub Pages build and deploy your Jekyll site. Or you build the site locally at your end and have GitHub Pages deploy / serve your generated contents. In the latter case, yes, you have to commit and push the contents of the _site.

See Dependency versions | GitHub Pages