By Bineli Manga, Alibaba Cloud Community Blog author.
Modern web applications are built using the static assets like HTML, CSS and Javascript. Among them, there's the architecture JAM stack, standing for Javascript, API and Markdown.
This tutorial comes after a previous one (link below) where I wrote for the Alibaba Cloud Tech Share program where I presented the features and the advantages of JAM stack. Now, in this tutorial, I'm going to show how you can use such a stack using the Jekyll framework to build your own personal blog using only static assets.
To have a look at my previous tutorial on the subject, you can go through the following link: How modern web apps are created
So, now let's get started.
First things first, there's installation. For the sake of simplicity, we will focus on the installation on only one architecture and OS, which will be Windows. So I will start by presenting the prerequisites for setting up the Jekyll framework development environment, then I will continue with installing the tools to get started with that framework.
Jekyll framework is a ruby package, so it can be used on any platform or OS (Windows, Linux and Mac OS), but in my case I will show the process of using Jekyll on a machine running 64-bit Windows 10.
To create a adequate Jekyll development environment, here are the prerequisites:
Now we are going to install the tools discussed above:
The simplest way to install Ruby on Windows platform is, through Ruby installer, this program installs the ruby language support on windows along with its execution environment and documentation.
After installing it, run the following command to install gems with the native extensions
> ridk install> gem install jekyll bundlerNow that our tools are installed, we can continue with the structure of a Jekyll project and get started with it.
The Jekyll gem makes a jekyll executable available to you in your terminal.
You can use this command in a number of ways:
jekyll new: Creates a new Jekyll site with default gem-based theme.jekyll new --blank: Creates a new blank Jekyll site scaffold.jekyll build or jekyll b: Performs a one off build your site to ./_site (by default).jekyll serve or jekyll s: Builds your site any time a source file changes and serves it locally.jekyll doctor: Outputs any deprecation or configuration issues.jekyll new-theme: Creates a new Jekyll theme scaffold.jekyll clean: Removes the generated site and metadata file.jekyll help: Shows help, optionally for a given subcommand, e.g. jekyll help build.Using Jekyll's syntax, we can consider different objects like the following ones:
Objects tell Liquid where to output content. They're denoted by double curly braces: {{ and }}. For example:
{{ page.title }}Outputs a variable called page.title on the page.
Tags create the logic and control flow for templates. They are denoted by curly braces and percent signs: {% and %}. For example:
{% if page.show_sidebar %}
<div class="sidebar">
sidebar content
</div>
{% endif %}Outputs the sidebar if page.show_sidebar is true. You can learn more about the tags available to Jekyll here.
Filters change the output of a Liquid object. They are used within an output and are separated by a |. For example:
{{ "hi" | capitalize }}Outputs Hi. You can learn more about the filters available to Jekyll here.
Front matter is a snippet of YAML which sits between two triple-dashed lines at the top of a file. Front matter is used to set variables for the page, for example:
---
my_number: 5
---Front matter variables are available in Liquid under the page variable. For example, to output the variable above, you would use:
{{ page.my_number }}Jekyll supports Markdown as well as HTML for pages. Markdown is a great choice for pages with a simple content structure (just paragraphs, headings and images), as it's less verbose than raw HTML. Let's try it out on the next page.
The include tag allows you to include content from another file stored in an _includes folder. Includes are useful for having a single source for source code that repeats around the site or for improving the readability.
Navigation source code can get complex, so sometimes it's nice to move it into an include.
Here is a basic example of the usage of the include tag:
Create a file for the navigation at _includes/navigation.html with the following content:
<nav>
<a href="/">Home</a>
<a href="/about.html">About</a>
</nav>Try using the include tag to add the navigation to _layouts/default.html:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>{{ page.title }}</title>
</head>
<body>
{% include navigation.html %}
{{ content }}
</body>
</html>Open http://localhost:4000 in your browser, and try switching between the pages.
Jekyll supports loading data from YAML, JSON, and CSV files located in a _data directory. Data files are a great way to separate content from source code to make the site easier to maintain.
Here is a example of the data file usage:
YAML is a format that's common in the Ruby ecosystem. You'll use it to store an array of navigation items each with a name and link.
Create a data file for the navigation at _data/navigation.yml with the following:
- name: Home
link: /
- name: About
link: /about.htmlJekyll makes this data file available to you at site.data.navigation. Instead of outputting each link in _includes/navigation.html, now you can iterate over the data file instead:
<nav>
{% for item in site.data.navigation %}
<a href="{{ item.link }}" {% if page.url == item.link %}style="color: red;"{% endif %}>
{{ item.name }}
</a>
{% endfor %}
</nav>The output will be exactly the same. The difference is you've made it easier to add new navigation items and change the HTML structure.
What good is a site without CSS, JS and images? Let's look at how to handle assets in Jekyll.
Using CSS, JS, images, as well as other assets is straightforward with Jekyll. Place them in your site folder and they'll copy across to the built site.
Jekyll sites often use this structure to keep assets organized:
.
├── assets
| ├── css
| ├── images
| └── js
...At this stage you'll just have a main css file. Create a css file at ./assets/css/main.css with the following content:
.current {
color: green;
}You'll need to reference the stylesheet in your layout.
Open _layouts/default.html, and add the stylesheet to the <head>:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>{{ page.title }}</title>
<link rel="stylesheet" href="/assets/css/main.css">
</head>
<body>
{% include navigation.html %}
{{ content }}
</body>
</html>Load up http://localhost:4000 and check the active link in the navigation is green.
Next we're looking at one of Jekyll's most popular features, blogging.
Blog posts live in a folder called _posts. The filename for posts have a special format: the publish date, then a title, followed by an extension.
Create your first post at _posts/2018-08-20-bananas.md with the following content:
---
layout: post
author: bineli
---
Lorem ipsum dolor sit amet consectetur adipisicing elit. Maxime, doloremque a laudantium nihil ad voluptatum optio, illum minus debitis odit fugit aut recusandae cum, commodi voluptate accusamus laboriosam earum adipisci.
Lorem ipsum dolor sit amet consectetur adipisicing elit. Maxime, doloremque a laudantium nihil ad voluptatum optio, illum minus debitis odit fugit aut recusandae cum, commodi voluptate accusamus laboriosam earum adipisci.
Lorem ipsum dolor sit amet consectetur adipisicing elit. Maxime, doloremque a laudantium nihil ad voluptatum optio, illum minus debitis odit fugit aut recusandae cum, commodi voluptate accusamus laboriosam earum adipisci.This is like the about.md you created before except it has an author and a different layout. author is a custom variable, it's not required and could have been named something like creator.
Let's look at fleshing out authors so each author has their own page with a blurb and the posts they've published.
To do this, you'll use collections. Collections are similar to posts except the content doesn't have to be grouped by date.
To set up a collection, you need to tell Jekyll about it. Jekyll configuration happens in a file called _config.yml (by default).
Create _config.yml in the root with the following:
collections:
authors:It's good practice to have a Gemfile for your site. This ensures the version of Jekyll and other gems remains consistent across different environments.
Create Gemfile in the root with the following:
source 'https://rubygems.org'
gem 'jekyll'Then run bundle install in your terminal. This installs the gems and creates Gemfile.lock which locks the current gem versions for a future bundle install. If you ever want to update your gem versions you can run bundle update.
When using a Gemfile, you'll run commands like jekyll serve with bundle exec prefixed. So the full command is:
> bundle exec jekyll serveThis restricts your Ruby environment to only use gems set in your Gemfile.
The project in this tutorial is to build a personal blog that you can use to showcase your talents on the web using Jekyll.
To set up the project, you have to execute the following commands in the CLI:
> jekyll new blogThis command will create a new Jekyll project named blog. The blog project is a folder with the above structure:
_posts
.gitignore
404.html
about.md
Gemfile
Gemfile.lock
index.md
_config.yml
When the command finishes its execution, you can execute the following to verify that the simple website can now be edited:
> cd blog
> bundle exec jekyll serveYou should see the following lines in the command lines to be sure that the dev server is running:
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.Now you can open your browser and point it to the address: http://127.0.0.1:4000/ to verify that the web server is effectively running.
When you finish writing your blog, you can deploy it online using a CDN server. For our case we will use the CDN provided by Alibaba Cloud named Object Static Storage.
In this step, I will show you how to deploy a static website on the Alibaba Cloud Static File Storage CDN, as recommended by the JAM stack organisation.
For more details about the creation of an OSS bucket and deploying files in it, you can check the following tutorial: https://www.alibabacloud.com/getting-started/projects/host-a-static-website-on-oss
Alibaba Cloud Spurs Industry Innovation for China Gateway Customers
2,599 posts | 762 followers
FollowAlibaba Clouder - March 10, 2021
Alibaba Cloud MVP - November 8, 2019
Alibaba Clouder - April 15, 2019
Alex - August 26, 2019
Alibaba Clouder - July 12, 2019
Iain Ferguson - November 26, 2021
2,599 posts | 762 followers
Follow
Content Delivery Solution
Save egress traffic cost. Eliminate all complexity in managing storage cost.
Learn More
CDN(Alibaba Cloud CDN)
A scalable and high-performance content delivery service for accelerated distribution of content to users across the globe
Learn More
OSS(Object Storage Service)
An encrypted and secure cloud storage service which stores, processes and accesses massive amounts of data from anywhere in the world
Learn More
Tair (Redis® OSS-Compatible)
A key value database service that offers in-memory caching and high-speed access to applications hosted on the cloud
Learn MoreMore Posts by Alibaba Clouder