TheProjectsGuy Welcomes You

My personal webpage available at theprojectsguy.github.io, built using the al-folio theme. The original readme is in README.original.md.

Table of Contents

• TheProjectsGuy Welcomes You
  • Table of Contents
  • Setup
    • Adding Social Integration
    • Enabling mermaid diagrams
    • Enabling Disqus
    • Creating Pages
    • Minor Additions
      • Email Scrambler
      • Clustrmaps Visitor Count
  • Local Deployment
  • References

Setup

Steps to create this website (first build)

1. Fork the al-folio theme as TheProjectsGuy.github.io.

2. Setup Jekyll using these instructions

3. Clone and see the webpage on local system. This is same as step 4 and beyond from here

   git clone https://github.com/TheProjectsGuy/TheProjectsGuy.github.io.git
   cd TheProjectsGuy.github.io
   # Recompile and check results at localhost:4000
   bundle install
   bundle exec jekyll serve

4. Set up the GitHub build pipeline

   1. In _config.yml, set the following

      url: https://TheProjectsGuy.github.io # the base hostname & protocol for your site
      baseurl: # the subpath of your site, e.g. /blog/

   2. Recompile the site and check the results (on local system). Push the changes to the repository (the page may not build yet)

   3. On GitHub, set the Settings > Pages > Branch to gh-pages

   4. Push some new changes (or wait for the site to rebuild)

5. Set up the branch and this file

   cd TheProjectsGuy.github.io
   git checkout -b main
   git checkout -b archive
   mv ./README.md ./README.original.md
   touch README.md
   git add --all
   git commit -m "Added separate README"
   git push origin -u main

6. Change default branch to main and delete the master branch (local and github). Keep archive as a local backup branch (do not deploy its build)

   Whenever you want to debug the original website, check the archive build

   git checkout archive
   bundle exec jekll serve

   Optionally, push archive to GitHub and add a read-only branch protection rule. You may also delete master in remote and local repository.

Adding Social Integration

1. Choose the profile logo from fontawesome brands search (there are also academicons, but we'll use fontawesome here). I'm choosing GoodReads fa-goodreads for this.

2. Go to the social media site and get the identifier for your profile in URL

   For example, on goodreads, go to your profile link. Mine looks like this (either of the following)

   https://www.goodreads.com/user/show/127374683-avneesh
   https://www.goodreads.com/user/show/127374683

   My identifier is 127374683 (which, with the URL can give my profile)

3. Add the entry to _config.yml file, under Social integration

   goodreads_id: 127374683 # Your goodreads URL ID

   Make sure the key goodreads_id is unique.

4. In _includes/social.html, at the desired place, add the following

   {%- if site.goodreads_id -%}
   <a href="https://www.goodreads.com/user/show/{{ site.goodreads_id }}" title="GoodReads"><i class="fab fa-goodreads"></i></a>
   {% endif %}

   The href section requires the URL template. The site gets the contents of the YML file in the build.

5. Rebuild the site and refresh the browser

   # Recompile and check results at localhost:4000
   bundle install
   bundle exec jekyll serve

Enabling mermaid diagrams

1. Install nodejs and npm from here

   sudo apt update
   sudo apt install nodejs npm

2. Set the permissions for npm to use paths in home. These are borrowed from here

   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export NPM_CONFIG_PREFIX=~/.npm-global' >> ~/.zshrc
   echo 'export PATH=$PATH:${NPM_CONFIG_PREFIX}/bin' >> ~/.zshrc

   This will set the ~/.npm-global folder as the library folder for npm.

3. Install the mermaid.cli package

   npm install -g mermaid.cli

4. Add the following code changes

   • In Gemfile, make sure the following are there in group :jekyll_plugins

     gem 'jekyll-diagrams'
     gem 'asciidoctor-diagram'

   • In _config.yml, the plugins should include jekyll-diagrams

   • There can also be a blank setting jekyll-diagrams: for the diagrams settings

5. Rebuild the site and test on local system

   bundle install
   bundle exec jekyll serve

Enabling Disqus

By default, the comments blog page won't have comments rendered. Do the following

1. Go to https://disqus.com/ and create an account (click on Get Started)

   I'm using the Basic plan (free with ads) and the website name is theprojectsguy (this page's name)

2. When choosing platform for your site, choose Universal Code (at the bottom). You do not need to modify anything, the layout already includes code for disqus.

3. Set the disqus_shortname in _config.yml (you may have to uncomment it).

4. Rebuild the site

   bundle install
   bundle exec jekyll serve
   # Site on localhost:4000

5. Go to the template post with comments and you should now see the comments

Creating Pages

Creating another page (under dropdown options). Assuming a gists page here.

1. Create page under _pages/gists.md with the following header

   ---
   layout: page
   permalink: /gists/
   title: Gists
   description: Code snippets I have created to ease my developer life.
   ---

2. In _pages/drapdown.md, add the following to the children

       - title: divider
       - title: Gists
       permalink: /gists/

3. Rebuild the site and the dropdown should contain the contents of the gists.md file.

Minor Additions

Some minor additions to the webpage I got from others

Email Scrambler

In the about.md page, add your email address under profile > email section (in header of page).

Thanks to Jeff Donahue for the JavaScript starter code and Nikhil Varma Keetha's Webpage for the initial idea and implementation.

Clustrmaps Visitor Count

Note: Somehow, this doesn't show up on desktop, but works on mobile.

In the _config.yml file, set the clustrmaps_id. The ID is what comes after the ?d= and before the &. For example

• Map widget installation: <script type="text/javascript" id="clustrmaps" src="//clustrmaps.com/map_v2.js?d=mlKjqTzZ5b9aPWdkGGd6Rw3GHVjb8RBn3kF7whYf6i0&cl=ffffff&w=a"></script> means mlKjqTzZ5b9aPWdkGGd6Rw3GHVjb8RBn3kF7whYf6i0
• Globe widget installation: <script type="text/javascript" id="clstr_globe" src="//clustrmaps.com/globe.js?d=mlKjqTzZ5b9aPWdkGGd6Rw3GHVjb8RBn3kF7whYf6i0"></script> means mlKjqTzZ5b9aPWdkGGd6Rw3GHVjb8RBn3kF7whYf6i0

Set the theme to "map" or "global" in the variable clustrmaps_theme (in the same file).

Local Deployment

For testing changes before pushing them. Run commands under this in the repository folder.

# Install packages (if the Gemfile has been changed)
bundle install
# Serve website on localhost:4000
bundle exec jekyll serve

References

• jekyll on ruby
  • Ruby 101
• GitHub pages
• Liquid Documentation
• Template: alshedivat.github.io/al-folio/
• Distill blogs
• jekyll-diagrams
  • mermaid
  • mermaid.live interactive online editor
• disqus
  • How to Install Disqus Manually Using the Universal Code: But we won't have to do much of this