2 of 43

Intro & Agenda

Hi, I’m Lauren!

Healthcare tech Data Scientist based in Columbus, Ohio
Director of Operations of Women in Analytics
Member of the scikit-learn Communications Team

Agenda

Jekyll/GitHub Pages Background
Creating Your Site
Hosting on GitHub Pages
Customization Options

3 of 43

Background

Section 1

4 of 43

Why Create a Personal Website/Blog?

Establish a Personal Brand

More customizable than a resume, GitHub, or LinkedIn profile.
Greater control to display the most relevant and important content to viewers.

Build a Portfolio

Showcase projects and work samples that serve as a direct representation of your skillset.

Gain Visibility

Increase discoverability to potential employers and collaborators.
Easier for others to contact you about opportunities.

Showcase Your Accomplishments

A space for you to promote yourself! E.g., community impact, awards, speaking engagements

Share Knowledge

A place for you to publish information or tutorials that can help others in your field!

5 of 43

Jekyll

Ruby-based static site generator

Static site generators build HTML sites from provided files & page templates

Offers:

Built-in support for GitHub Pages
Simple build process

Supports:

Markdown
Liquid for dynamic content

GitHub Pages

Static site hosting service
Host your site directly from GitHub, for free
Supports HTML/CSS/JavaScript
Option to host your site via the free github.io domain or a custom domain

What are Jekyll & GitHub Pages?

6 of 43

Why use Jekyll/GitHub Pages?

Jekyll

Static sites are simpler, faster, more secure and more flexible compared to dynamic sites like Wordpress or Drupal
Incremental build reduces the overall build time

GitHub Pages

Free hosting

Includes one free domain at <username>.github.io

GitHub has version control to keep track of changes

GitHub allows for user collaboration

7 of 43

Creating Your Site

Section 2

8 of 43

Prerequisites

To get started, you will need to have:

Basic command line skills
Basic knowledge of HTML/CSS languages
A GitHub account

9 of 43

Getting Started

Option 1: Use a Template

Create a website by simply forking then cloning the repository of an existing template.

Ex. The popular Minimal Mistakes theme.

Option 2: Start from Scratch

We will be using this method!

10 of 43

Install Jekyll

1) Ensure Ruby is Installed

Jekyll is a Ruby gem. Gems are similar to plugins, but installed at system level instead

of application level.

Ruby is installed on Mac by default but will need to be installed on Windows machines.
In terminal, check if Ruby is installed using the command:

2) Install Bundler

Bundler is a package manager for Ruby gems.

3) Install Jekyll

gem install bundler

gem install jekyll

ruby -v

11 of 43

Create a New Jekyll Project

1) Navigate to the directory to hold your site.

I will be using: /Documents/Github/

2) Create a new Jekyll project in the current

directory using the jekyll new command:

In this case, I’ve created a new project named

myblog at path: /Documents/GitHub/myblog

3) Navigate into the newly created folder.

jekyll new myblog

cd myblog

cd Documents/Github

12 of 43

Run Your Site Locally

1) Install dependencies using the bundle install command:

2) Run your site locally:

bundle install

bundle exec jekyll serve

View your site at: http://127.0.0.1:4000/

Tip: Bundler may throw an “cannot load such file” error due to it missing certain required gems. If this occurs, run command bundle add MissingGemName then try to serve the site again.

13 of 43

What’s Inside the Project?

_config.yml: File containing site configuration variables like site name, description, URLs, author information, etc.

_posts: Folder containing site posts. Each post should be a Markdown file labeled in a YYYY-MM-DD-PostName.md format.

_site: Folder containing files that help compile the site. This folder is created when you serve the site for the first time.

about.md: A pre-created Markdown file of content to be published on the About page.

Gemfile: A file containing information on the site’s dependencies, including theme gems.

index.md: A pre-created Markdown file of content to be shown on the site’s home page.

14 of 43

Updating Site Configuration

1) Edit the _config.yml file in your project

directory to add information about

your site like the name, email,

description, and social links.

2) After saving the file, run the serve

command once again to view the

updates.

bundle exec jekyll serve

15 of 43

Hosting on �GitHub Pages

Section 3

16 of 43

Initialize the Repository

1) Within GitHub, create a new repository

with the name <username>.github.io.

Do not add any files!

git init

2) Back in your terminal, initialize the git repository in your project’s root directory.

17 of 43

Add the GitHub Pages Gem

1) Edit the Gemfile that Jekyll created in the project

folder. You can do so using any text editor.

Comment out the line with the jekyll gem, and

add the github-pages gem.

2) Then, update the Gemfile by running the

bundle update command.

bundle update

Tip: Bundler may throw an error when attempting to install the required jekyll-feed gem. If you run into this issue, delete the Gemfile.lock file then run bundle install.

18 of 43

Personal Access Tokens (PAT)

In 2020, GitHub changed their authentication process from password-based to token-based.

Personal Access Tokens

Alternative to using a password to authenticate when using the command line

Required to perform certain operations

This includes the remote operations we will be doing today!

19 of 43

Generating a PAT

Within GitHub, click on your profile icon then click Settings.
At the bottom of the left hand side menu, click Developer Settings.
At the bottom of left side menu, click Personal access tokens, then select Generate new token.
Enter a name for the token in the Note field, set an expiration date, select permissions, then click Generate token.
COPY YOUR TOKEN! You will not be able to view it again, so save it somewhere you can locate it later.

20 of 43

Push to GitHub

In terminal, use your PAT to set the remote GitHub repository.

git remote add origin https://<PERSONAL_ACCESS_TOKEN>@github.com/<username>/<username>.github.io.git

Add all changes and commit them.

git add .

git commit -m “Initial Commit”

git remote -v

git push origin master

Verify the remote repo.

Push the changes to the remote repo.

21 of 43

View on GitHub Pages

GitHub Actions

Under GitHub Actions, you can track the progress of the site build and deployment.

If the workflow throws an error, click into the build or deploy tabs to investigate the issue.

Deployment

Once pushed to GitHub, your site will begin to build automatically.

View your published site at: https://<username>.github.io

22 of 43

Customization�Options

Section 4

23 of 43

Theme

Section 4.1

24 of 43

Theme

Option 1: GitHub Pages offers a number of supported themes.

Switch to another supported theme by updating the theme variable in the _config.yml file.

Option 2: Use a remote theme. Here we will install Minimal Mistakes as a remote theme.

Update _config.yml

First, update the Gemfile to include the jekyll-include-cache gem and comment out the base theme.

Next, update the _config.yml file to reference the remote theme.

Finally, use bundle install to add any dependencies.

Update _config.yml

25 of 43

Viewing the Updated Theme

1) First, serve the site and view the

updates locally:

bundle exec jekyll serve

2) Then add, commit, and push

the changes to view the updated

theme on GitHub Pages.

26 of 43

Color Scheme

Change the color scheme by setting the minimal_mistakes_skin variable in the _config.yml file.

After making any changes to the site configuration, use bundle update followed by bundle exec jekyll serve to update the site.

Update theme in _config.yml

27 of 43

Posts & Pages

Section 4.2

28 of 43

Posts

By default, posts will be displayed on the home page sorted in order of more recent.

Update the default settings in _config.yml to display additional post stats like date, read time, etc.

29 of 43

Front Matter

Front matter, within the “---” borders, is where we set variables and metadata about our site’s pages and posts.

Page: Set the title, layout, permalink, featured image, link, sidebar
Post: Set the title, date, author, categories/tags, featured image, link

Ex. Post’s front matter

Ex. Page’s front matter

30 of 43

Pagination

Add the paginate gem to the Gemfile.

gem 'jekyll-paginate-v2', '~> 3.0’

Add the following code to the _config.yml file, setting the posts per page and path.

Also in the _config.yml file, add the paginate gem to the plugins list.

31 of 43

Pages

Create a _pages/ folder in the project directory.

Place new Markdown files named as pagename.md into the folder.

Update the page’s front matter to reflect the title, layout, and permalink.

In the _config.yml file, add _pages to the include list.

32 of 43

Menus & Navigation

Section 4.3

33 of 43

Site Author Profile

Add a site author profile by updating the _config.yml file.

Add an author variable and any relevant social links.

In _config.yml, add an author profile…. then update default format

Create an assets/images/ folder and place your avatar image inside.

Update the page/post formatting options in _config.yml to display the author_profile.

34 of 43

Site Footer

Add a footer to your site by updating the _config.yml file.

For each footer link, include the label name, icon, and URL.

Tip: Use the Font Awesome search to find available icons!

35 of 43

Navigation Options

Create a new file _data/navigation.yml in your project directory.

In the navigation.yml, file update the main menu variable with the list of revelant link labels and URLs.

Once enabled, the menu will automatically toggle to fit the screen.

36 of 43

Custom Sidebars

Option 1: Add sidebar to single page/post

Update the page/post’s front matter within the Markdown file.

Define new sidebars in /_data/navigation.yml
If the author_profile is enabled, the sidebar will display directly below it.

Add to navigation.yml

Option 2: Add to all pages/posts

Update the formatting defaults in the _config.yml file

37 of 43

Blog Settings

Section 4.4

38 of 43

Home Page Content

In the root of the project directory, locate the index.markdown file.

Use Markdown or HTML/CSS formatting to add text, images, and links to the section above “Recent Posts”.

39 of 43

Separate Blog Page

Create a new file /blog/index.html in the root directory. Set the layout as home.

Update the layout of the index.markdown file from “home” to another layout style.

If using pagination, update the paginate_path in _config.yml to /blog/page:num/

If you’d prefer to have a standard homepage, you can update the layout and display your blog on another page.

40 of 43

41 of 43

Adding Categories & Tags

Update _config.yml to include the archives and collections code shown below.

In the Gemfile, add gem "jekyll-archives”.

In the _pages folder, add two new Markdown files: tags.md and categories.md

Add relevant categories and tags to the front matter of a post.

The categories/ and tags/ pages will display a list of the categories and tags linked to the posts.

42 of 43

Other Customizations

Page/Post Layouts: Use page layout templates, header images/videos, galleries, sidebars, table of contents, and more to customize your site.
Site Search: Add a search bar to allow users to search your site more easily.
Favicon: Add a custom icon to display in the browser tab.
Custom Domain: Host your site via a custom domain you have acquired.
Google Analytics: Add tracking information to learn about your site visitors.
Comments: Multiple options to allow comments including through Facebook, Disqus, Discourse, or Staticman.
Social Feed: Embed a feed from a social media account, like Twitter.
And much more!

43 of 43

Thank you!

Feel free to connect or reach out with questions!

@lauren_e_burke

@laurburke

laurburke.github.io

Talk References

site: https://laurburke2.github.io

repo: https://github.com/laurburke2/laurburke2.github.io