Welcome to learn how to setup a development environment for Jekyll and J1 Theme to manage and create your first website locally on your PC in minutes. J1 Theme comes with a built-in Web, a skeleton for a new website. This site is called the Starter Web, a general-purpose scaffold. The Starter Web is a good base for modifying a new website for your personal needs.
The live version of the built-in Starter web is available at the home page of JekyllOne under the menu Examples. A Starter web is created in minutes but requires a development environment in place for Jekyll and J1 Theme.
The Software needed
The Jekyll Theme JekyllOne 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. |
Development languages and tools
To run the Development System for J1 Theme, the following languages and tools expected to be in place with your OS:
-
Ruby language, version >= 2.6
-
Javascript language (NodeJS), version >= 12.x
| More current or older versions may work, but not tested. |
Software upgrades needed for all platforms
If Ruby and NodeJS are in place, some packages needs to be upgraded to more current versions. Install all packages system-wide with their respective product installation paths.
Upgrades needed for Ruby < v2.7
Install latest bundler for Ruby:
gem install bundler --no-documentInstall latest RubyGems for Ruby:
gem install rubygems-update --no-document
update_rubygems --no-document
gem update --systemUpgrades needed for NodeJS
NodeJS comes with NPM pre-installed. The native CLI for the NodeJS package management is npm. Besides npm there’s another quite handy CLI for NPM available: yarn.
The CLI 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, we prefer to use yarn.
| 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 latest NPM and Yarn packages for NodeJS:
npm install -g npm@latest
npm install -g yarn@latestCreate a Starter Web
Running the J1 Theme project is very simple:
-
Download the JekyllOne Gem
-
Create a JekyllOne web project
-
Setup the runtime environment for your project
-
Run and develop the buildin starter web
Find all details on this with the sections below.
Download the JekyllOne Gem
The Gem for J1 Theme (runtime system) is published on RubyGems. You can get it by installing the package using the Ruby gem command or by downloading it from RubyGems.
gem install j1-template --remote --user-install --no-documentgem install j1-template --remote --no-document| To not pollute the system-wide Gem folder of a Ruby-installation by user and project specific Gems, it is recommend to install the gem for J1 Theme userized. |
J1 Theme is a so-called gem-based theme, a Ruby Gem managed by the (gem) internal executeable (command) j1. Check your version installed or some usage information by running:
j1 --versionj1 --helpSetup a project
Is the Ruby Gem j1-template installed, a project, a website needs to be generated by gem’s build-in executable j1. The command j1 is used to manage base project tasks like generating a project.
If a project (a website) is generated, all development tasks are managed by NPM scripts (NodeJS). Development tasks are defined as scripts with the project config file package.json.
First, create a projects folder for all websites to be generated for JekyllOne. For the following examples, a project is generated on Windows using C:\Temp for the project’s folder.
j1 generate starterYYYY-MM-DD hh:mm:ss - GENERATE: Running bundle install in C:/Temp/starter ... YYYY-MM-DD hh:mm:ss - GENERATE: Install bundle in USER gem folder ~/.gem ... YYYY-MM-DD hh:mm:ss - GENERATE: Fetching gem metadata from https://rubygems.org/.......... YYYY-MM-DD hh:mm:ss - GENERATE: Resolving dependencies... YYYY-MM-DD hh:mm:ss - GENERATE: Using bundler 2.3.22 ... YYYY-MM-DD hh:mm:ss - GENERATE: Using nokogiri-pretty 0.1.0 YYYY-MM-DD hh:mm:ss - GENERATE: Bundle complete! 30 Gemfile dependencies, 79 gems now installed. YYYY-MM-DD hh:mm:ss - GENERATE: Bundled gems are installed into `C:/Users/xyz/.gem` YYYY-MM-DD hh:mm:ss - GENERATE: C:/Users/xyz/.gem/ruby/3.1.0;C:/DevTools/Ruby31-x64/lib/ruby/gems/3.1.0; YYYY-MM-DD hh:mm:ss - GENERATE: Install patches in USER gem folder ~/.gem ... YYYY-MM-DD hh:mm:ss - GENERATE: Install patches on path C:/Users/xyz/.gem/ruby/3.1.0 ... YYYY-MM-DD hh:mm:ss - GENERATE: Patches already installed, skip install. YYYY-MM-DD hh:mm:ss - GENERATE: Generated Jekyll site installed in folder C:/Temp/starter YYYY-MM-DD hh:mm:ss - GENERATE: To setup the site, change to the project folder C:/Temp/starter and run: j1 setup
Setup the runtime
The command j1 generate creates a project folder with the name given. In this example, the project is starter. Change to this folder
cd C:\Temp\starterA J1 project consists in several files and folders. Find a typical structure as below:
├──── . │ └─ _data (1) │ └─ _includes (2) │ └─ _plugins (3) │ └─ assets (4) │ └─ collections (5) │ └─ pages (6) │ └─ utilsrv ├──── _config.yml (7) ├──── config.ru ├──── dot.gitattributes ├──── dot.gitignore ├──── dot.nojekyll ├──── favicon.ico ├──── Gemfile (8) ├──── index.html (9) └──── package.json (10)
| 1 | Configuration data for the website |
| 2 | Asciidoc (global) includes |
| 3 | Build-in (Ruby) plugins |
| 4 | Assets for the web |
| 5 | Folder that contains all blog posts |
| 6 | Folder that contains all (article) pages |
| 7 | Central (Jekyll) site configuration |
| 8 | Ruby Gemfile |
| 9 | Homepage for the web |
| 10 | (NPM) Project file |
The first step, done only once, is to initialize a project. What means to download and install all resources for your new website followed by an initial creation process for the new site. Initializing a project is managed by the (NPM) task setup. A bunch of sub-tasks gets fired, all of them managed by NPM.
Let’s start …
j1 setupBecause a lot of sub-tasks getting started for a (first) setup, see below the output as a summary:
Check consistency of the J1 project ... YYYY-MM-DD hh:mm:ss - SETUP: Running bundle install in C:/Temp/starter ... YYYY-MM-DD hh:mm:ss - SETUP: Install bundle in USER gem folder ~/.gem ... YYYY-MM-DD hh:mm:ss - SETUP: Using public_suffix 5.0.1 ... YYYY-MM-DD hh:mm:ss - SETUP: Using wdm 0.1.1 YYYY-MM-DD hh:mm:ss - SETUP: Bundle complete! 30 Gemfile dependencies, 79 gems now installed. YYYY-MM-DD hh:mm:ss - SETUP: Bundled gems are installed into `C:/Users/xyz/.gem` YYYY-MM-DD hh:mm:ss - SETUP: Install patches in USER gem folder ~/.gem ... YYYY-MM-DD hh:mm:ss - SETUP: Install patches on path C:/Users/xyz/.gem/ruby/3.1.0 ... YYYY-MM-DD hh:mm:ss - SETUP: Initialize the project ... YYYY-MM-DD hh:mm:ss - SETUP: Be patient, this will take a while ... YYYY-MM-DD hh:mm:ss - SETUP: YYYY-MM-DD hh:mm:ss - SETUP: > j1@2023.0.8 setup C:/Temp/starter YYYY-MM-DD hh:mm:ss - SETUP: > npm --silent run setup-start && npm --silent run setup-base && run-s -s setup:* YYYY-MM-DD hh:mm:ss - SETUP: YYYY-MM-DD hh:mm:ss - SETUP: Setup project for first use .. YYYY-MM-DD hh:mm:ss - SETUP: Bootstrap base modules .. YYYY-MM-DD hh:mm:ss - SETUP: done. YYYY-MM-DD hh:mm:ss - SETUP: Configure environment .. YYYY-MM-DD hh:mm:ss - SETUP: done. YYYY-MM-DD hh:mm:ss - SETUP: Create project folders .. YYYY-MM-DD hh:mm:ss - SETUP: Create log folder .. YYYY-MM-DD hh:mm:ss - SETUP: Create archived log folder .. YYYY-MM-DD hh:mm:ss - SETUP: Create etc folder .. YYYY-MM-DD hh:mm:ss - SETUP: done. YYYY-MM-DD hh:mm:ss - SETUP: Bootstrap project modules .. YYYY-MM-DD hh:mm:ss - SETUP: Bootstrap utility server modules .. YYYY-MM-DD hh:mm:ss - SETUP: done. YYYY-MM-DD hh:mm:ss - SETUP: Detect OS .. YYYY-MM-DD hh:mm:ss - SETUP: OS detected: Windows_NT ... YYYY-MM-DD 1hh:mm:ss - SETUP: Build site incremental .. YYYY-MM-DD hh:mm:ss - SETUP: Configuration file: C:/Temp/starter/_config.yml YYYY-MM-DD hh:mm:ss - SETUP: Source: C:/Temp/starter YYYY-MM-DD hh:mm:ss - SETUP: Destination: C:/Temp/starter/_site YYYY-MM-DD hh:mm:ss - SETUP: Incremental build: enabled YYYY-MM-DD hh:mm:ss - SETUP: Generating... YYYY-MM-DD hh:mm:ss - SETUP: J1 Lunr: enabled YYYY-MM-DD hh:mm:ss - SETUP: J1 Lunr: generate search index YYYY-MM-DD hh:mm:ss - SETUP: J1 Feeds: enabled YYYY-MM-DD hh:mm:ss - SETUP: J1 Feeds: generate rss feeds for: excerpts only YYYY-MM-DD hh:mm:ss - SETUP: J1 Feeds: generate rss feeds for: #posts of unlimited YYYY-MM-DD hh:mm:ss - SETUP: J1 Feeds: generate rss feeds for: all posts YYYY-MM-DD hh:mm:ss - SETUP: J1 SEO Tags: enabled YYYY-MM-DD hh:mm:ss - SETUP: J1 SEO Tags: generate seo tags YYYY-MM-DD hh:mm:ss - SETUP: J1 Sitemap: enabled YYYY-MM-DD hh:mm:ss - SETUP: J1 Sitemap: generate sitemap files YYYY-MM-DD hh:mm:ss - SETUP: J1 Paginator: enabled YYYY-MM-DD hh:mm:ss - SETUP: J1 Paginator: generate auto pages: disabled YYYY-MM-DD hh:mm:ss - SETUP: J1 Paginator: generate paginator pages: enabled YYYY-MM-DD hh:mm:ss - SETUP: J1 Paginator: generate paginator pages: 2 page|s generated YYYY-MM-DD hh:mm:ss - SETUP: done in 51.564 seconds. YYYY-MM-DD hh:mm:ss - SETUP: Auto-regeneration: disabled. Use --watch to enable. YYYY-MM-DD hh:mm:ss - SETUP: .. build finished. YYYY-MM-DD hh:mm:ss - SETUP: Initializing the project finished successfully. YYYY-MM-DD hh:mm:ss - SETUP: To open your site, run: j1 site
The setup process will take a while. Typically some minutes for the first run, depending on your Internet connection bandwidth and the workstation performance. Many NPM modules and Ruby Gems are downloaded and linked for the components part of the project. See setup as an extended install and build process to manage your new website’s initial setup.
Run and develop a starter web
Running the Starter Web for development is done like so:
yarn siteThe task site does a lot for you; whatever is necessary for a full-stack Web development. The task will put in place all needed CSS and JS components, build the Web content.
Check consistency of the J1 project ... Check setup state of the J1 project ... YYYY-MM-DD hh:mm:ss - SITE: Starting up your site ... YYYY-MM-DD hh:mm:ss - SITE: YYYY-MM-DD hh:mm:ss - SITE: > j1@2023.0.8 j1-site C:/Temp/starter YYYY-MM-DD hh:mm:ss - SITE: > run-p -s j1-site:* .. YYYY-MM-DD hh:mm:ss - SITE: Configuration file: C:/Temp/starter/_config.yml YYYY-MM-DD hh:mm:ss - SITE: Source: C:/Temp/starter YYYY-MM-DD hh:mm:ss - SITE: Destination: C:/Temp/starter/_site YYYY-MM-DD hh:mm:ss - SITE: Incremental build: enabled YYYY-MM-DD hh:mm:ss - SITE: Generating... YYYY-MM-DD hh:mm:ss - SITE: J1 Lunr: enabled YYYY-MM-DD hh:mm:ss - SITE: J1 Lunr: generate search index YYYY-MM-DD hh:mm:ss - SITE: J1 Feeds: enabled YYYY-MM-DD hh:mm:ss - SITE: J1 Feeds: generate rss feeds for: excerpts only YYYY-MM-DD hh:mm:ss - SITE: J1 Feeds: generate rss feeds for: #posts of unlimited YYYY-MM-DD hh:mm:ss - SITE: J1 Feeds: generate rss feeds for: all posts YYYY-MM-DD hh:mm:ss - SITE: J1 SEO Tags: enabled YYYY-MM-DD hh:mm:ss - SITE: J1 SEO Tags: generate seo tags YYYY-MM-DD hh:mm:ss - SITE: J1 Sitemap: enabled YYYY-MM-DD hh:mm:ss - SITE: J1 Sitemap: generate sitemap files YYYY-MM-DD hh:mm:ss - SITE: J1 Paginator: enabled YYYY-MM-DD hh:mm:ss - SITE: J1 Paginator: generate auto pages: disabled YYYY-MM-DD hh:mm:ss - SITE: J1 Paginator: generate paginator pages: enabled YYYY-MM-DD hh:mm:ss - SITE: J1 Paginator: generate paginator pages: 2 page|s generated YYYY-MM-DD hh:mm:ss - SITE: done in 11.682 seconds. YYYY-MM-DD hh:mm:ss - SITE: Auto-regeneration: enabled for '.' YYYY-MM-DD hh:mm:ss - SITE: LiveReload address: http://localhost:35729 YYYY-MM-DD hh:mm:ss - SITE: Server address: http://localhost:20000/ YYYY-MM-DD hh:mm:ss - SITE: Server running... press ctrl-c to stop. YYYY-MM-DD hh:mm:ss - SITE: LiveReload: Browser connected
Finally, the starter web get automatically openend in your default browser from http://localhost:20000/.
Go, go, go ..
Rebuild a site
A project runs Jekyll in incremental mode with auto-regeneration enabled. All changes made to your web’s pages and posts at runtime are automatically detected, and the affected pages are rebuilt and automatically reloaded with your browser.
For rebuilding a site from scratch, a web can be completely rebuilt by running the task rebuild:
j1 rebuildREBUILD: Rebuild the projects website ... REBUILD: Be patient, this will take a while ... YYYY-MM-DD hh:mm:ss - REBUILD: YYYY-MM-DD hh:mm:ss - REBUILD: > j1@2023.0.8 rebuild C:/Temp/starter YYYY-MM-DD hh:mm:ss - REBUILD: > run-s -s rebuild:* && run-s -s post-rebuild:* YYYY-MM-DD hh:mm:ss - REBUILD: YYYY-MM-DD hh:mm:ss - REBUILD: Rebuild site incremental .. YYYY-MM-DD hh:mm:ss - REBUILD: Clean up site files .. YYYY-MM-DD hh:mm:ss - REBUILD: Configuration file: C:/Temp/starter/_config.yml YYYY-MM-DD hh:mm:ss - REBUILD: Cleaner: Removing _site... YYYY-MM-DD hh:mm:ss - REBUILD: Cleaner: Removing ./.jekyll-metadata... YYYY-MM-DD hh:mm:ss - REBUILD: Cleaner: Removing ./.jekyll-cache... YYYY-MM-DD hh:mm:ss - REBUILD: Cleaner: Nothing to do for .sass-cache. YYYY-MM-DD hh:mm:ss - REBUILD: Configuration file: C:/Temp/starter/_config.yml YYYY-MM-DD hh:mm:ss - REBUILD: Source: C:/Temp/starter YYYY-MM-DD hh:mm:ss - REBUILD: Destination: C:/Temp/starter/_site YYYY-MM-DD hh:mm:ss - REBUILD: Incremental build: enabled YYYY-MM-DD hh:mm:ss - REBUILD: Generating... YYYY-MM-DD hh:mm:ss - REBUILD: J1 Lunr: enabled YYYY-MM-DD hh:mm:ss - REBUILD: J1 Lunr: generate search index YYYY-MM-DD hh:mm:ss - REBUILD: J1 Feeds: enabled YYYY-MM-DD hh:mm:ss - REBUILD: J1 Feeds: generate rss feeds for: excerpts only YYYY-MM-DD hh:mm:ss - REBUILD: J1 Feeds: generate rss feeds for: #posts of unlimited YYYY-MM-DD hh:mm:ss - REBUILD: J1 Feeds: generate rss feeds for: all posts YYYY-MM-DD hh:mm:ss - REBUILD: J1 SEO Tags: enabled YYYY-MM-DD hh:mm:ss - REBUILD: J1 SEO Tags: generate seo tags YYYY-MM-DD hh:mm:ss - REBUILD: J1 Sitemap: enabled YYYY-MM-DD hh:mm:ss - REBUILD: J1 Sitemap: generate sitemap files YYYY-MM-DD hh:mm:ss - REBUILD: J1 Paginator: enabled YYYY-MM-DD hh:mm:ss - REBUILD: J1 Paginator: generate auto pages: disabled YYYY-MM-DD hh:mm:ss - REBUILD: J1 Paginator: generate paginator pages: enabled YYYY-MM-DD hh:mm:ss - REBUILD: J1 Paginator: generate paginator pages: 2 page|s generated YYYY-MM-DD 19:07:57 - REBUILD: done in 50.001 seconds. YYYY-MM-DD 19:07:57 - REBUILD: Auto-regeneration: disabled. Use --watch to enable. YYYY-MM-DD 19:07:57 - REBUILD: .. rebuild finished. REBUILD: The projects website has been rebuild successfully. REBUILD: To open the site, run: j1 site
If the site rebuild, re-run:
yarn siteand continue developing your website.
Reset a project
To start from the beginning, you can reset the runtime system to the factory state. The top-level task reset does the resetting work for you and cleans up each and everything except the NPM modules folder node_modules stored in the project root.
j1 resetThe cleanup runs some tasks for the root folder and in parallel sub-tasks using Jekyll for the Web:
Check consistency of the J1 project ... Check setup state of the J1 project ... YYYY-MM-DD hh:mm:ss - RESET: Reset the project to factory state ... YYYY-MM-DD hh:mm:ss - RESET: Be patient, this will take a while ... YYYY-MM-DD hh:mm:ss - RESET: YYYY-MM-DD hh:mm:ss - RESET: > j1@2023.0.8 reset C:/Temp/starter YYYY-MM-DD hh:mm:ss - RESET: > run-s -s reset:* YYYY-MM-DD hh:mm:ss - RESET: YYYY-MM-DD hh:mm:ss - RESET: Reset project to factory state .. YYYY-MM-DD hh:mm:ss - RESET: Clean up base modules .. YYYY-MM-DD hh:mm:ss - RESET: Clean up site files .. YYYY-MM-DD hh:mm:ss - RESET: Configuration file: C:/Temp/starter/_config.yml YYYY-MM-DD hh:mm:ss - RESET: Cleaner: Removing _site... YYYY-MM-DD hh:mm:ss - RESET: Cleaner: Removing ./.jekyll-metadata... YYYY-MM-DD hh:mm:ss - RESET: Cleaner: Removing ./.jekyll-cache... YYYY-MM-DD hh:mm:ss - RESET: Cleaner: Nothing to do for .sass-cache. YYYY-MM-DD hh:mm:ss - RESET: Clean up projects files .. YYYY-MM-DD hh:mm:ss - RESET: Remove bundle config folder .. YYYY-MM-DD hh:mm:ss - RESET: Remove log folder .. YYYY-MM-DD hh:mm:ss - RESET: Remove etc folder .. YYYY-MM-DD hh:mm:ss - RESET: Remove various log files .. YYYY-MM-DD hh:mm:ss - RESET: Remove lock files .. YYYY-MM-DD hh:mm:ss - RESET: Clean up utility server .. YYYY-MM-DD hh:mm:ss - RESET: done. YYYY-MM-DD hh:mm:ss - RESET: The project reset finished successfully. YYYY-MM-DD hh:mm:ss - RESET: To setup the project, run: j1 setup
To reset the project completely, delete the folder node_modules manually and start from the beginning by running the setup task again:
j1 setupIf the project is newly setup, re-run:
j1 siteand continue developing your website.
Happy Jekylling!