Jekyll was first released in 2008 by Tom Preston-Werner, one of the co-founders of GitHub. Today the project is led by Parker Moore together with a motivated team. Jekyll is a tool written in the Ruby programming language. It builds static websites from a few simple ingredients: templates, partials, Liquid tags, and markup files such as Asciidoc or Markdown.

Jekyll is delivered as a Ruby gem — that is the standard packaging format for Ruby libraries. The same gem can be used on the command line as a stand-alone program, or it can be integrated into a larger Ruby application. Inside J1, Jekyll is the central tool that generates every page of your website.

To produce the final HTML, Jekyll reads your content (written in Asciidoc or Markdown) and combines it with shared page parts (written using the Liquid templating language). The result is a complete website ready to be served by any web server. Because Jekyll does not use a database to build pages on demand, the term static is sometimes misleading: you can still load data into your pages, but the data comes from simple files in standard formats such as YAML, JSON, CSV, or TSV.

A CMS (Content Management System) is a software application for creating and publishing digital content. When the content in question is a website, the system is usually called a Web CMS (WCMS). Well-known examples are WordPress, Joomla, and Drupal.

A WCMS lets several people create, edit, and publish website pages from one shared place. This central approach is a big advantage for large web projects such as enterprise sites. It does, however, require a substantial software stack on the server: a database to store the pages and a rendering engine to turn database records into HTML on demand.

J1 Theme (or just J1) is a boilerplate for websites built with Jekyll. Although the underlying delivery model is static — every page is a real HTML file prepared in advance — J1 websites feel dynamic to visitors. This combination is the heart of the JAMstack approach.

On one hand, a J1 site is a pure static site: a folder of HTML files plus supporting assets (JavaScript, CSS, images, fonts) that any web server can hand out directly. On the other hand, J1 has no moving server-side parts. There is no PHP, no database, and no rendering engine waiting on the server to assemble pages.

Everything dynamic in a J1 site comes from JavaScript running in the visitor’s browser and from external APIs called from that JavaScript. The Jekyll build step prepares all of these JAM components (JavaScript, APIs, Markup) ahead of time. The result is a website that loads quickly and behaves like a modern web app.

Netlify provides everything you need to host fast, modern websites built by static site generators like Jekyll (and many others such as Next.js, Hugo, Gatsby, and 11ty). The platform offers powerful features such as continuous deployment and serverless functions — features that make a real difference to the quality of your website.

Netlify is one option for putting a J1-based website on the Internet. Running a site on Netlify is easy to manage, very fast, and free for most small to medium sites.

GitHub is a code hosting platform that uses the version-control system Git to track and manage source files. It lets developers, writers, and other contributors work together on projects from anywhere in the world. Millions of developers and companies build, ship, and maintain their software on GitHub every day.

Jekyll is also the engine behind GitHub Pages, a free GitHub service that hosts websites directly from a GitHub repository. J1-based projects are typically tracked with Git, so storing them on GitHub is a natural fit — especially for public projects and small teams.

The JAMstack is a way of building websites and web applications using three ingredients: JavaScript, APIs, and Markup. At first that sounds trivial — after all, most modern web technologies use some of these. The point of the JAMstack is how the three are combined, not that they are involved.

JAMstack is a philosophy or approach, not a specific software bundle. It does not require any particular tool. In that respect it is different from something like the LAMP Stack, which names exact technologies (Linux, Apache, MySQL, PHP). The JAMstack just describes how you build a site, not which tools you must use.

To follow this chapter, you need free accounts with two service providers: GitHub and Netlify. Together they let you build and host a J1 website on the Internet. Both providers offer a free tier that is more than enough for this tutorial.

If you do not have these accounts yet, sign up now:

The Netlify team has built a very simple process that takes a JAMstack template like J1 and turns it into a live website on the Internet in just a few minutes. It really only takes one click — Netlify handles the rest.

The 1-Click Deployment button opens a new browser tab. The deployment process itself is explained step by step in the Deployment Reference section. To follow along easily, place your two browser windows side by side: this tutorial in one, and the Netlify deployment in the other.

Ready? Click the button below to start the deployment on Netlify.

Any reasonably modern desktop or laptop computer will do. As a guideline, a typical setup looks like this:

You don’t need top-of-the-line hardware, but a reasonably fast computer makes the work much more pleasant. You don’t want to wait long every time you save a change. A larger monitor is helpful too, because you will often have a code editor, a terminal, and a browser open side by side.

A laptop with a 15-inch screen can work, but expect to switch between windows more often than you would on a larger screen.

To manage J1 projects you will run a few commands in a shell (Windows calls this the command prompt). The easiest way to open a shell on Windows is to put a shortcut to cmd.exe on your desktop.

The screenshots below show each step in detail.

From now on you can open a shell any time by double-clicking that desktop icon.

Jekyll and the J1 Theme run on every current 64-bit operating system:

32-bit versions of Windows or Linux are not supported. If you bought your computer in the last few years it almost certainly runs a 64-bit operating system, but it is worth checking — especially on older home PCs. On Windows, you can find out which architecture is installed with this one-line command:

Copy the command, then paste it into the Windows search box on the taskbar (the magnifying-glass icon). A new window opens and displays your operating system’s architecture.

To run the development environment for J1 Theme you need these two programming languages installed:

For Windows, you can download both installers from the links in the following table.

Download both installers first. You will need them in the next two sections.

The essential tools for managing and editing a J1 website are:

Git keeps track of every change you make to your J1 project. With Git on your side, you have a complete history of your site and a very safe backup of all your project data on GitHub. Even if you break your local working copy beyond repair, you can always go back to a previous working version.

Git also protects you from serious data loss. You will start by creating a development branch — a parallel line of work where you can test changes without touching the main version of your site. You will see how useful this is when you start making big changes: your live site is never put at risk.

Download the latest version of Git for Windows from here (current as of 03/23): Git v2.40.0.

A powerful source-code editor like Atom is a developer’s most-used tool — it is the place where you spend most of your time. Editors typically come with many built-in features and you can install plug-ins for the rest.

If you already use a code editor that you like, by all means stick with it. You will not need to change.

If you have never used a code editor before, take the time to install one now. Yes, it is one more new tool to learn, but it will save you hours of work in return.

Installing programs is rarely exciting. To make it less tedious, the screenshots of every installer dialog below come with a short explanation, so you also pick up some technical terms along the way.

The notes will also help you pick the right options where the installer asks you something.

The Ruby gem j1-template is the foundation for managing J1 projects. The first step is to download the current version of this gem from the Internet. Ruby gems are downloaded directly with the Ruby package manager: the gem command downloads and installs a module in a single step.

You have already installed Git, but it is not configured yet. To create and use Git repositories for your local J1 projects, you use the git command on the command line. The basic setup of Git is very short: you only need to tell Git two things about your default identity:

Open a shell and run the following commands:

That is all there is to the basic Git setup. From now on, every Git command will record these personal details so that other contributors can see who made which change and how to contact you.

Creating and starting a J1 project is very easy. After only a handful of steps you will have a new website ready to go. The next few sections walk through every step in detail.

Here is the high-level overview:

A project consists of several files and folders. A typical structure of a J1 project looks like this:

If you deployed your site with the 1-Click method from the chapter Awesome Site, the new website now lives as a repository in your personal GitHub workspace. In Git terms, that GitHub repository is the remote — the central version of your J1 project.

The next few steps create a local working copy of your remote repository — in Git terms, the local. With this working copy on your PC, you can edit the site in your development environment and then sync the changes back to the remote on GitHub.

First, sign in to GitHub from the GitHub login page using your personal account.

If the j1-template gem is installed you can create completely new J1 projects from scratch. New projects are created with the j1 command on the command line.

If you have not already done so, create a folder where your local project copies will live. In the examples below that folder is C:\J1\Projects:

The j1 generate command creates a new project folder (my-start) inside your current folder.

j1 generate my-start creates a folder called my-start inside your current folder and fills it with every file the new project needs. When the command finishes, change into the new folder. The last step is to bring the new project under Git version control.

In the example below, the project is called my-start. For the next steps, make sure you are inside your project folder:

You only have to initialize a project once. Initialization downloads any additional NodeJS and Ruby modules the project needs, both for the development tooling and for the Jekyll build engine.

Initializing a project is done by the j1 command using the setup top-level script. The setup task triggers many sub-tasks, but you do not have to deal with them yourself — they all run automatically.

For an overview of what setup does, here is a summary of its output:

Setting up a project takes a few minutes — usually longer the first time, because Ruby and NodeJS modules have to be downloaded from the Internet. How long depends on your Internet speed and the performance of your PC.

You can think of setup as an extended install process: it downloads the modules the project needs and then uses the Jekyll engine to build the new website for the first time.

Once setup is finished, all the components are in place. You can start the Starter Web with a single top-level command:

The site task does a lot for you: it makes sure the development server is ready, starts Jekyll in watch mode, and finally opens the generated website in a browser when everything is up.

While you are developing a website you will sometimes need to rebuild it from scratch. J1 normally runs Jekyll in incremental mode with automatic regeneration: when you edit content, only the affected pages are rebuilt, and the browser reloads them.

A few changes — typically changes to the project’s configuration files — are not picked up by automatic regeneration. In those cases you have to rebuild the site manually. The rebuild task does exactly that: it recreates the whole website from scratch.

After a rebuild you can restart the development server with site and the website will reload in your browser:

Mistakes happen. A wrong setting in your J1 configuration can keep the site from starting, or make it behave in odd ways. In those cases, resetting the project to its original state often helps.

The reset task does the reset for you: it removes all the generated configuration files and modules that are no longer needed.

If you have just reset a project, you have to initialize it again with the setup task before you can use it.

Once the project is set up again, you can start the development server with site and the site will open in your browser as before:

Writing a website as plain-text source files may feel strange at first, especially if you have never worked this way before. Source-based projects have their own rhythm: you focus on the content first, and the visual result second.

This is a deliberate choice. When you are writing, you want to capture your ideas without interruption. Worrying about fonts, spacing, or page layout at the same time slows you down. Source files let you write down the skeleton of your idea as plain text, knowing that the formatting will be applied automatically later.

J1 is a JAMstack website, which means it is built from a handful of programming and markup languages. The two you will deal with most often are:

Building a website is part craft and part art. The craft needs the right tools; the art needs your creativity. This chapter helps with both.

As you work through this section, you will probably ask yourself questions like these:

Let’s get started. You are about to learn how to build a modern website and present its content well using J1 Theme.

The primary tool for this exploration and editing is the source code editor. The editor is the swiss army knife, the ultimate tool for daily work on websites. The editor offers essential functions for fast and reliable editing of the content, such as creating and adapting the configuration of the template system.

If not already done, start a new command shell, change the folder to your J1 project and fire up the build-in website:

For the following example, the source code editor Atom is used. Start your editor and open your project’s folder (the project my-start is used for all the next examples):

The quickest and most direct way to gain initial experience in dealing with a website’s content is to examine pages that are already finished, that already exist. The website built into the J1 Theme will help a lot to understand most of the elements used by the Jekyll engine and J1 Theme. The site supports you to learn the J1 Theme in a quite visual way and helps you to practice everyday routines and procedures.

You were already able to examine the general structure of a source page in the Page blocks section. You learned that the source of a page consists of the control-block and the content-block. Your modified about_site page might look like this:

Besides the actual content of the page from the content-block , there are a lot of other elements like that Navigation and page header . Look at other sites You’ll find that all pages on your site have these elements on your site.

This behavior is explained by the page model that the Jekyll builder engine uses to generate HTML pages. Besides the unique content of a page from the content block, all pages inherit components fundamentally required for each page. In other words, all pages consist of general elements that each page has and that unique content.

The structure of an HTML page is complex. In addition to the visible elements displayed in the browser, many other invisible HTML elements are required for a complete web page. For this, take a look at the HTML code of a web page. Displaying the HTML code can be called up with the key combination Ctrl+U. The HTML code of the fairly simple page about_site consists of hundreds of lines. The code contains many invisible HTML elements, which are required for loading the resources used, for example. The resources of a page include the required CSS styles that give a page its shape and Javascript components responsible for the dynamic behavior of pages.

An important promise of the template system J1 is: To create a website is no programming. No programming is required because all required programs exist already and are appropriately used by the builder engines to generate the resulting HTML codes of the pages. Knowledge of the details of these programs is not necessary, but it is very helpful to know how the HTML code of a page is created, how the Jekyll builder engine generates the resulting HTML code from source pages.

Authors should create source pages from scratch to create their content for a website. To not start completely from a blank page, J1 offers ready-made skeletons for new source pages. In the ~/pages/public/asciidoc_skeletons folder, three different types support different methods of developing new pages.

If you compare the already existing articles with the pages you created, one thing stands out: The existing pages seem to miss some Front matter variables.

To not repeat frequently used Front matter variables with identical values, it is advised to use default settings. Find the default settings of the Front matter variables with the site configuration /_config.yml.

Here you define common values and are only overwritten in the sources if necessary. For all articles of content type page, the variable layout has the default value page. The default value posts is set for all articles of content type post. Default values are configurable for many other variables not to repeat yourselves.

The front matter variable image: is used to display images. The variable controls the image used in the header-sections for the boxes displayed.