How I Blog
Someone asked what I used to produce this blog. This post will provide the methodology and details.
The Decision to Blog
I’ve hosted a personal website on various platforms since early 2000. I’ve used FTP, SFTP, FrontPage, WebDAV, Dreamweaver, WordPress, and probably some others that I’ve forgotten about. Using WordPress, I had performance issues when the MySQL database was not located near the web host.
Even with a stance of ‘update all the plugins’, it was not enough to protect my site from hackers. Late in 2015, my site was hacked and it took me months to realize since they were just hosting hidden pages and hidden SEO info. Once I realized what had happened to my site, I converted it to a static hosted by (don’t judge) Google Sites. It solved the problem of a vulnerable site and poor performance.
I’ve been toying around with the idea of creating a blog for PowerShell for a few years now, ever since I started working with another PowerShell blogger, Michael Simmons, who publishes I Love PowerShell.
As I was learning how to build my own modules, with finesse — not just thrown together, I kept finding enlightening posts on blogs like Kevin Marquette on PowerShell Theory and Warren Frame’s Rambling Cookie Monster. They just happen to be using GitHub Pages, Jekyll, and the Minimal Mistakes Jekyll theme.
This new (to me) tech stack would provide an easy way to add content (not like Google Sites) and still provide a static site with decent performance. Thoughts started falling into place and I saw the efficiency and learning opportunities.
I’m going to blog. And I’m going to use that tech stack.
Editor and Source Control
I use Visual Studio Code to edit my blog, PowerShell code, and scripts in other languages.
Git for Windows allows me to create local source controlled folders and to interact with GitHub. Even if you don’t opt to use GitHub (free for public repositories), you can still use Git locally.
GitHub and GitHub Pages
I’m fully convinced that source control is necessary for code, and a blog is really nothing but code. Therefore, it was an easy decision to use a GitHub repository for my blog and then to configure it to publish using GitHub Pages.
Visit GitHub Help for more information on how to create a GitHub account, create a repository, and information on GitHub Pages.
Perhaps due to OCD, I created a repository to match the custom domain that I’m using for my GitHub Pages. Actually, naming folders based on the hostname is a habit that I got in several years ago. It clearly identifies that the content should be that website.
I’ve had the domain
anovelidea.org since early 2000, and since I didn’t want to use the default domain of *.github.io,
I opted to use the Custom Domain setting for my repo and created
Every git or GitHub repository can have multiple branches. Branches are typically used to develop new features or work on fixes without touching the rest of the code.
Each branch of my repo plays a role in the production of my blog.
|main||I push commits to this branch when I make changes to the blog, e.g. publish new posts or approve comments.|
|gh-pages||After Travis-CI builds the site, it pushes to this branch which GitHub, in turn, publishes to GitHub Pages.|
|comments||The Staticman API creates pull requests for this branch when a new comment is submitted.|
Jekyll is one of the most used static site generators. It’s built on Ruby and renders content with Markdown and Liquid templates.
GitHub Pages deploy sites using Jekyll and provides a handful of themes.
Check out the Jekyll site for more details.
The theme that I chose for simplicity is Minimal Mistakes by Michael Rose at Made Mistakes. He provides a Minimal Mistakes demo site that can show you the theme’s capabilities.
The cool thing about most of the Jekyll themes is that they, themselves, are in GitHub repos. You can download the full repo or fork it and have a site up and running in short order.
Custom Layouts and Includes
The Jekyll framework is essentially a given structure of folders with code snippets that build the static HTML files when Jekyll is instructed to do so. Layouts, includes, CSS, html, Markdown files, and more are stitched together and, barring any compilation errors, the result is several html files, CSS, and other assets that is your site. You could conceivably take those files and FTP them to a third-party hosting provider, but where is the fun in that?
Jekyll uses what’s called front matter YAML in the template files and in the configuration file,
allows each post and page to have different elements.
Layouts and Includes
I’ve updated or added the following layout and includes files from the base theme.
|_layouts\home.html||Replaced archive-single include with posts-lists|
|_layouts\onlinehelp.html||New layout based on single, removed title header, page metadata, and other elements not required|
|_layouts\pages.html||New layout based on single, added code to display published and updated date, removed environment requirement|
|_includes\analytics.html||Removed environment requirement|
|_includes\archive-single.html||Included new include file posts-date|
|_includes\posts-date.html||New include, displays published and updated date|
|_includes\posts-list.html||Based on archive-single, added posts-tags-list and posts-date|
|_includes\posts-tags-list.html||Based on tag-list, uses post.tags instead of page.tags|
Though I’m using the
air skin for my theme, I didn’t like the default color scheme the skin provided. Using the
theme’s documentation, I was able to replace the code syntax highlighting color variables with another skin’s by
updating the file
I wanted to provide a quick place to see my modules and what features they possess. I originally created markdown tables for each, but then decided to use a data file.
Jekyll uses a
_data folder to store data that could be used by the framework. At build time, it will import all files
in this folder and provide the data as variables.
- name: PoShEvents description: 'PowerShell module to query Windows Event Logs.' help: 'External file' onlinehelp: true updatablehelp: true pester: false build: false psgallery: true
_pages\modules.html file, I added the html and Liquid code to loop through each section in the data file.
Instead of manually adding markdown or html code, which can become tedious, I now simply add another section in the data
_data\mymodules.yml. On next build, the page will include the new module.
The theme has built-in support for Google Analytics. You simply add your site’s tracking ID to the
The Minimal Mistakes theme includes several options for visitor comments: disqus, discourse, facebook, google-plus, staticman, staticman_v2, and custom. After checking into them, I saw that the theme author used Staticman V2. It seemed the best way to go and it keeps the comments within your grasp and local(ish) to the site.
Note: The theme author has developed reply-to comments but has not incorporated them into the Minimal Mistakes theme. When I want to get under the hood again of the theme, I will look at implementing it for this site.
Staticman API Webhook
For Staticman to work, there are a few quick configuration steps needed that are laid out in the documentation.
Additionally, you will need a
staticman.yml configuration file. This file is included in the theme’s repo.
Comment forms are magnets for bots and malicious users. The theme provides a few tricks to filter comments down to the
real users wanting to leave a message. Beyond that, I use the optional moderation provided by Staticman which creates a
pull request to the
comments branch. I get a notification that a PR is waiting for me, login to GitHub, even on
mobile, and merge the pull request to approve the message.
The pull request for a comment is saved to
_data\comments\<title-slug\comment-<date-time-stamp>.yml. The visitor’s
email is stored as a hash value to keep it relatively safe.
The theme will use the Gravatar service to provide a graphic that the user has previously configured.
As Jekyll runs on Ruby, you will need to have a system that can run Ruby and the Jekyll gems.
Build System : Windows Subsystem for Linux
Instead of going down the Ruby on Windows avenue, I opted to learn a little about the new Windows Subsystem for Linux on Windows 10. This method produced a few errors that I had to overcome. I’ll most likely post on that setup separately. While I used this method initially, I have all but abandoned it for now.
Build System : Google Cloud Platform
I looked for a free hosting solution to have a Linux VM and, what I’m hoping, it appears that Google Cloud Platform will
give you enough free credits per month to have a single, small VM running the whole time. I had configured it to the
point of being able execute the
jekyll build command successfully.
I had even configured dynamic DNS for the VM to register its IP address with my domain at Google Domains. Hey, at least I know how to do that now.
The problem I faced was that I need a way to kick off the build after I pushed changes into the branch — automatically, if possible. But that would entail me creating a listener on the VM that could be triggered by the branch status change. I felt I had explored that rabbit hole enough and backed out quickly.
I still needed an automated build system.
Build System : Travis CI
Enter Travis CI. The CI stands for Continuous Integration and is part of the CI/CD model that I want to learn about. It drives true DevOps.
On GitHub, I configured the Travis CI service for my blog repo.
Note: Travis CI announced in May
that open source projects would be able to use
travis-ci.com. Sometime soon, I’ll work on upgrading to the new method
which uses GitHub Apps and has greater benefits.
With the integration service setup, whenever the main branch changes, that is when I push changes or when a PR from the comments branch is merged, the service notifies Travis CI that it needs to create a build.
Travis Configuration File
.travis.yml configuration file, I set the build script to execute (chmod), set which branch to clone, and
whether to use a cache for the bundler. Additionally I set it to deploy to the gh-pages branch after the build phase
When notified of a change, Travis spins up an Ubuntu Linux container, installs all dependencies (from self updating
cache), clones the main branch of my blog repo, runs the
/script/cibuild bash script I created, then deploys to the
Spinning up a blog in this manner takes patience and determination, but the rewards include learning new technologies, such as GitHub, Ruby, and Jekyll. It’s taken me several steps toward automation, CI/CD, and DevOps.
Remember, because all of this is hosted publicly by GitHub, you can see everything in my repo. Check out the closed Pull Requests. Check out the folder structure and the files.
I hope this post was informative. Feel free to leave a comment below.
Update 2018-08-29 I used the code from Coders Block to change the color syntax of GitHub Gists.
Update 2020-06-18 Updated references of master branch to main.
Leave a comment