Quick Spinup of my Github Pages

This post explains how I spined-up my Github Pages in < 1 hour

Notes #

• GitHub Pages is basically a website with its code can be found in a GitHub repository specific to your account (<your username>.github.io, the same name as your GitHub Pages website’s domain)
• The basic flow for publishing would be:
  1. I push new commits to the repo (the publishing branch)
  2. GitHub Action process the files with Jekyll
  3. The Jekyll process generated the statis assets
  4. GitHub serves those assets on the GitHub Pages website.
• It turns out that GitHub Pages by default is like a static file server. I.e. whatever files that is processed by the Jekyll process will be generated as public assets. So basically whatever is processed, you have it publicly accessible.
  • E.g. I have a directory called ubuntu in the repo’s root directory, and the file ubuntu/my-setup.md. Then after build, I will have a file available at /ubuntu/my-setup.html. Note that Jekyll will process every markdown files to generate its HTML version.

Steps #

Create GitHub repo #

Create a public repo named <your username>.github.io. E.g. my username is bloomingseed then the required repo name is bloomingseed.github.io.

Configure a publishing source for the GitHub Pages site #

• Go to the GitHub Pages setting of the repo
• Check that the source is set to “Deploy from a branch”
• Configure the branch to deploy code and the root folder to serve the site. Notes:
  • Initially, we would serve in root folder of master branch of the home repo (the repo with its name same as the site domain)
  • But GitHub Pages can also serve from any other repos. The result of it is the repo’s Pages can be found at /<repo name>/<repo's root Pages folder>
  • Since in other repos, you may not want to throw the GitHub Pages files in the project’s root folder. It may even mess with your Gemfile if your project is Ruby one.
  • Thus you may want to change the serving directory to something else and accept that the project’s Pages URL would be /<repo name>/<root dir>

Serve locally #

Clone the repo to local #

• Use git clone <repo url> to download the project.
• And current change directory into it.

Install ruby if not already did #

• Install rvm
• Install ruby 3.1.1: rvm install 3.1.1

Install jekyll (and bundler if not already did) #

• Install gems: gem install jekyll bundler (from the Jekyll docs)

Init jekyll #

• jekyll new --skip-bundle -f . inside the project root directory. Notes
  • --skip-bundle means after init jekyll, don’t run bundle install, because we want to modify the Gemfile first.
  • -f means in case your repo is already a GitHub Pages (or have any conflicting file) then override all the conflicting files (i.e. _config.yaml, Gemfile, Gemfile.lock, and other files that would be generated by jekyll new)

Replace gem jekyll with gem github-pages #

• Since we are running Jekyll with GitHub Pages, GitHub has provided a special gem github-pages that is their Jekyll version that is used when generating our GitHub Page site.
  • I.e. If we are only using Jekyll without GitHub Pages, then use gem jekyll as generated.
  • To do that, edit the Gemfile, replace the line gem "jekyll" with gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins Notes:
  • GITHUB-PAGES-VERSION is the gem github-pages’ version number found at GitHub’s provided Dependency versions.
  • E.g. If their Dependecy versions say github-pages version is 227 then our line would be gem "github-pages", "~> 227", group: :jekyll_plugins.

Serve the site #

• jekyll serve, or bundle exec jekyll serve, or jekyll s. Notes:
  • This command can hot reload by default

Configure a theme #

• Choose a theme from list of jekyll-theme gems
• Add the gem to Gemfile, along with the version
• Set theme to the gem name.

Start making contents #

• How posts work:
  • Posts are any piece of writing you do on a specific date.
    • E.g. a tutorial post, a sharing post, any random writing (diary, blog, …)
  • In Jekyll, you create post by writing to a file named in format YYYY-mm-dd-<post-name>.(md|html) and put inside the folder _posts.
  • The content of a post can be in Markdown or HTML format. It can contain Front Matter too.
  • When a post is created, remember that it’s inside a folder whose name starts with underscore, they won’t be available as _posts/<post name>.html, but will be available at /YYYY/mm/dd/<post name>.html
  • When a post’s Front Matter declares some categories, those categories are put first, in correct order, then comes the URL above.
• Since Jekyll can be a simple static file server, I can simply create contents anywhere, any folder and when processed, it will be available the same path they were.
• There are a lot of features of Jekyll you can use, as well as a lot of features that you want to add to your site. You can browse the Intenet for the tutorial and continue making content here.

Commit changes and deploy #

• Commit changes
• Push code to the publishing branch
• Wait for GitHub Pages to finish
• Go to URL <username>.github.io to check. It should be identical to your local site.