Jekyll2022-07-30T13:54:29+10:00http://chriscoombes.com/feed.xmlChrisCoombes.comChris Coombes's personal blog about cloud, devops, infrastructue as code, powershell, windows, linux and automation.Chris CoombesIntroduction to GitHub Pages and why it’s the chosen platform for this blog2020-09-12T00:00:00+10:002020-09-12T00:00:00+10:00http://chriscoombes.com/blog/github-pages<p>This post is split into two parts, if you are already sold on GitHub Pages and want a technical overview of how I set it up, please click <a href="#basic-setup">here</a> to be taken directly to the tutorial. If you are interested in understanding why I chose this platform please continue reading below.</p>
<p>As the tag line of this site and the themes highlighted in my initial <a href="/blog/welcome-to-my-blog/">post</a> would indicate, the primary driver for setting up this site was to document my learnings of modern cloud technologies. To gain the full operational benefit of “the cloud” relies on automating all aspects of the environment, including the ability to rapidly provision and manage infrastructure.</p>
<p>The concept of Infrastructure as Code introduces an infrastructure deployment process which describes in text files the desired state of the systems. While the theory is sound, through the ability to create immutable repeatable infrastructure, it introduces a new challenge of managing and sharing the source files used in the process.</p>
<p>In a large environment, this will consist of hundreds if not thousands of files, including multiple versions. These files all need to be created and maintained by several people across the organisation. Keeping these files organised can quickly become a management burden. Source control or version control is the practice of tracking and managing changes to code. Source control management (SCM) is the classification given to the tools that operate this process. SCM is a system which provides a running history of code development and helps to resolve conflicts when merging contributions from multiple sources.</p>
<p>There are several SCM tools available the most common and widely used of these tools is Git. The use of Git or SCM systems, in general, has traditionally been associated with the developer community. This observation is no longer valid, with its adoption rapidly increasing across the full range of IT roles. Familiarity with SCM tools is quickly becoming a must-have skill for developers and systems administrators alike.</p>
<p><img src="https://git-scm.com/images/logos/2color-lightbg@2x.png" alt=""Git Logo"" title="https://git-scm.com/images/logos/2color-lightbg@2x.png" /></p>
<blockquote>
<p>Git is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files. Its goals include speed, data integrity, and support for distributed, non-linear workflows.</p>
</blockquote>
<blockquote>
<p><a href="https://en.wikipedia.org/wiki/Git">Wikipedia</a></p>
</blockquote>
<p>When selecting a blogging platform, I wanted something that integrated a content management system while learning the basics of Git. While technically any project containing source files can be managed by Git, I was looking for a platform that is easy to use and had content creation at it’s core.</p>
<p>GitHub Pages meets this brief perfectly. GitHub Pages is a free static website hosting service from GitHub that renders files from a Git managed cloud repository and publishes them as a website. In addition to the learning opportunities, the use of a static hosting service has many advantages. There are no databases to maintain, no plugins to manage, no security updates to install and with the removal of these overheads page load speed are greatly enhanced.</p>
<p>When comparing against a traditional blogging platform, you might think with the removal of all these features that using a static website, functionality would be reduced. This is where the use of static site generator (SSG) applications comes in. SSG is a software package that you run on your workstation that creates HTML files based on templates you specify and formats them for publishing to the web. There are several SSG’s available the focus of this post is Jekyll as it’s natively supported by GitHub Pages.</p>
<p><img src="https://upload.wikimedia.org/wikipedia/commons/4/42/Jekyll_%28software%29_Logo.png" alt=""Jekyll Logo"" title="https://upload.wikimedia.org/wikipedia/commons/4/42/Jekyll_%28software%29_Logo.png" /></p>
<blockquote>
<p>Jekyll does what you tell it to do — no more, no less. It doesn’t try to outsmart users by making bold assumptions, nor does it burden them with needless complexity and configuration. Put simply, Jekyll gets out of your way and allows you to concentrate on what truly matters: your content.</p>
</blockquote>
<blockquote>
<p><a href="https://github.com/jekyll/jekyll/blob/master/README.markdown">Jekyll README.md</a></p>
</blockquote>
<p>In summary, while all the technologies mentioned above have a direct connection with Git they offer very different functionality and can confuse a beginner or even a seasoned professional when getting started;</p>
<ul>
<li>Git: Tool for working with source files</li>
<li>GitHub: A cloud-based repository to store Git managed source files</li>
<li>GitHub Pages: Renders source files to be displayed as a website</li>
<li>Jekyll: Tool used to generate HTML pages which can be pushed GitHub and rendered as a website</li>
</ul>
<p>The rest of this post will cover off the steps for getting started with GitHub Pages.</p>
<h1 id="basic-setup">Basic Setup</h1>
<p>The first step to getting started with GitHub Pages is to create a GitHub account. Head to the <a href="https://github.com/join?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F&source=header-home">GitHub</a> sign up page to create an account.</p>
<p><img src="/assets/images/posts/github-pages/gh-signup.png" alt=""GitHub sign up"" title="Creating a GitHub Account" /></p>
<h2 id="creating-a-repository">Creating a Repository</h2>
<p>Now that you have a GitHub account, the next step is creating a cloud repository to host your source files that are to be rendered as a webpage.</p>
<p>Select New from the top left corner of GitHub dashboard.</p>
<p><img src="/assets/images/posts/github-pages/gh-new-repo.png" alt=""GitHub New Repo"" title="GitHub New Repository" /></p>
<p>Typically when naming a repository you can name it whatever you like, as long as it is unique for your GitHub account. GitHub Pages has a unique requirement in that the repository must be named ‘username.github.io’ to properly render the files that it contains as a website.</p>
<p>The username for my demo account is <strong>‘gac-cloud-demo’</strong> so I will name my repository <strong>‘gac-cloud-demo.github.io’</strong>.</p>
<p>Make sure your repository is set to public so the content is visible to all, then select <strong>‘Create repository’</strong>.</p>
<p><img src="/assets/images/posts/github-pages/gh-repo.png" alt=""Creating repository"" title="Creating your GitHub pages repository" /></p>
<p>Take note of the HTTPS URL you will need this later.</p>
<p><img src="/assets/images/posts/github-pages/gh-url.png" alt="GitHubURL" title="GitHub Repository URL" /></p>
<h1 id="installing-git">Installing Git</h1>
<p>In this post I will cover the installation methods I use for Windows and Mac only. Git is available on Windows, Mac and Linux for installation instruction for the Linux distribution of your choice please visit;</p>
<p><a href="https://git-scm.com/download/">https://git-scm.com/download/</a></p>
<p>Now you need to install Git on your local computer to create a local Git repository that will eventually be synced with the GitHub repository you just created.</p>
<h2 id="windows">Windows</h2>
<p>To install Git on my Windows workstation I used the Chocolatey package manager, which is my preferred method for managing application installations, for more details on Chocolatey please visit;</p>
<p><a href="https://chocolatey.org"><img src="/assets/images/posts/github-pages/chocolatey-logo.png" alt="Chocolatey" title="Chocolatey Logo" /></a></p>
<h3 id="install-chocolatey">Install Chocolatey</h3>
<p>To install Chocolatey first open PowerShell as an Administrator</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
</code></pre></div></div>
<p>Close Powershell window</p>
<h3 id="install-git-package">Install Git package</h3>
<p>Open PowerShell as an Administrator</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>choco install Git
</code></pre></div></div>
<p>Close and reopen PowerShell as a standard user</p>
<p>To confirm Git has been successfully installed run the following command</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git --version
</code></pre></div></div>
<p>At the time of writing, this would return</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git version 2.28.0.windows.1
</code></pre></div></div>
<p>Your PC is now set up and ready to use Git on your local computer and push content to a GitHub repository.</p>
<h2 id="macos">macOS</h2>
<p>There are several options available for installing Git on macOS. If you already have the XCode Command Line Tools installed it’s likely that Git will already be available. To install Git on my macOS workstation, like Windows my preferred method for managing packages is to use a package manager. The package manager for macOS is HomeBrew, for more details please visit;</p>
<p><a href="https://brew.sh"><img src="/assets/images/posts/github-pages/Homebrew-mac-logo.jpg" alt="HomeBrew" title="HomeBrew Logo" /></a></p>
<h3 id="install-homebrew">Install Homebrew</h3>
<p>Open a new Terminal window</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
</code></pre></div></div>
<p>Close Terminal</p>
<h3 id="install-git-package-1">Install Git package</h3>
<p>Open Terminal</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>brew install git
</code></pre></div></div>
<p>Close and reopen Terminal</p>
<p>To confirm Git has been successfully installed run the following command</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git --version
</code></pre></div></div>
<p>At the time of writing, this would return</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git version 2.28.0
</code></pre></div></div>
<p>Your Mac is now set up and ready to use Git on your local computer and push content to a GitHub repository.</p>
<h1 id="github-pages">GitHub Pages</h1>
<p>Now that we have a GitHub account and a functioning installation of Git on our Windows PC or Mac, the next steps are to create some content to be used by GitHub Pages and commit it to a Git repository.</p>
<p>I will cover the basics of using two content types with GitHub Pages, HTML and Markdown as well as highlight the differences between the two. For an in-depth look at GitHub Pages please visit;</p>
<p><a href="https://docs.github.com/en/github/working-with-github-pages">https://docs.github.com/en/github/working-with-github-pages</a></p>
<h2 id="basic-html">Basic HTML</h2>
<p>Open your console of choice (PowerShell / Terminal)</p>
<p>Create a directory for your files</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>mkdir gac-cloud-demo
cd gac-cloud-demo
</code></pre></div></div>
<p>Create the HTML file</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>echo "<h1>Hello GitHub Pages</h1>" >> index.html
</code></pre></div></div>
<p>Now it’s time to start working with Git</p>
<p>Initialise your local Git repository</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git init
</code></pre></div></div>
<p>Add files to be tracked by version control to your local Git repository</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git add index.html
</code></pre></div></div>
<p>Commit the changes</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git commit -m "first commit"
</code></pre></div></div>
<p>You now have our first files being tracked by version control</p>
<p>To enable the content ypu have just created to be uploaded to GitHub we need to link your local Git repository with the Cloud-hosted GitHub repository we created earlier.</p>
<p>Copy the HTTPS URL for our GitHub pages repository</p>
<p><img src="/assets/images/posts/github-pages/gh-url.png" alt="GitHubURL" title="GitHub Repository URL" /></p>
<p>Using this URL you then need issue the command to link your repositories</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git remote add origin https://github.com/gac-cloud-demo/gac-cloud-demo.github.io.git
</code></pre></div></div>
<p>Now that the repositories are linked you need to push the committed files in your local Git repository to your cloud repository.</p>
<p>As this is the first time we are pushing files you need to tell Git which branch to push your changes to. The default branch is ‘master’ which exists on every repository.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git push -u origin master
</code></pre></div></div>
<p>Now that the files have been uploaded you can check in on your website. First check your GitHub Pages settings, if we named our repository ‘username.github.io’ these should be configured by default.</p>
<p>Log into your GitHub account and confirm the Github pages settings match the following;</p>
<p><img src="/assets/images/posts/github-pages/gh-ghp-settings.png" alt=""Confirm GitHub pages settings"" title="Confirm GitHub pages settings" /></p>
<p>Now open your preferred web browser and visit your GitHub Pages URL and you will see the rendered HTML.</p>
<p>NOTE: If this is the first time browsing it can take a few minutes for GitHub to populate the content.</p>
<p>For me my GitHub Pages URL is;</p>
<p><a href="http://gac-cloud-demo.github.io">http://gac-cloud-demo.github.io</a></p>
<p><img src="/assets/images/posts/github-pages/ghp-html-render.png" alt=""GitHub pages rendered HTML"" title="GitHub pages rendered HTML" /></p>
<h2 id="basic-markdown">Basic MarkDown</h2>
<p>Markdown is a lightweight markup language with a plain-text-formatting syntax, removing the requirement to add complex tags to format documents. The primary use case for this is HTML, taking a simple human-readable text file and having it converted to structurally correct HTML ready to be displayed on the web.</p>
<p>GitHub Pages allows you to use Markdown files to create content through the built-in integration with Jekyll. By default, every file saved in a GitHub Pages repository will be rendered by Jekyll. Through the use of a template, you can take these simple text files and have them displayed to the web in a visually pleasing way.</p>
<p>In the same local directory you were working in before, create a new Markdown file.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>echo "# Hello GitHub Pages" >> index.md
</code></pre></div></div>
<p>You are replacing your HTML files with Markdown you need to exclude the HTML file created previously from being tracked by version control.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git rm index.html
</code></pre></div></div>
<p>Add the new Markdown file to be tracked</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git add index.md
git commit -m "Markdown commit"
</code></pre></div></div>
<p>As you linked our local and remote repositories earlier, we can simply run a Git push.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git push
</code></pre></div></div>
<p>Visit your GitHub Pages URL and you should see the rendered Markdown file.</p>
<p><img src="/assets/images/posts/github-pages/ghp-md-render-basic.png" alt=""GitHub pages rendered Markdown"" title="GitHub pages rendered Markdown" /></p>
<p>You will notice the formatting is slightly different. This is Jekyll formatting the content using the default template.</p>
<p>GitHub Pages offer a variety of templates you can use to format your content.</p>
<p><img src="/assets/images/posts/github-pages/ghp-themes.png" alt=""Jekyll templates"" title="Jekyll templates" /></p>
<p>Select a new template, for this demo, I used ‘Slate’.</p>
<p>Browse to your URL again and you will see the new formatting.</p>
<p><img src="/assets/images/posts/github-pages/ghp-md-render-template.png" alt=""New Jekyll Template"" title="New Jekyll template" /></p>
<p>This is the power of writing in Markdown. Removing all the complex formatting tags and focusing purely on creating the content.</p>
<p>For example, please visit my <a href="https://raw.githubusercontent.com/ccoombes/ccoombes.github.io/master/_drafts/2020-08-21-github-pages.md">GitHub</a> profile and view the Markdown file for this post.</p>
<h1 id="whats-next">What’s Next</h1>
<p>The next post will cover using a custom theme and some of the Jekyll tweaks I have used to create <a href="https://chriscoombes.com">ChrisCoombes.com</a>.</p>
<p>If you found this article useful, please let me know at <a href="https://www.twitter.com/ccoombes83">@ccoombes83</a> or email me at <a href="mailto:ccoombes@outlook.com">ccoombes@outlook.com</a>.</p>Chris CoombesThis post is split into two parts, if you are already sold on GitHub Pages and want a technical overview of how I set it up, please click here to be taken directly to the tutorial. If you are interested in understanding why I chose this platform please continue reading below.Starting a Tech blog!2020-08-11T00:00:00+10:002020-08-11T00:00:00+10:00http://chriscoombes.com/blog/welcome-to-my-blog<p>Why am I starting a blog? For a seasoned IT professional, there are many reasons for setting up a personal website or blog. Drawing on the ever-evolving technology landscape or documenting the challenges experienced every day, there is a magnitude of content waiting to be published. For me the primary objectives for going down this path are;</p>
<ul>
<li>To gain a deeper understanding of the topics researched.</li>
<li>To document new skills using the philosophy “You Never Really Learn Something Until You Teach It”.</li>
<li>A way to validate my knowledge.</li>
<li>To improve my written communication.</li>
<li>Giving back to the community.</li>
</ul>
<p>Why now? With a global pandemic rampant, enforced ‘working from home’ policies, the immediate future looking a little grim, this may seem like an odd time to start. After never working from home for more than a single day in my entire career, I was excited by the opportunity the situation presented. The extra time made available through the lack of commute and the flexibility in work hours would mean increased time with my young family and further personal development opportunities.</p>
<p>It would seem people have reacted in two ways to these circumstances. Either bettering themselves through learning new skills, enhancing their fitness, improving diets or the opposite, binging Netflix, eating junk, generally hating on the world and if you are in Australia hoarding toilet paper.</p>
<p><img src="https://www.pedestrian.tv/content/uploads/2020/03/04/toilet-paper-crisis-memes-social-1.png" alt=""Simpsons"" title="Simpsons toilet paper meme" /></p>
<p>I think I’m the first type and have focused heavily on my fitness and diet, the one outstanding area for development was to work on learning some new skills. Like many tech enthusiasts, I love researching and playing with new technologies, from reading blogs, watching training videos to tinkering in my home lab. While this is enjoyable, the knowledge gained always ends up as scattered thoughts lacking the structure needed to be fully absorbed and used constructively. Starting this blog is my way of bringing these ideas together. Leaning on a key objective I highlighted earlier, the best way to deeply understand a topic is to teach someone else about it.</p>
<p>If it’s such a good idea, why the delay? The usual reasons that go through one’s mind when publishing online;</p>
<ul>
<li>No one wants to listen to anything I have to say.</li>
<li>My writing isn’t good enough.</li>
<li>Someone ‘smarter’ than me has already written about that.</li>
<li>The fear of being ridiculed by peers.</li>
<li>What if no one reads what I write?</li>
<li>I don’t have time for that.</li>
</ul>
<p>In the end, these are all worthless excuses if you want to improve yourself then you need to bite the bullet and get it done.</p>
<blockquote>
<p>Some people want it to happen, some wish it would happen, others make it happen.<br />
<cite>Michael Jordan</cite></p>
</blockquote>
<p>What topics will be covered? In a career that has spanned almost 15 years across the full spectrum of IT Operations roles, service desk to management. While I will lean on my experiences from over the years, these roles have primarily been with manufacturing organisations with a focus on traditional on-premise infrastructure. The focus of this blog will be the discovery of the ‘modern’ infrastructure landscape and the practices that enable it.</p>
<p>Follow my journey to the clouds!</p>
<p>If you found this article useful, please let me know at <a href="https://www.twitter.com/ccoombes83">@ccoombes83</a> or email me at <a href="mailto:ccoombes@outlook.com">ccoombes@outlook.com</a>.</p>Chris CoombesWhy am I starting a blog? For a seasoned IT professional, there are many reasons for setting up a personal website or blog. Drawing on the ever-evolving technology landscape or documenting the challenges experienced every day, there is a magnitude of content waiting to be published. For me the primary objectives for going down this path are; To gain a deeper understanding of the topics researched. To document new skills using the philosophy “You Never Really Learn Something Until You Teach It”. A way to validate my knowledge. To improve my written communication. Giving back to the community.