Static content generators are becoming more and more popular as there’s a drive to deliver content as quickly as possible from versioned source code to the browser. Jekyll is a static content generator that is written in Ruby and available as a Ruby Gem. Jekyll can be executed locally, on a server, within a cloud service, or within GitHub. Within this post, you’ll learn how to create a Jekyll theme using a Windows based PC. While the steps are the same if you are using a Mac or Linux machine, there are a few subtle differences for Windows such as the way you get started. Jekyll Themes are actually Ruby Gems. Wait! You’ve never created a Ruby Gem? Neither have I. We’ll go through this process together.

Prerequisites

There are a few requirements to get started.

  1. Ruby – You’ll need to grab Ruby. The Jekyll website states that version 2.5 or above is needed, but I tend to ensure I have the latest. On Windows, you’ll install Ruby plus the Devkit using https://rubyinstaller.org/downloads/. You can find out what version you have by running ruby -v from a command line.
  2. RubyGems – You’ll need to have RubyGems. You can check if you have it installed by running gem -v from a command line.
  3. Jekyll – You’ll need to install Jekyll. However, to do this, you need to have a new command line open to ensure that Ruby has been added to the PATH environment variable. To install Jekyll, run gem install jekyll bundler from the new command line. You’ll know the process was successful if you see the version returned from running jekyll -v.

Awesome! At this point, you should have a Ruby environment and Jekyll installed as well.

Create a Jekyll Theme

I normally like to create a brand new Git repository right from the start. However, Jekyll will do this for us when we create our new theme. So, let’s navigate to the folder that we’d like to place our new Git repository that will house Jekyll. We’ll do this inside of our command prompt. I have a habit of creating a folder on my local C: drive called Repos and cloning and creating repositories in that folder. I’ll navigate to C:\Repos in my command prompt. For these purposes, I’m going to use the name Spaaced. Type jekyll new-theme Spaaced to create your structure for your Jekyll theme.

https://cdn.jasongaylord.com/images/2020/05/04/Jekyll-New-Theme-Command.jpg

You’ll notice that Jekyll will respond with a message to read the README.md file to get started. Open that file in your favorite Markdown editor. I happen to use Visual Studio Code as my preferred editor. In fact, I won’t just open that file, I’ll open the entire folder in VS Code.

The README.md will explain how to install your Jekyll theme in your local Jekyll site. However, did you know that if you host the repository on something such as GitHub and use GitHub pages, you can take advantage of the remote-theme gem. What’s this gem, you ask? It’s a plugin for Jekyll that allows your Jekyll site to connect to any public GitHub hosted theme (or repository). You can find out more about the jekyll-remote-theme gem by visiting https://github.com/benbalter/jekyll-remote-theme.

We’ll create a basic theme below. However, from here, you should be set to start updating your theme. Be sure to update the README.md file to instruct others about your theme and how to use it. If you’re struggling to get started with the layouts, includes, and other items, I’d recommend looking at another theme for ideas and inspiration. The following sites provide Jekyll themes including links to their source:

Testing Your Theme

We’ll want to start adding a very basic theme and test it locally. So, I performed the same actions above, but instead of the Spaaced theme, I decided to use a new theme called BasicTheme. If you want to see the full source of this theme, visit the repository on GitHub at https://github.com/jasongaylord/BasicTheme. The idea is to provide a very basic layout with an HTML structure, a header, and some basic styles. Once I created the BasicTheme as we did above, I headed to GitHub and created a new repository called BasicTheme. I then navigated to the BasicTheme folder on my machine and ran a series of commands to send the theme to GitHub.

1
2
3
4
git remote add origin https://github.com/jasongaylord/BasicTheme.git
git add .
git commit -m "Initial commit."
git push -u origin master

At this point, our initial theme has been pushed to GitHub. We can now test this theme out within a local Jekyll site. So again, in the command line, I’ll navigate back to C:\Repos and create a new Jekyll site by executing:

jekyll new TestJekyllSite

TestJekyllSite is just the name I decided to call my new site.  Next, I’ll open the TestJekyllSite in VS Code. Once it opens, in the Explorer pane, I’ll find GEMFILE. The GEMFILE contains the list of gems that will be used by the Ruby application, in this case, Jekyll and the Jekyll plugins. In the Jekyll Plugins group at around link 19, I’ll add a new entry for the jekyll-remote-theme that will look like this:

https://cdn.jasongaylord.com/images/2020/05/04/jekyll-remote-theme-gem.jpg

Next, open the _config.yml YAML file in the Explorer pane. Remove the line that reads theme: minima. Replace that line with a line that reads remote_theme: jasongaylord/BasicTheme. Replace jasongaylord with your GitHub username and BasicTheme with the name of your theme.

Now that we’ve prepared our Jekyll site for build, let’s go back to the command line and run the following two commands:

1
2
jekyll build
jekyll serve

You’ll notice that after the serve command executes, you’ll receive a URL like so:

https://cdn.jasongaylord.com/images/2020/05/04/jekyll-serve-01.jpg

Navigate to that URL and be prepared to be amazed. Wait! The page is blank? That’s because of two things. Let’s go back to our Jekyll file so we can observe. Don’t close out of the browser just yet.

Open up the index.markdown file in the Explorer pane. This is our entry file for our test site. You’ll notice that it references the home Layout file. We haven’t explored the layouts in our theme yet, but for now we only have a default, post, and page layout. Let’s replace home with default for now. Below the YAML header at the top of the file, the area that has three dashes (—), add a new line of text that simply reads ‘Hello World!’. Save the file and navigate back to the browser. Refresh and you’ll notice your new file being served.

Now that we’ve tested our theme and building a sample Jekyll site, let’s start analyzing our theme a little bit more.

Adding Includes

Include files are files that we’ll “include” in another area of the website. Think of includes as content that can be shared throughout pages and posts on your site. They can contain dynamic content that is passed as a parameter. A great use of an include would be a header or footer for a website. I’ll add just one include and call it head.html. The content of the file will look like this:

1
2
3
4
5
6
7
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link href="https://fonts.googleapis.com/css?family=Mate|Open+Sans" rel="stylesheet">
  <link rel="stylesheet" href="/assets/style.css">
</head>

This file is fairly self explanatory as it will contain the head section of my HTML file. The &#123;&#123; .. &#125;&#125; value will be injected into this include at runtime.

Adding Layouts

The default.html file contained in the Layouts folder should be considered the default template to be used for content within the site. Typically, this file will contain the HTML header and body for your site. Remember, we can include files from our includes folder as mentioned above.

You’ll notice that there are two other files in the Layouts folder: page.html and post.html. The page file is used as the primary layout for any static pages. The post file is used as the primary layout for any blog posts. In both of these pages, you’ll see that they inherit from default.html.

I’ll update the default.html file so that it looks similar to this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
<!DOCTYPE html>

<html lang="en"><head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link type="application/atom+xml" rel="alternate" href="https://www.jasongaylord.com/feed.xml" title="Jason N. Gaylord" />
    <!-- Begin Jekyll SEO tag v2.6.1 -->
<title>Creating a Jekyll Theme from Windows | Jason N. Gaylord</title>
<meta name="generator" content="Jekyll v3.8.7" />
<meta property="og:title" content="Creating a Jekyll Theme from Windows" />
<meta name="author" content="Jason Gaylord" />
<meta property="og:locale" content="en_US" />
<meta name="description" content="Static content generators are becoming more and more popular as there’s a drive to deliver content as quickly as possible from versioned source code to the browser. Jekyll is a static content generator that is written in Ruby and available as a Ruby Gem. Jekyll can be executed locally, on a server, within a cloud service, or within GitHub. Within this post, you’ll learn how to create a Jekyll theme using a Windows based PC. While the steps are the same if you are using a Mac or Linux machine, there are a few subtle differences for Windows such as the way you get started. Jekyll Themes are actually Ruby Gems. Wait! You’ve never created a Ruby Gem? Neither have I. We’ll go through this process together." />
<meta property="og:description" content="Static content generators are becoming more and more popular as there’s a drive to deliver content as quickly as possible from versioned source code to the browser. Jekyll is a static content generator that is written in Ruby and available as a Ruby Gem. Jekyll can be executed locally, on a server, within a cloud service, or within GitHub. Within this post, you’ll learn how to create a Jekyll theme using a Windows based PC. While the steps are the same if you are using a Mac or Linux machine, there are a few subtle differences for Windows such as the way you get started. Jekyll Themes are actually Ruby Gems. Wait! You’ve never created a Ruby Gem? Neither have I. We’ll go through this process together." />
<link rel="canonical" href="https://www.jasongaylord.com/blog/creating-a-jekyll-theme-from-windows" />
<meta property="og:url" content="https://www.jasongaylord.com/blog/creating-a-jekyll-theme-from-windows" />
<meta property="og:site_name" content="Jason N. Gaylord" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2020-05-04T00:00:00-04:00" />
<meta name="twitter:card" content="summary" />
<meta property="twitter:title" content="Creating a Jekyll Theme from Windows" />
<meta name="twitter:site" content="@jgaylord" />
<meta name="twitter:creator" content="@Jason Gaylord" />
<meta name="google-site-verification" content="cjbVriPAfj0T_WG2hUu3GJTxRjCnWCZ6veDMczcUEHg" />
<script type="application/ld+json">
{"@type":"BlogPosting","url":"https://www.jasongaylord.com/blog/creating-a-jekyll-theme-from-windows","headline":"Creating a Jekyll Theme from Windows","dateModified":"2020-05-04T00:00:00-04:00","datePublished":"2020-05-04T00:00:00-04:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://www.jasongaylord.com/blog/creating-a-jekyll-theme-from-windows"},"author":{"@type":"Person","name":"Jason Gaylord"},"description":"Static content generators are becoming more and more popular as there’s a drive to deliver content as quickly as possible from versioned source code to the browser. Jekyll is a static content generator that is written in Ruby and available as a Ruby Gem. Jekyll can be executed locally, on a server, within a cloud service, or within GitHub. Within this post, you’ll learn how to create a Jekyll theme using a Windows based PC. While the steps are the same if you are using a Mac or Linux machine, there are a few subtle differences for Windows such as the way you get started. Jekyll Themes are actually Ruby Gems. Wait! You’ve never created a Ruby Gem? Neither have I. We’ll go through this process together.","@context":"https://schema.org"}</script>
<!-- End Jekyll SEO tag -->

    
    <link rel="stylesheet" href="/assets/style.css">
<link rel="stylesheet" href="/assets/syntax-highlight.css">
<link href="https://fonts.googleapis.com/css?family=Merriweather:400|Lato|Raleway:700,900" rel="stylesheet">
<script src="https://kit.fontawesome.com/506794c6fa.js" crossorigin="anonymous"></script>
    <script src="/assets/js/utils.js"></script>
    
      <script>
  window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
  ga('create', 'UA-2053573-1', 'auto');
  ga('send', 'pageview');
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>
    
    
      <script data-ad-client="ca-pub-2663334448189019" async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
    
    
      <link href="https://fonts.googleapis.com/css?family=Rock+Salt:400" rel="stylesheet">
<link rel="apple-touch-icon" sizes="57x57" href="/assets/icons/apple-icon-57x57.png">
<link rel="apple-touch-icon" sizes="60x60" href="/assets/icons/apple-icon-60x60.png">
<link rel="apple-touch-icon" sizes="72x72" href="/assets/icons/apple-icon-72x72.png">
<link rel="apple-touch-icon" sizes="76x76" href="/assets/icons/apple-icon-76x76.png">
<link rel="apple-touch-icon" sizes="114x114" href="/assets/icons/apple-icon-114x114.png">
<link rel="apple-touch-icon" sizes="120x120" href="/assets/icons/apple-icon-120x120.png">
<link rel="apple-touch-icon" sizes="144x144" href="/assets/icons/apple-icon-144x144.png">
<link rel="apple-touch-icon" sizes="152x152" href="/assets/icons/apple-icon-152x152.png">
<link rel="apple-touch-icon" sizes="180x180" href="/assets/icons/apple-icon-180x180.png">
<link rel="icon" type="image/png" sizes="192x192" href="/assets/icons/android-icon-192x192.png">
<link rel="icon" type="image/png" sizes="32x32" href="/assets/icons/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="96x96" href="/assets/icons/favicon-96x96.png">
<link rel="icon" type="image/png" sizes="16x16" href="/assets/icons/favicon-16x16.png">
<script src="/assets/js/clipboard.js"></script>
<script src="/assets/js/lazysizes.min.js"></script>
    
    
  </head><body>
    <main class="container">
      <section class="about">
        <h2>Jason N. Gaylord</h2>
      </section>
      <section class="content">
        <div style="text-align:center;margin-bottom:15px;">
    <div class="desktop ad" data-type="ad" data-publisher="lqm.jasongaylord.site" data-format="728x90" data-zone="post"></div>
    <div class="mobile ad" data-type="ad" data-publisher="lqm.jasongaylord.site" data-format="300x250" data-zone="post"></div>
</div>

<div class="wrapper">
  <article class="post h-entry" itemscope itemtype="http://schema.org/BlogPosting">
    <header class="post-header">
      <h1 class="post-title p-name" itemprop="name headline">Introducing Visual Studio Codespaces</h1>
      <div class="post-header">
    <i class="far fa-calendar-alt"></i>
    <time class="date dt-published" datetime="2020-05-03T00:00:00-04:00" itemprop="datePublished">
        
        May 3, 2020
    </time>

    &nbsp;
    &#9679;
    &nbsp;

    
    
        1 minute(s) to read

        &nbsp;
        &#9679;
        &nbsp;
    

       
        <span class="cursor" data-copy-text="https://jasong.us/3aYeKYL"><i class="fas fa-copy"></i> Permalink</span>

        &nbsp;
        &#9679;
        &nbsp;
    

    <i class="fas fa-pencil-alt"></i>
    <span class="edit">





<a href="https://github.com/jasongaylord//JasonGaylord.com/edit/master/_posts/2020/05/2020-05-03-introducing-visual-studio-codespaces.md" target="_blank" title="Suggest an edit" aria-label="Suggest an edit" rel="noopener">suggest edit</a></span>
</div>
    </header>
  
    <div class="post-content e-content" itemprop="articleBody">
      <p>Technically, Visual Studio Codespaces has been around for several months. Back in November 2019, Visual Studio Online was announced. However, the name “Visual Studio Online” has lost its place in the Microsoft marketing repertoire for a second time. Visual Studio Online has recently been renamed to Visual Studio Codespaces.</p>

<p><img src="https://cdn.jasongaylord.com/images/2020/05/03/vscodespaces.png" alt="https://cdn.jasongaylord.com/images/2020/05/03/vscodespaces.png" /></p>

<p>Visual Studio Codespaces allows fully-managed on-demand development environments in Azure. Since the environments are fast to create and are easily disposable, adding environments for onboarding new team members or to bring on remote workers for projects has become a cinch. You can access the Codespaces using <a href="https://jasong.us/code">Visual Studio Code</a>, Visual Studio, or the Web editor.</p>

<p>Changing the name is not the only thing that Microsoft announced. In addition, they announced two other things:</p>

<ol>
  <li>There’s a <a href="https://jasong.us/3bVNKKP">new, basic instance</a> type at a cost point of just $0.08 US/hr. That means you’ll get two virtual cores, 4GB RAM, and 64GB SSD for your development machine. Along with this instance, they are dropping the prices of Standard (4 cores, 8GB RAM) and Premium (8 cores, 16GB RAM) to $0.17 US/hr and $0.34 US/hr respectively.</li>
  <li>You can now <a href="https://jasong.us/3d7Wnlo">bring your own machine</a> to Codespaces. That’s right, you can configure your own Dockerfile or image and deploy it to Visual Studio Codespaces for usage.</li>
</ol>

<p>Go ahead and try it for yourself. Visit <a href="https://jasong.us/2SrObEK">https://aka.ms/vso-login</a> to sign in and get started.</p>

    </div>

    <div class="meta">
<ul class="tags">

  <li><a href="/tags/#cloud" title="cloud" aria-label="cloud">cloud</a></li>

  <li><a href="/tags/#development" title="development" aria-label="development">development</a></li>

  <li><a href="/tags/#devops" title="devops" aria-label="devops">devops</a></li>
</ul>
</div>
  
    <div style="text-align:center; margin: 30px 0;">
        <div class="desktop ad" data-type="ad" data-publisher="lqm.jasongaylord.site" data-format="728x90" data-zone="post"></div>
        <div class="mobile ad" data-type="ad" data-publisher="lqm.jasongaylord.site" data-format="300x250" data-zone="post"></div>
    </div>

    
      
  

  <div id="disqus_thread"></div>
  <script>
    var disqus_config = function () {
      this.page.url = 'https://www.jasongaylord.com/blog/introducing-visual-studio-codespaces';
      this.page.identifier = 'https://www.jasongaylord.com/blog/introducing-visual-studio-codespaces';
    };

    (function() {
      var d = document, s = d.createElement('script');

      s.src = 'https://jasongaylord.disqus.com/embed.js';

      s.setAttribute('data-timestamp', +new Date());
      (d.head || d.body).appendChild(s);
    })();
  </script>
  <noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a></noscript>


    
  
    <a class="u-url" href="/blog/introducing-visual-studio-codespaces" hidden></a>
  </article>
</div>
      </section>
    </main>
  </body>
</html>

In this case, we’re including head.html within the HTML. We’re also pulling in a few variables.

Adding Style

We can add style a few different ways. One way we can add style is by adding CSS files directly into the assets folder and referencing those files in the head.html file like above. However, Jekyll also includes SASS support by default. So, we’ll start by adding a very basic style.scss style.scss file to the root of the assets directory. The purpose of this file is just to import our SASS. This will compile to the CSS file location referenced in the head.html file.

1
2
3
---
---
@import "default";

Next, we’ll add a default.scss file to the SASS folder. The contents of this SASS file, for now, will be static in nature. We can add the dynamic style rules at a later time.

1
2
3
4
5
body { font-family: Mate; margin: 0; padding: 0; }
h2, h3 { font-family: "Open Sans"; }
h3 { margin: 0; padding: 1em 0; }
.about { background-color: #336699; display: block; padding: 20px; text-align: center; color: #fff; }
.content { background-color: #f6f6f6; color: #333; padding: 20px; }

Next, let’s commit and push our changes. We’ll need to stop our Jekyll server by pressing Ctrl + C and hitting Y. Let’s rerun the build and serve process and navigate back to our website. We should notice a new look to our site:

https://cdn.jasongaylord.com/images/2020/05/04/BasicTheme-Snapshot.jpg

Updating the .gemspec, README.md, and more

At this point we’re on our way to create a nice looking Jekyll theme. Of course we’ll need to go back and update the includes, layouts, and SASS to provide our own look and feel for our theme. However, we cannot forget to perform the other due diligence of updating our .gemspec and README.md files. These files will help others benefit from the remote theme we are building. We could also take this a step further and build our theme as a gem accessible from the RubyGem library. The possibilities are really endless.

Recap

Hopefully you have a good idea how to head down the path of creating your first Jekyll theme. I’m interested in hearing what themes you’ve built. Use the comments found below to provide feedback and let me know what themes you’ve built so I can check them out myself.