×
Community Blog Getting Started with JAM Stack Using Jekyll and Alibaba Cloud OSS

Getting Started with JAM Stack Using Jekyll and Alibaba Cloud OSS

In this tutorial, you'll learn how you can use JAM stack with the Jekyll framework to build your own personal blog using only static assets.

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.

Installation

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.

Requirements

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:

  • Ruby: to be able to run Jekyll and its plugins.
  • Gem: to manage ruby packages.
  • bundler: to create ruby packages.
  • An Integrated Development Environment (IDE) for web development: in my case, for this tutorial, I will use Visual Studio Code.

Tools installation

Now we are going to install the tools discussed above:

  • Install Ruby (version 2.4.0)

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.

  1. Download and install Ruby installer: this will install Ruby, the ruby language documentation and the ruby package manager gem.
  2. After installing it, run the following command to install gems with the native extensions

      > ridk install
  • Install Jekyll and Bundler
> gem install jekyll bundler

Now that our tools are installed, we can continue with the structure of a Jekyll project and get started with it.

What is Jekyll

How Jekyll Works

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.

Jekyll Templating

Using Jekyll's syntax, we can consider different objects like the following ones:

  • Objects

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

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

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

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 }}
  • Layout

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.

  • Includes

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.

  • Data files

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.html

Jekyll 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.

Jekyll Styling

  • Adding assets and styling with CSS

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.

Content Production

  • Posts

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.

  • Collections

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.

  • Configuration

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:
  • Gemfile

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 serve

This restricts your Ruby environment to only use gems set in your Gemfile.

Writing Our Blog

Presenting the Project

The project in this tutorial is to build a personal blog that you can use to showcase your talents on the web using Jekyll.

Setting up the Project

To set up the project, you have to execute the following commands in the CLI:

> jekyll new blog

This 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 serve

You 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.

Publish Our Blog

Choose a CDN

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.

Deploy the Website

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.

  1. You have to log in to https://www.alibabacloud.com .
  2. Then click on Object Storage Service.
  3. Then create a new bucket that will be used to store the files of your static website.
  4. After completing the bucket creation, you are redirected to the created bucket interface
  5. Then you can upload your site's files inside the bucket.

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

0 0 0
Share on

Alibaba Clouder

2,205 posts | 511 followers

You may also like

Comments