OpenSource Blogging with Jekyll GitHub VSCode Part 2

 

During Part 1 of this series I introduced you to open source blogging using some awesome tools and platforms available today. I also shared my own setup so you can see what’s involved end-to-end.

Shortly I’ll provide a detailed walkthrough of everything you need to get started with your own blog site.

 

Part 1 – Why I’m using open source and an overview of my blog setup Part 2 – Getting started with a step-by-step guide – you are here Part 3 – Securing your Content and Going Live with GitHub Pages Part 4 – Tips & Tricks with Jekyll and Markdown editing

Local Blog Development

First we need to setup our local development environment for the blog site by installing a few dependencies.

 

As I’m running a Surface Book 2 these instructions are for the Windows 64-bit OS but can be modified to suit MacOS or Linux as needed.

PART 2 DEPLOYMENT PLAN

Coming Up…

 

We will install VSCode We will install Git We will install Ruby and Jekyll We will clone a Jekyll Theme to a local folder and preview the site

Already have Visual Studio Code or Git installed? –> Update to the latest release prior to continuing with this guide.

 

VSCode – Go to Help > Check for Updates from your VSCode client to update to the latest release. Git – Use git update-git-for-windows from your Git client to update to the latest release.

Step 1 – Install Visual Studio Code

 

Go to https://code.visualstudio.com/download Download & run the Windows (x64) installer ~ 57MB. Accept all defaults during the installation wizard. Nothing exciting here!

Step 2 – Install Git

 

Make your way to https://git-scm.com/downloads Download & run the Windows (x64) installer ~ 44MB. During the install wizard – make sure to choose Visual Studio Code as Git's default editor from the drop-down (shown below). All other install defaults seem fine to leave as-is!

MAKE SURE TO CHOOSE VISUAL STUDIO CODE AS GIT’S DEFAULT EDITOR

Step 3 – Install Ruby / Jekyll

 

Head over to https://rubyinstaller.org/downloads/ Download & run the Ruby+Devkit 2.6.X (x64) installer ~ 132MB. During the install wizard accept all defaults. Click Finish at the completion of the install wizard. After the install wizard a new cmd window will appear automatically and display 3x selections – Make sure to key in the number 1 before hitting enter to continue. If all goes well you should see a screen saying MSYS2 is installed. Feel free to close it. Now that’s over, open your VSCode client & also a new Terminal ( ctrl+shift+` ) Next we need to install the Jekyll and Bundler RubyGems with following cmdlet: $ gem install jekyll bundler If you run into issues here try re-installing Ruby+Devkit starting from Step 2 above.

DOWNLOAD & RUN THE RUBY+DEVKIT 2.6.X (X64) INSTALLER

DURING THE INSTALL WIZARD ACCEPT ALL DEFAULTS.

DURING THE INSTALL WIZARD ACCEPT ALL DEFAULTS.

CLICK FINISH.

MAKE SURE TO KEY IN THE NUMBER 1 BEFORE HITTING ENTER TO CONTINUE.

IF ALL GOES WELL YOU SHOULD SEE A SCREEN SAYING MSYS2 IS INSTALLED. FEEL FREE TO CLOSE IT.

WE NEED TO INSTALL THE JEKYLL AND BUNDLER RUBYGEMS WITH FOLLOWING CMDLET: $ GEM INSTALL JEKYLL BUNDLER

IF YOU RUN INTO ISSUES HERE TRY RE-INSTALLING RUBY+DEVKIT STARTING FROM STEP 2 ABOVE.

Step 4 – Using a community theme – Minimal Mistakes

We want to be blogging today-ish, not next week or a month later. So let’s clone/fork an existing Jekyll theme to our local dev environment. We can then modify it to suit our needs without reinventing the wheel!

By the way! The default Jekyll theme is Minima and seems fine for a quick proof of concept. I don’t recommend going live with it because of what it lacks when compared to other themes out there. You can check it out by executing the following cmdlets from a VSCode Terminal:

$ jekyll new my-awesome-site

 $ cd my-awesome-site

 $ bundle exec jekyll serve

After a successful serve – browsing to http://localhost:4000 will display a home page like this.

JEKYLL DEFAULT THEME (MINIMA)

Currently I’m using Minimal Mistakes by Michael Rose because it suits my needs & because of Michael’s helpful documentation available – for example check out https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/

The quickest way to get started with the Minimal Mistakes theme is to git clone or git fork one of the following GitHub repositories.

 

Minimal Mistakes Remote Theme Starter Minimal Mistakes

Let’s look at how this works with the Remote Theme.

Try executing the following cmdlets from a VSCode Terminal:

$ cd C:/

 $ git clone https://github.com/mmistakes/mm-github-pages-starter

 $ cd mm-github-pages-starter/

 $ bundle exec jekyll serve

After a successful serve – browsing to http://localhost:4000 will display a home page like this.

JEKYLL COMMUNITY THEME (MMISTAKES)

Open the newly created folder C:\mm-github-pages-starter from VSCode to access the following site structure.

MMISTAKES SITE STRUCTURE

Here’s a breakdown of what you see above. It’s important to understand this structure as the majority of your changes will happen here.

 

_data contains a .yml file which controls the site navigation links visible at the top of pages. Modify the navigation.yml file as you add/remove pages to your site. _pages contains .markdown files used by the site such as the 404 and About pages. Modify the existing pages in this folder or create new ones to suit your needs. _posts contains .markdown files that are published to the site as new posts. Place your new posts into this folder. _site is where Jekyll has built and stored the site before publishing it locally. You can ignore this folder. assets\images contains image files used by the site and pages/posts. Save your PNG/JPEG/BMP/GIF files into this folder and reference the path in your markdown. _config.yml is the main configuration file that Jekyll references to build the site after you have used bundle exec jekyll serve. Modify this file first to update key properties/variables and then rerun a jekyll serve to see the changes locally. .gitignore contains files or folders that you do not want syncing via Git to your GitHub repository. Modify this file if you add a _drafts folder later on for posts that you don’t want sync’d into GitHub. Gemfile is used to define RubyGems that are loaded for the site. Modify this file as needed for changes to plugins. Gemfile.lock is a Jekyll autogenerated file that appears after you have used bundle exec jekyll serve – you can ignore it. index.html defines some YAML Front Matter for the site’s home page. There’s no need to modify this file. README.md is a helpful introduction to the Remote Theme written by the author Michael Rose.

Next Steps

Review and update Config.yml Create a few blog posts into the _posts folder. Add your own images into the assets\images folder and reference them into posts using . Create your own About page or update the existing  _pages/About.md. Run bundle exec jekyll serve to see the results!

Recap

We’ve completed installation of our open source blogging dependencies to our local dev environment and cloned/served a Jekyll theme.

PART 2 DEPLOYMENT PLAN COMPLETE!

Congrats on getting this far!

Join me for Part 3 of this series where we’ll look at taking your blog live with GitHub and GitHub Pages.

Join me for Part 3 of this series where we’ll look at taking your blog live with GitHub and GitHub Pages.