First of all, some preparation steps are needed to step into the world of static websites and Jekyll. This tutorial is focussing mainly on Windows. For web servers, Windows for the OS is not the best choice for several reasons. But Windows is quite popular for Desktop Computers, the PC at home.
Jekyll, J1 Template, and all Tools needed are so-called multi-platform. That means you can use J1 on all popular platforms like Windows, Unix/Linux, or MacOS. This tutorial is focussing mainly on the Windows OS. For good reasons. Windows has a domain on Desktop Computers. Most PCs used at home for a Desktop system are running under the operating system (OS) Windows. Today mostly Windows 10.
We expect that for the testing platform, the Computer used for learning Jekyll and J1 a Windows-PC is preferred by most of our readers. Windows is a proprietary platform - far away from open and OpenSource. Sounds bad first place, but it is not.
The Windows OS does not provide any of the tools needed to create a Jekyll Web. That is different for Linux or other modern Unix OS (short: *nix) in general of today. Many tools are already installed on *nix based systems or available as (native) installation packages.
Why a hell is Windows a good choice for learning Jekyll and J1? That is because you need to start from the scratch! It is a bit more work upfront, sure. In the very end, you’ll learn much more about the world of OpenSource and what is Jekyll, J1, and Web Development all about.
All the software needed for this tutorial, and Jekyll/J1 in general, is available for the Windows OS for free. Multiple companies, thousands and thousands of private persons and projects contribute by their tools and software freely available to all of us on the Internet. Thanks a lot to all of them.
Using Windows for a web project is a sort of an oxymoron. A challenge sometimes. Anyway:
Let’s start and have fun!
The Hardware needed
For all Desktop Computers, a modern hardware is expected like so:
a multi-core CPU, >= Intel i5 or AMD Ryzen 5
8 GB of RAM, 3-4GB free RAM available
an Internet connection, bandwidth >= 16k (simple DSL)
a modern Monitor, Display size >= 21 inch
To develop a website, some power for the hardware is essential to be able to work fluidly. It is not fun to wait on the processing to finish a simple change on the web for ages.
To run multiple programs in different windows on a screen in parallel, a modern monitor is needed. It is possible to use a Laptop at 15 inches for the display, but expect difficulties.
The Software needed
In general, J1 is supported on all current x64-based OS:
Windows 10, build >= 1903
Windows WSL 2
Linux, kernel version >= 4.15 (e.g. Ubuntu 18.x LTS)
OSX, version >= 10.10.5 (Yosemite)
|Note that 32-bit versions (x32) are generally NOT supported for all platforms supported.|
|For the Windows platform, a current Windows 10 is expected. A Windows 7 OS will work, but is not tested.|
The base software to run Jekyll and J1 is:
Ruby is a dynamic, open-source programming language with a focus on simplicity and productivity. Jekyll, the core engine to create websites using J1, is written in Ruby. J1 Template is using Ruby as well to e.g implement (build-in) plugins.
The image below describes the general relationship of NodeJS and Ruby to work with J1 Template creating websites. From a top-level view, the development toolset is used in a row as an Input-Processing-Output scheme.
Input, commands to control a J1 project
Processing, site builders Jekyll and J1
Output, the website created
If NodeJS or Ruby is not already installed with your PC, continue on the following sections. You’ll find help about installing and check the toolset. If you’re unsure if or what versions of Ruby and/or NodeJS is already installed with your system, run a command shell (cmd.exe) and check the versions installed:
ruby --version && node --version
The required tool versions are:
Ruby: >= 2.6.x, < 3.x (1) NodeJS: >= 12.x, < 14.x (2)
|1||The latest version 3.x of the Ruby language is not supported by J1|
|2||NodeJS version 14.x is not supported by J1|
What versions should be installed?
All software used by J1 Template is in current, but well-known stable and secure versions. It is not always needed to use the very latest versions, especially for the development toolset. The development environment must meet the requirements for all components used for a project.
|Many private persons or smaller organizations develop OpenSource software. smaller organizations. A lot of OpenSource software is used by Jekyll and J1 under the hood. Great software, but quite often limited in terms of the development tool versions. New versions of development tools require changes for the code and already existing OpenSource software hasn’t implemented the needed changes for the latest versions yet. In the very end, those software components will issue warnings, fail or cause other issues that make a product unusable overall.|
Where to install the toolset?
The development system, the toolset, is a platform-specific compilation. The supported programming languages are multi-platform, the development tools are not! All tools to be installed on Windows are build for this platform to make it possible to run, for example, Ruby-based programs on Windows.
Most of the OpenSource software today has its roots in Linux. In relation to Windows, Linux-based platforms use a different scheme for the naming of directories and paths.
|A more detailed discussion for the naming schemes of directories and paths for several OS can be found on Wikipedia.|
On Windows, directories and paths typically contain whitespaces (blanks). This is much closer to a written human language but can cause some difficulties. The default folder for installing NodeJS on Windows is:
On Linux, directories and paths can contain whitespaces as well, but most files and folders do not use blanks for a path (or a filename):
I recommend installing only native Windows Applications under C:\Program Files. The development toolset is built for Windows, but for, sure they aren’t native to Windows. None of the tools having a Graphical User Interface (GUI). They are command-line tools running on a shell, not in a GUI.
It is recommended to use an installation folder without whitespaces. To make the toolset available for all users on Windows, simply install the tools under the root of the (first) hard disk C: like so:
Such will prevent you from having difficulties managing folder names that contain whitespaces, and the installation path is quite simple and easy to remember.
|You can always go for the default installation paths of a product on Windows. But all examples for this (and other) tutorials will use the recommended path for the J1 Template, not the default.|
If you decided to go for J1-Template recommended installation paths, create the root folder for the dev tools first. Open a command shell (cmd.exe) and run:
All tools used for the development environment will go to this folder.
What user can install software on Windows?
To install software on Windows, you’ll need administrative user rights to do so. That means only an elevated user account can install applications. That is quite the same for all OS, including Linux.
If you start an installation using an Installer provided for a product, this is done using the User Access Control (UAC) mechanism of Windows under the hood. To manage applications, for example, creating an install path at command-line (cmd.exe), you’ll need an administrative shell as well.
|Never change the security settings of any OS without the proper knowledge of what you’re doing. For the Windows OS, the pretty same and much more critical for a Desktop OS used by non-technical people. For most user activities on the Windows OS, using elevated system rights is not needed!|
How to run and use an elevated shell?
From time to time, it is needed to go for elevated system rights. To work with J1 Template, this is required for very seldom operations only and can be done from the command-line. If your UAC settings on Windows are correctly configured or not changed, all commands required are safe and won’t touch your system security by harmful side effects.
The easiest way to run an elevated shell is to create a shortcut for the shell cmd.exe on your Desktop. Give that shortcut administrative user rights to execute the command shell elevated.
First, do a right-click with the mouse on your Desktop. A dialog pop-up to create the new link.
For the first dialog window, give cmd for the program to be linked.
For the second dialog window, name the link cmd (elevated).
If the is link is created, configure the link properties to run cmd.exe elevated.
See the steps in a row from the screen-shots below.
From now on, an elevated command shell can be started using this link to cmd.exe. If this shortcut is clicked on, a UAC control dialog is issued to accept to run cmd.exe elevated.
Well done! All that is needed to be prepared for installing the development environment is done. Now, the toolset is to be installed!
The recommended path for J1 to install NodeJS is:
or a path reflecting the specific version (v12.22 for example) to be installed like so:
|1||Option 2, a folder link (junction) NodeJS pointing to the install folder should be created|
Creating the installation path
To prepare the installation, create the needed installation path first. Run an elevated command shell to create the directory for NodeJS needed.
If you decided on option 1:
cd C:\DevTools && md NodeJS
For option 2:
cd C:\DevTools && md NodeJS-v12.22.0-win-x64 && mklink /J NodeJS NodeJS-v12.22.0-win-x64
|In both cases, the install path is C:\DevTools\NodeJS. For option 2, additionally, a junction, a link for folders, has been created.|
If you open an explorer for the directory C:\DevTools, you’ll find the install folder for NodeJS created.
If you decided to go for option 2, the folder link (junction) is available and pointing to the directory reflecting the NodeJS version to be installed. Next, the installer for NodeJS is to be downloaded. The recommended version (latest v12) for J1 is available from the link:
or for all available NodeJS versions from:
Run the NodeJS installer
If you decided to go for the recommended version, a browser window is opened, and the download starts immediately. The installer node-v12.22.0-x64.msi will be downloaded to the default location Download for Windows. If the download is finished, you can start the installer directly from your browser or the download folder Download. See the installing steps from the screenshots below.
In step 5, you’re requested to install the toolset for NodeJS. These tools are not required for Jekyll or J1 and should not be installed to reduce the installation’s complexity.
Chocolatey is a package manager to manage and automate installations of OpenSource packages/applications on Windows. That might be an option if many software packages from this world need to be installed on Windows quite often.
Install/Update the package managers for NodeJS
NodeJS comes with the package manager NPM pre-installed. The native CLI for the NodeJS package management is
npm there’s another quite handy CLI for NPM available: Yarn.
yarn is developed at Facebook and can be used as a replacement for
npm. From a top-level perspective, both package management clients behave pretty much the same. The syntax
yarn uses is shorter in writing, making the command-line look a bit more natural. Therefore, the use of
yarn is preferred over
|Yarn adds some additional features to the NodeJS package management implemented for the needs at Facebook. Regarding the J1 development system, those add-ons are neither needed nor used.|
Install the latest NPM and Yarn packages for NodeJS:
npm install -g npm@latest (1) npm install -g yarn@latest
|1||The package managers npm and yarn are installed globally (-g)|
The needed software to manage J1 projects is in place. Next, the Ruby language is to be installed to run Jekyll. Go next for Installing Ruby.
The procedure to install Ruby is quite similar to install NodeJS. Because the steps are quite the same, the description is a bit more compact, skipping some parts you already know to not bother you by the same again.
The recommended path for J1 to install Ruby is:
or a path reflecting the specific version (v72 for example) to be installed like so:
Creating the installation path
To prepare the installation, create the needed installation path first. Run an elevated command shell to create the directory for Ruby.
cd C:\DevTools && md Ruby
cd C:\DevTools && md Ruby27-x64 && mklink /J Ruby Ruby27-x64
Next, the installer for Ruby is to be downloaded. The recommended version (latest Ruby v2) for J1 is available from the link:
or for all available Ruby versions from:
The development kit (DevKit) to build platform-specific Ruby modules (libraries) is needed for Jekyll and J1. This is a quite simple process to install, with no headache as for NodeJS.
Run the installer
If you decided to go for the recommended version, a browser window is opened, and the download starts immediately. The installer rubyinstaller-devkit-2.7.2-1-x64.exe will be downloaded to the default location Download for Windows. If the download is finished, you can start the installer directly from your browser or the download folder Download. See selected installing steps from the screenshots below.
|For the last step of the Ruby installation, use option 3 to install the full set of DevKit applications for Windows. To finish this install step, simply press the Return-key.|
Yeah, you finished the heavy part of setting up your development environment to run J1! From now on, no more cumbersome installations are needed. Now, you can smoothly step into the world of Jekyll using J1 doing this the simple way.
Installing J1 Template
The Template system J1 is a Ruby GEM, a so-called GEM-based template for Jekyll.
|Ruby GEMs, called Rubies sometimes, are libraries - or more general modules, to extend the Ruby language. All programming languages support a concept to extend the base functionality by modules (libraries). That is the same for Ruby. Besides system GEMs (libraries), user-defined modules are playing an important role in programming applications. Thousands of people around the world support the Ruby language by user-defined modules be (re-)used. No wonder Jekyll and J1 are using a bunch of those GEMs: to not re-invent a wheel!|
In general, the tool to install Ruby GEMs (modules) is the command gem, the package manager utility for Ruby. All modern programming languages support a marketplace to get available user-defined modules from the Internet. For Ruby, this marketplace is RubyGems.
Installing GEMs (modules/libraries) for Ruby raises an important question to be answered upfront the installation: where to install libraries used to extend a programming language? This open question is quite the same for all programming languages, not specific for Ruby.
You’ve experienced that installing a programming language will need elevated user rights (on Windows: think about UAC) to do so. The reason is, this installation provides access for all users of a system. Vice versa, this raises the questions what libraries:
are need for all users
are needed for a specific user or application
J1 and Jekyll are great software, no doubt. But for sure, they are used typically in a user context, not system-wide. For this reason, J1 should be installed for a user, not globally (system-wide) for the Ruby language.
|Installing Ruby GEMs system-wide will always need elevated user rights. This is annoying, but prevents a system-wide installation to be polluted by software components not needed in general.|
Installing J1 can be done in a user context (userized), but system-wide as well. In most cases, an installation in a user context is the better choice to install Ruby GEMs for Jekyll and J1.
gem install j1-template --user-install (1) gem install j1-template (2)
|1||Option 1, installing userized (default)|
|2||Option 2, installing system-wide|
Installing J1 Template userized
It is highly recommended to install J1 and Jekyll userized. This tutorial is based on an userized installation. A system-wide installation will need some additional steps in terms of configuring J1 what is not discussed. In other words: expect difficulties to manage Jekyll and J1 if you decided to install differently.
To install J1, an elevated shell is not needed. To run the installation, close the administrative shell and open an unprivileged shell by running cmd.exe.
gem install j1-template --user-install --no-document (1)
|1||Installing the full documentation is not needed for the J1 runtime-system to develop websites|
Installing the J1-Template GEM will take a while. A significant number of modules (about 60) used by Jekyll and J1 will be download, installed, and configured.
A summary of the responses while installing is shown below:
WARNING: You don't have c:\users\<user_name>\.gem\ruby\2.7.0\bin in your PATH, gem executables will not run. Fetching public_suffix-4.0.6.gem ... Successfully installed bump-0.10.0 60 gems installed
|Downloading and installing the entire chain of depending GEMs are only done once.|
Adjust your environment
An important notice in your command shell while installing J1 was:
WARNING: You don't have c:\users\<user_name>\.gem\ruby\2.7.0\bin in your PATH, gem executables will not run.
|On Windows, a set of general environment variables are set automatically for you: %HOMEDRIVE and %HOMEPATH%, for example. These variables are used to manage the access to applications by users.|
A userized installation will install all GEMs with the user’s home directory. For full access to all resources of your userized GEMs, your environment needs to be extended to the installation for the GEMs binary path:
|1||It is expected that Ruby v27 has been installed. If version v26 was used, the path is %HOMEDRIVE%%HOMEPATH%\.gem\ruby\2.6.0\bin|
|The module concept of Ruby is different in comparison to other programming languages. For Ruby, a GEM can contain command-line interfaces (CLI, commands) to access higher-level functionality. Jekyll and J1 use that to provide the CLI commands jekyll and j1.|
To adjust your environment, to have full access to userized GEMs, add the installation (binary) path to your environment. To adapt your environment, run in a command shell:
and add a new variable:
to your environment. See all steps summarized by the following screenshots:
Check your environment
If you have extended your environment for the userized GEM path, run:
where jekyll && where j1
To list the versions installed, the command below can be used:
jekyll --version && j1 --version
The current versions (of April 2021) are:
jekyll 4.2.0 j1 2021.1.0
What a procedure! Yes, sure. And most of you haven’t expected that - guessed. See it as a piece of advice: installing the software you’ve never seen before or installed on an unknown platform, it makes sense to know what needs to be done in more detail. And it is required to verify if the installation was successful and gives results for their (installation) locations respectively the versions as expected.
Installing an Code Editor
Creating websites using J1, a good source code editor is needed. If you are using a code editor already, you can skip this section. Go for your favorite editor.
If you haven’t used a source code editor, two of them can recommend. Both are Open-Source-Software, can be used for free:
Visual Studio (VS) Code Editor
VS Code Editor is well-known from the world of Windows development and provided by Microsoft. VS Code is independend from a Microsoft Visual Studio development environment, multi-platform, and can be used standalone. Atom is a free and multi-platform editor as well, originally developed by Github (Github today owned by Microsoft):
VS Code Editor is a multi-platform, well-known editor for Windows development provided by Microsoft but independent from a Microsoft development environment (Visual Studio).
Atom is a free and multi-platform editor, initially developed by Github (but owned today by Microsoft).
Both editors are using Electron as a base and are comparable by their features. VS Code Editor is closer to the Windows world in terms of available Windows-specific extensions, Atom more popular in the world of OpenSource providing a large number of extensions this world.
A source code editor is a crucial tool but should meet what developers like to use. But this depends on what is preferred, what the developer support at its best. Therefore what editor should be used cannot be answered in general. It depends on personal preferences rather than on the features an editor provides.
It is up to you what code editor to use. Try the editors available on the market and decide what editor fits your needs. Find the download page for Atom and VS Code below.
The following questions will help you review this chapter for the essential topics for better learning success.
First, answer the questions on paper. Before you look up an answer, take some time to answer the question yourself. If you find it challenging to find the correct answers, refer to the previous sections.
Clicking the link on the question number will open a new page (tab) in your web browser and point you to the answer. This page helps to navigate to the questions by a table of content (TOC). Go for the question number or the chapter title.
|If you finished the questions section, you could close the browser windows (tabs) opened for answers or questions and continue on this page for the next section.|
What user can install software on Windows?
For Ruby, GEMs (libraries) can be installed system-wide or userized. What are the differences?
If Ruby GEMs are installed userized, what is to be considered to make userized GEMs fully accessible?
A lot you’ve learned, time to summarize what is in behind. The last chapter Summarize! should help on that. Summarize! offer some handy sections to remember what was presented, giving an outlook what could be done next. This section provides an overview on all chapters this tutorial and finally useful links to read more.
See all sections below:
Recap — What has been done, what’s explored in current section
Whats Next — Find to go further, what’s planned next
All Chapters — The full chain, all chapters
Further Reading — List of helpful links to get more
Installing the development environment was not an easy job, many things to consider. If you install the software you’ve never seen before, it makes sense to know what needs to be done in more detail. And it is required to verify if the installation was successful and gives results for their (installation) locations respectively the versions as expected. You’ve learned that elevated user rights are needed to install the software (system-wide) but not needed to run, to use an application!
Especially for development tools, some more questions came up in terms of the libraries to be installed. All modern dynamic programming languages like NodeJS, Ruby, or Python support the extending their functionality by the system- and user-defined modules.
System modules are to be installed with the installation path of the main application. This install type is called global. You’ve seen that this is not always a good choice for user-defined libraries. The install type for user-defined modules is called local if those modules are not installed system-wide.
NodeJS and Ruby support different strategies to install modules locally. Two of them are:
You’ve learned for Ruby, the default installation type for GEMs is global. Still, in many cases, it makes sense to install GEMs userized to not pollute the central installation by libraries not needed globally. NodeJS has a different approach for installing modules: vendorized for default. That means the modules are installed within the project folder.
Library folder hierarchy
Library folders build a hierarchy. A search path is needed to locate a module along this hierarchy to get access to these resources. For Ruby GEMs, the decision to install J1 and Ruby GEMs was userized. The user environment was adjusted to locate the (Ruby) main installation path (system modules) and the user’s path to get full access to all GEMS installed userized.
For NodeJS, no adjustments are needed because, for default, the project path is used. If you run commands later on to control a J1 project, you will do this out of the project path. This will implicitly set the vendorized path to the current (project) path.
Almost all of the technical stuff is behind you. The following section, First awesome Web, is much more related to what the title of this tutorial implies: Web in Day.
Create from here your First awesome Web!
Find here an overview on all chapters this tutorial.
Find from here some interesting links to additional sources of information for further reading. It’s not needed to go for all the pages, but the links will give some more background provided by other people, what they do, and what other experts have on their minds.