DatoCMS with Jekyll: A beginner's guide

Prerequisite

This tutorial assumes you have already installed Ruby and RubyGems. You can then install Jekyll with the following command:

gem install jekyll bundler

Create your first Jekyll project

Ok, let's create your first Jekyll project. In you terminal paste the following command:

jekyll new my_dato_project

Once finished enter in your project directory:

cd my_dato_project

Create a new blog post

Your new Jekyll project is ready to host a Blog and some static pages. By default you have an index page, an about page and a blog post . You can find the index.md and about.md files in the root folder of the project, and the blog post in _post/xxxx-xx-xx-welcome-to-jeckyll.markdown.

The way those pages will show up in your website is defined by your theme. In a fresh Jekyll installation the default theme is "minima".

Let's create a new blog post copying e modifying the existing post:

cp ./_post/xxxx-xx-xx-welcome-to-jekyll.markdown ./_post/2016-11-14-my-second-post.markdown 

Now change the content of the new file, and start the preview web-server:

bundle exec jekyll server

This will start a local web server running at: http://localhost:4000/.

You can create and edit files in the source folder and see the changes reflected on the preview web-server. You can stop the preview server from the command-line using CTRL-C.

Build a simple catalog

Not everything is a post or a page. Maybe you want to document the various methods in your open source project, members of a team, or talks at a conference. In our case, we want to create a simple product catalog. It would be great if we could avoid hardcoding all the product metadata inside the HTML templates... this way some team members could concentrate on building up the database of content, while another team member could build the structure of the site. Jekyll collections allow you to define new types of document that behave like Pages or Posts do normally, but also have their own unique properties and namespace.

Our catalog is a list of products where each product has the following attributes:

• Title

• Price

• Descriprion

Let's add a new products collection. Open your site's _config.yml file and copy the following lines:

collections:
  products:
    output: true
    permalink: /products/:path/

This way we're telling Jekyll that we are going to have a new collection name products, and we want to output a page for each element of the collection (our products). Those pages will be reachable at the URL products/{product_filename}/index.html.

Create a corresponding _products folder:

mkdir _products

and add a couple of files, one for each product, with some metadata and some markdown description:

---
layout: product
title:  "Star Wars Chewbacca Slippers"
price:  29.99
---
**Slippers** emit two different Wookiee roars when you walk!
# _products/sku-0001.md

---
layout: product
title:  "Star Wars R2-D2 Coffee Press"
price:  39.99
---
Holds 32 ounces of coffee for you (4 cups)
# _products/sku-0002.md

As you can see, Jekyll will use a layout named product. Layout templates live in the _layouts folder, so let's create it:

mkdir _layouts

Inside this folder add the template file product.html, which will render the details of a product:

---
layout: default
---
<h1>{{ page.title }}</h1>
<div>
  <strong>{{ page.price }}</strong>
</div>
{{ content }}

In this case, the default layout is inherithed from the "minima" theme we are using, and the page.title and page.price are exactly the metadata we added to the beginning of every product page.

We also need to create a products.md page in the root of our project to iterate through the products and create an index of products reachable at /products/

---
layout: default
title: "Products"
permalink: /products/
---
<h1>Catalog</h1>
<div>
  {% for product in site.products %}
    <p>
      <a href="{{ product.url }}" >{{ product.title }}</a>
    </p>
  {% endfor %}
</div>

Well done! Now try to navigate your homepage at http://localhost:4000 and click one the Products link.

Deploy your first Jekyll project

Ok, now that you have the ugliest (but perfectly working) catalogue in the world, you need to deploy your website somewhere. You can simply run the command jekyll build to build your static website in the _site folder, than you can manually copy al the files to your preferred hosting platform.

Having to manually repeat the same process again and again every time you change a single line of code can be quite frustrating, but you can do much better and automate the deploy process!

Deploy with Github and Netlify

Create a new repository on GitHub. To avoid errors, do not initialize the new repository with any README, license, or gitignore files. You can add these files after your project has been pushed to GitHub.

For our purposes, let’s call your new repo my_dato_project.

In your terminal initialize the project directory as a Git repository.

git init

Add the files in your new local repository. This stages them for the first commit.

git add .

Commit the files that you’ve staged in your local repository.

git commit -m 'First commit'

At the top of your GitHub repository’s Quick Setup page, click the clipboard icon to copy the remote repository URL. In Terminal, add the URL for the remote repository where your local repository will be pushed.

git remote add origin GITHUB_REPOSITORY_URL

Now, it’s time to push the changes in your local repository to GitHub:

git push origin master

Now that your assets are up and running on GitHub, let’s connect them to Netlify.

Connecting to Netlify

Step 1: Add Your New Site

Creating a new site on Netlify is simple. Once you’ve logged in, you’ll be taken to https://app.netlify.com/sites. If you’re just starting out, there’s only one option.

Step 2: Link to Your GitHub

Clicking “New Site” brings you to this screen:

Since your assets are hosted on GitHub, we’ll need to link Netlify to GitHub. Click “Link to GitHub”.

Step 3: Authorize Netlify

It’s time to allow Netlify and GitHub to talk to each other. Clicking the “Authorize Application” button will do just that. Like it says in the image below, Netlify doesn’t store your GitHub access token on their servers. If you’d like to know more about the permissions Netlify requests and why we need them, you can visit https://docs.netlify.com/github-permissions/.

Step 4: Choose Your Repo

Now that you’ve connected Netlify and GitHub, you can see a list of your Git repos. There’s the my_dato_project repo we just pushed to GitHub. Let’s select it.

Step 5: Configure Your Settings

Here you can configure your options. For the purposes of this tutorial, there’s nothing you need to change, so just click “Save”.

Step 6: Build Your Site

Now it’s time to sit back and relax. Go grab something cold to drink, scratch the dog behind the ears, or just get up and walk around (you’ve probably been in front of the computer for too long today, right?). Netlify will do the rest, and you can watch the progress.

Step 7: Done

Wait, you thought there was going to be more? Nope! Netlify has done it all for you, including giving your site a temporary name. Now everytime you push some change to GitHub, Netlify will repeat the build process and deploy a new version of the site. No more manual deploying! Let’s make it look a little prettier changing the name of the project:

There, that’s better. Now you can add your custom domain, and your site will be live for your adoring public to view. Congratulations!!!

Using DatoCMS

Until now it's all wonderful, but what about when you need to add, edit or delete a product, a post or a page of your site? Actually is not that difficult: all you need to do is open the data files stored in _products, edit the items data, commit your changes and push it to GitHub. Netlify will grab the changes and will deploy your updated website for you.

If this can be fine for you, it certainly cannot be done if the person in charge of updating catalog is not a programmer and or is not confortable with terminal.

That's where DatoCMS shines

DatoCMS is a fully customizable administrative area for your static websites. The administrative interface is incredibly simple to use, yet flexible enough to allow the management of pretty much any kind of website.

Best of all, your customers don't need not know anything about Ruby, Middleman, Github, etc. neither they need to install stuff on their computers. You do the dirty work building the website with Middleman, and they can customize thier contents with a browser, just like they're used to do with ie. Wordpress.

Let see how this magic works

Step 1: Add Your New Site

Creating a new site on DatoCMS is simple. Once you’ve logged in, you’ll be taken to [https://dashboard.datocms.com/account/sites](your account dashboard). If you’re just starting out, there’s only one option.

Give your website a name and eventually select a template to start your project. In our case we'll start with an empty site template:

Step 2: Enter your Admin dashboard

After you click on "Create a new site", DatoCMS will create your administrative area in a randomly-generated subdomain. You can adjust some settings, but for now just click on the given link and enter in the Admin Area.

Step 3: Create the Item Types

Now it's time to create a place to store all the informations related to your Products and your Posts. In DatoCMS this place is named "Item Type". Try to think of a DatoCMS ItemType as a table in a database. Click on the plus button:

Give your Item Type the name Product. We are going to have a collection of products so DO NOT check the "Single Instance" flag. Enable the "Order collection" as in the picture to be able to reorder your product list once populated.

Step 4: Define the product fields

Now that you have the "Product" ItemType (again, think of ItemTypes as a table in a DB) you have to define the Product attributes. To begin click the "Add Field" button:

Now let's add the "Title" attribute. DatoCMS offers a lot of specialized field types, but in our case a "Simple-line string" is fine, so just click it. Give a "Label" to your field and define your validation rules as in image below, than click on the "Save Field" button:

Now repeat this taks for the Description and for the Price field, choosing respectively "Long text" and "Floating-point number" as field types:

Step 5: Populate your catalogue

Now that you have the "Product" item type and its attributes defined, you can start to insert products in your catalog! Click on Content in the top navigation bar then click on the plus button to insert a couple of products.

Step 6: Repeat step 3, 4 and 5 for Blog Posts

Now let's create the BlogPost item Type, its attributes, and populate it:

• Click on "Admin area" on the top-bar;

• Click "Item tyles" on the left menu (actually it should be already selected);

• Click the "plus" button;

• Give the name "BlogPost" to your Item Type and save it;

• Click the "Add Field" button and choose "Single-line string", Give your Field the name "Title" and save it;

• Click again the "Field" button and choose "Date + Time", give your Field the name "Date" and save it;

• Click again the "Field" button and choose "Single-line string", Give your Field the name "Categories" and save it;

• Click again the "Field" button and choose "Long text", Give your Field the name "content", select "Markdown Editor" in the "Presentation mode" dropdown and save it.

Now that you have your Item Type ready, insert a couple of demo blog post clicking again the "Content" button on the top-bar.

Important

You do not need to give your customer access to your Administrative Area just to populate the catalog, but you can restrict the access to the DatoCMS only to the Content section. To do so just click to Users on the top navigation bar and invite your customer/editor/collaborator.

Integrate DatoCMS with Jekyll

Ok, just recap what we have done until now:

• We created a Jekyll website

• We added our blog posts data to separate files in the _posts folder

• We added our products data to separate files in the _products folder

• We committed all the project files to a GitHub repository

• We created a new Site in Netlify

• We linked the Netlify Site to our Github repo to allow an automated deploy on every commit

• We created a new Site on DatoCMS

• We created the "Product" and "Blog Post" ItemType and their attributes

• We populated the catalogue in DatoCMS

What we want now is to get rid of the Markdown files in the _products and _posts folder on our Jekyll project and integrate the data from DatoCMS instead. That's a trivial task, thanks to the dato gem.

Open your Gemfile on your Jekyll project and add the following line:

gem 'dato'

then in your terminal paste the following command:

bundle install

If everything worked correctly, you should now run bundle exec dato and see something like this:

$ bundle exec dato
DatoCMS commands:
  dato dump --token=TOKEN  # dumps DatoCMS contents into local files
  dato help [COMMAND]      # Describe available commands or one specific command

Great! Now we need to dump all the remote data into local files that would replace the ones in _products and _posts, so let's create a dato.config.rb file into your project root directory with the following content:

# dato.config.rb
directory "_products" do
  dato.products.each do |item|
    create_post "#{item.title.parameterize}.md" do
      frontmatter :yaml, {
        layout: "product",
        title: item.title,
        price: item.price
      }
      content item.description
    end
  end
end
directory "_posts" do
  dato.blogposts.each do |item|
    create_post "#{item.date.to_s.parameterize}-#{item.title.parameterize}.md" do
      frontmatter :yaml, {
        layout: "post",
        title: item.title,
        date: item.date.to_s,
        categories: item.categories
      }
      content item.content
    end
  end
end

This script will fetch the data from DatoCMS and will create the new files thanks to the create_post helper that the dato gem exposes.

The DSL is quite simple to understand, in any case you can check the gem official documentation

Now is time to see if it works. Fire the following command:

$ bundle exec dato dump --token=SITE_READONLY_TOKEN 

You obviously need to replace the SITE_READ_ONLY_TOKEN string with the actual token. You can find that token in your DatoCMS Admin area:

Now make sure that the files in the _products and _posts have been replaced.

BE CAREFUL!" This script will delete all the files in the specified directories :)

Auto deploy your website when data on DatoCMS changes

Until now, to deploy a new version of your website on Netlify you needed to push a new commit on your GitHub repo. This is wonderful when you, as a developer, make some change to the website pages in Jekyll, but you also want to deploy a new version of your website when products are added/edited/deleted on your DatoCMS site by your clients!

DatoCMS handles all this for you

On your DatoCMS Admin area click on Deployment settings, then on Netlify:

On the new window that pops up, click on "Grant Access" to allow DatoCMS to setup the auto-deploy meachanism for you:

Select the Netlify site that has to be build upon data changes on DatoCMS:

And click the Save Settings button:

Now every time you change any content in your DatoCMS web interface, you can trigger a new deploy on Netlify simply clicking on the Publish button:

The last thing to to is to tell Netlify to run bundle exec dato dump --token=SITE_READONLY_TOKEN before running jekyll build, so that the latest content coming from your administrative backend will be present at build time.

Go to your Netlify Dashboard and click on your site, than find the "Link to git" section end edit the "build command" like this:

bundle exec dato dump --token=SITE_READONLY_TOKEN && jekyll build

That's it!

Jekyll is a great static site generator and Netlify is perfect for one-click continouos deployment. DatoCMS "seems like it'll be the last piece of the puzzle!", as our customers says. Just give it a try and feel free to contact our customer support for any questions.

Happy coding!