Set Up My Website via github.io

Documentation of how this website was made and its growth. :)

1. Copy Website Template and Host on GitHub

For every personal github account, you can host a website for free at https://[your GitHub username].github.io. For my website (the one you’re looking at) it’s https://gr-grey.github.io.

• Fork Academicpages GitHub Pages Template
  • The template comes from https://github.com/academicpages/academicpages.github.io.
  • Fork to get my own copy to have fun with.
• Host on GitHub
  • Go to my github page, rename the repo from “academicpages.github.io” to “gr-grey.github.io”
  • The website should be live at “https://gr-grey.github.io” (might take a minute for github to compile things).
  • At first, it should look exactly like https://academicpages.github.io/ (since it’s a copy).
  • It comes with many useful guidance of website formats and markdowns in general. Look around and explore!

2. Host Locally for Better Development Experience.

To avoid waiting for ages to see the changes after pushing to GitHub. It’s a good idea to serve the website locally. So I can mess around and immediately know what I broke.

• Instructions can be found in the README pages of the template.
• The website is served in WSL2 environment with these commands

sudo apt install ruby-dev ruby-bundler nodejs
sudo apt-get install -y build-essential
bundle install
bundle exec jekyll serve

• The site can be accessed at http://localhost:4000, or http://127.0.0.1:4000.

• Notes
  • bundle exec jekyll serve is needed for first time serving. Afterwards run jekyll serve to serve the website locally.
  • 2023-03-29 debug log when setting local server on a new machine.
    • bundle install had error “Gem::Ext::BuildError: ERROR: Failed to build gem native extension.”, solved by sudo apt-get install -y build-essential according to StackOverflow.
    • bundle exec jekyll serve had error /var/lib/gems/3.0.0/gems/jekyll-3.9.2/lib/jekyll/commands/serve/servlet.rb:3:in require\': cannot load such file -- webrick (LoadError), it seems to be a compatiblity issue, that ruby 3.0 requires the “webrick” package, solved by running bundle add webrick according to StackOverflow. It added “gem “webrick”, “~> 1.8”” to Gemfile and Gemfile.loc, these changes were commited, so future bundle install would install webrick.
• Extra Notes (for me)
  • Added alias jgrep="grep --exclude-dir=_site -r" to my zshrc, as I found myself grep excluding the _site folder too many times.
  • Added .jekyll-metadata to .gitignore as local server created that.

Mac environment

I have an old MacBook Air 2015 that I occasionally use. Setup date: 2023-03-31; OS version: Mojave 10.14.6

Set up

Get repo -> install ruby 3.2 and add to system PATH -> install jekyll & bundler -> bundle install -> serve locally

brew install ruby
export PATH="/usr/local/opt/ruby/bin:$PATH"
ruby -v # should be > 3.2
sudo gem install jekyll bundler
bundle install
bundle exec jekyll serve # need to run once, only "jekyll serve" after that

Troubleshooting and notes

• brew install ruby took more than 3 hrs for my old laptop
• after installing ruby, need to explore to PATH variable
  • before exporting, ruby -v shows 2.3.7 - default version from OS, after exporting, version should be > 3.2
• bundle exec jekyll serve had an error message:

Liquid Exception: undefined method `tainted?' for "http://localhost:4000":String in /_layouts/single.html

According to this github pages issue, it’s because liquid 4.0.3 is not compatible with ruby 3.2, need to bump up the version to liquid 4.0.4.

Running bundle update seems to solve the problem, it modified “Gemfile.lock” with a bunch of changes, one of them is changing the version of liquid to 4.0.4. The new Gemfile.lock was committed, the liquid version should be fine for now.

Extra notes from installing ruby:

By default, binaries installed by gem will be placed into:
  /usr/local/lib/ruby/gems/3.2.0/bin

You may want to add this to your PATH.

ruby is keg-only, which means it was not symlinked into /usr/local,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.

If you need to have ruby first in your PATH, run:
  echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

For compilers to find ruby you may need to set:
  export LDFLAGS="-L/usr/local/opt/ruby/lib"
  export CPPFLAGS="-I/usr/local/opt/ruby/include"

For pkg-config to find ruby you may need to set:
  export PKG_CONFIG_PATH="/usr/local/opt/ruby/lib/pkgconfig"

3. Fill in Infos

• The “_config.yml” field contains basic info such as site name, your name, url, email, twitter, linkedin and so on
• Modified “_includes/author-profile.html”: changed site.data.ui-text[site.locale].email_label to author.email; as I found explicitly displaying the email address on the left side bar is more useful than saying “Email”.

4. Navigation Bar & Structual Changes

• Navigation buttons are set in the “_data/navigation.yml” file
• Restructure my naviation bars to CV > Publication > NGS > Courses > Blogs > Dev-log
• Comment out ones I don’t need
• NGS column
  • Add NGS title and /ngs/ url in navigation.yml file
  • Create “_pages/ngs.md” Note that permalink needs to match with the \ngs\ url.
• Dev Logs column
  • Add Dev Log title and /dev-logs/ url in navigation.yml file
  • Create “_devlogs” folder to store articles in this catogory
  • In the “_config.yml” file, add “devlogs” entry to both “collections:” and “defaults:” fields (or else site.devlogs can’t fine the files in _devlogs folder);
  • Create “_pages/dev-log.html” . The file is based on Blogs page - “_pages/year-archive.html”, as it’ll display blogs of programming and development records.
    • Changed for post in site.posts to for post in site.devlogs reversed to load files in the _devlogs folder, and for newer dates to show up first.
  • Write up this post “_devlogs/2023-01-30-github-io.md”, with collection: devlogs in the front matter.
• Courses column - parallel operations to Dev Logs
  • Add Courses title and /courses/ url in navigation.yml file
  • Create “_courses” folder to store articles in this catogory
  • In the “_config.yml” file, add “courses” entry to both “collections:” and “defaults:” fields (or else site.courses can’t fine the files in _courses folder);
  • Create “_pages/courses.html” . The file is based on Blogs page - “_pages/year-archive.html”, as it’ll display blogs of programming and development records.
    • Changed for post in site.posts to for post in site.courses reversed to load files in the _courses folder, and for newer dates to show up first.
  • Creat “_courses/2023-01-31-introduction-to-genomics.md” file, with collection: courses in the front matter.
• NGS page links to courses. E.g. [Introduction to Genomics](/courses/2023/01/introduction-to-genomics/)

5. Dev and Maintenance

• 2023-01-31
  • Format: increase font size of code block, in “_sass/_syntax.scss” , font size was set by .highlight{font-size: .8125em; /* was $type-size-7 */} . Solution found from this issue of the original repo.
  • Format / Bug Fix: in the same syntax.scss file, changed “fontawesome” to “Font Awesome 5 Free”, to fix the \f121 symbol problem, mentioned in issue above.
• 2023-02-01
  • Remove blogs came with the template. Post The Sunscreen Song.
• 2023-02-02
  • Format: remove post.paperurl links in archive-single.html and single.html
  • Structure change: replace Publications with Research in navigation bar, have CV and front page point to research details on that page.
• 2023-02-03
  • Format: add doi to the line of “Published in” on research page. Done by creating a “doi” variable in the front matter of each publication’s markdown file, and change the archive-single.html

            
      {% elsif post.collection == 'publications' and post.doi %}
      <p>Published in <i>{{ post.venue }}</i>, {{ post.date | default: "1900-01-01" | date: "%Y" }}, {{ post.doi }} </p>
            
    

• 2023-03-06
  • Post: Introduction to Genomics under Course column.
• 2023-04-16
  • Format: adjust banner to each post
    • in “_sass/_pages.scss” add code block

        .wrapper2 {
          padding-left: 1em;
          padding-right: 1em;
          @include breakpoint($large) {
            max-width: $large;
          }
          margin: 0 auto;
        }
      
        # did not ended up using this
        .page__hero-image2 {
          width: auto;
          height: auto;
          -ms-interpolation-mode: bicubic;
        }
      

    • “_include/page__hero.html” change <div class="wrapper"> to <div class="wrapper2">
    • for each blog, set banner by configuring header in the frontmatter

        header:
          overlay_color: black
          overlay_image: /banners/2023-04-05-huberman-elissa-epel-banner.png
      

    • Note that the banner folder is under images, but the images path is omitted
    • Make sure the banner file has enough width, or it will be streched to the entire screen
• 2023-05-20
  • Format: further adjust banner, shrink the width
    • in “_sass/_pages.scss” in class .page__hero &–overlay

      // shrink width
      max-width: $large; 
      // put the session in middle
      margin: auto auto; 
      

    • “_include/page__hero.html” change <img src="" alt="Set Up My Website via github.io" class="page__hero-image2"> to <img src="" alt="Set Up My Website via github.io" class="page__hero-image">
    • in “_sass/_pages.scss” in class .page__hero-image2, change from height: auto to height: 100%;, though seem to have no effect
    • Source Limiting hero-image max width?
    • Source make header image narrower

6. To Do

• for posts/blogs, add TOC to the left for quickly jumping around in the article.
• Add description to each paper in excerpt (front matter).
• Dark mode, Gruvbox theme?
• Copy button for code block