Jekyll Github Pages Website

This is my personal guide related to all about making github pages with and without jekyll.

1. Github pages website (without jekyll + only markdown files)

• Reference Repo: this
• Reference Website: this
• It contains no themes, no extra github pages features, etc. Just the simplest form of github pages website.
• Process:
  1. Initialise a repo
  2. Add a readme and any other markdown files that you want to put.
  3. Go to settings tab of repo, pages sections, these choose main branch and root directory. In sometime the website url will apear in the current page (just reload after a while)
• Features:
  1. Allows normal features of markdown files: links, markdown syntax etc
  2. No themes, automatic navbar, etc

2. Github pages website (with jekyll theme + only markdown files)

• Reference Repo: this
• Reference Website: this
• Process:
  1. Steps 1 to 3 same as above
  2. Add a _config.yml file which contains a theme supported by github and other configuration respective to that theme provide its repo.
• Features:
  1. Allows normal features of markdown files: links, markdown syntax etc
  2. Github supported themes and any features respective to that theme alone (no custom configurations outside of what that theme can provide)

3. Autogenerated Github pages website ( with jekyll theme + markdown + html files)

• Reference Repo: this
• Reference Website: this
• Pre-requisites:
  • Ruby installed (For windows - https://rubyinstaller.org/downloads/), the one with devkit
  • Jekyll and bundler installed - gem install jekyll bundler
• Process:
  • Creating webpage: run jekyll new my-site
  • Running webpage locally: run bundle exec jekyll serve
  • Running webpage with github: push to repo and setup github pages via settings (as point 3 in here)
• Features:
  1. Neccessary markdown and html files, Gemfile with predefined gems, _config.yml with preset configurations and theme.
  2. Just have to add more markdown files into _posts folder to add more posts to the website. Everything else is autogenerated

4. Github pages website from scratch (with jekyll + markdown + html files + github pages workflows)

• Reference Repo: this
• Reference Website: this
• Pre-requisites:
  • Ruby installed (For windows - https://rubyinstaller.org/downloads/), the one with devkit
  • jekyll and bundler installed - gem install jekyll bundler
• Process:
  • Create a _config.yml
  • For properties, visit https://json.schemastore.org/jekyll.json. In that go to the key called properties and under it every key is a possible property that can be added to the config file.
  • For default properties specific to any particular theme or website template, visit that template and read its documentation or code base to identiy what variables are used in its code.
  • Finding variables :
  • 
  • 
  • We will be using architect theme from https://github.com/pages-themes/architect. I'll just go ahead and copy info from its _config.yml
  • Create a file called Gemfile
  • Its like package.json but for ruby. It contains gems (packages for installation)
  • In it add necessary gems for jekyll, and those related to the respective theme/template. (example)
  • Bundle the gemfile by running bundle install or just bundle
  • Create a file called .gitignore specific to jekyll, automatically by running npx gitignore jekyll
  • Adding files:
  • Add a readme file that acts a starting point
  • Add additonal frontmatter to any post or page that you make. (example)
  • Add custom markdown pages [optional]. (example)
  • Add custom html pages [optional]. (example)
• Running:
  • Running webpage locally: run bundle exec jekyll serve
  • Running webpage with github: push to repo and setup github pages via settings

5. Github pages website from scratch (with jekyll + markdown + html files + custom github workflows)

• Reference Repo: this
• Reference Website: This current blog website
• Process:
  • Every thing same as 4, but we will build our own workflow.
  • This is required when we make any changes in jekyll core code, because github-pages gem do not consider any changes that is made in jekyll core code like this. So we make our own github workflow.
• Github Workflow:
  • Add a folder named .github, within which you add another folder workflows, within which you add a file named jekyll.yml
  • In that file you add the following code
• Running:
  • Same as 4
  • Running webpage locally: run bundle exec jekyll serve
  • Running webpage with github: push to repo and setup github pages via settings

◈ Additional Notes:

• List of starter file of some simple and pretty github pages websites:

  • https://github.com/cotes2020/chirpy-starter
  • https://github.com/jekyll/minima/tree/v2.5.2
  • https://github.com/jsanz/gh-pages-minima-starter
  • https://github.com/alshedivat/al-folio

• Some other references for github pages website setup:

  • https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml
  • https://opensource.com/article/21/11/jekyll-config-files
  • https://nainagurung.medium.com/publish-github-pages-using-jekyll-369a8e2800b7