My JAMstack Journey: A Guide To A (very simple) JAMstack Site — Part 2
Welcome to part two of this three part series on how to build a simple JAMstack site. In part one, we set up a Kontent.ai headless CMS project, installed the tools required to develop a JAMstack website, and created a Netlify account in anticipation of deploying to and hosting our website. In part two, we will dive into our Gridsome project and start writing code — this article will focus on setting up a skeleton HTML website in Gridsome.
Seat belts on, we’re gonna build a (very simple) HTML skeleton 💀 website.
Website Development
Now that we’re done with setting up our development environment and tools, let’s begin building by opening up the Gridsome project in our code editor of choice.
My personal preference is Visual Studio Code.
Before we pull content from Kontent.ai, we’re going to create a static site structure — complete with master layout, home page, news page and an article details page. Having a functioning site structure will make it easier to integrate CMS content in part three when we begin using GraphQL.
Let’s open the Gridsome project in a code editor — if your editor has a file hierarchy view, you’ll see Gridsome’s specific project file structure (figure 1 below).
Behold! The Gridsome project:
Styling
First up, we need a place for the site assets — a place to add our static images, CSS files, font files, JS files, etc. We are only going to add a single CSS file as to keep things simple and we’re not adding any CSS frameworks. We will also get our dummy images from Picsum (the lorem ipsum of images).
On a side-note, there are plenty of great CSS framework options to choose from including Vuetify, Tailwind CSS, Bootstrap, the list goes on.
The CSS file will go here:
\src\asses\css\main.css
We need to configure Gridsome to reference our CSS file so that a reference is generated in our HTML. This is done via an import statement that needs to be added in the main.js file (note the import statement on line:4 - in figure 3 below):
\src\main.js
In the next steps we’ll create a skeleton HTML pages — with dummy text and dummy images aplenty. Our structure will consist of a master layout, a home page, a news listing page and a news details template. Once our skeleton website is set up an working, in part three we will hook up Kontent.ai and via GraphQL, which will help us pull in content from the CMS.
Default Layout
The default layout (I refer to it as the master page — old habits die hard) acts as a wrapper around pages. We’ll place the site’s header, top navigation, and footer here as they’re components that repeat across all pages.
Coming from the .Net world, it’s easy to draw some parallels — such as a Gridsome layout serving a similar purpose as a MVC page layout; and likewise, a Gridsome page being similar to a MVC view page.
Note in figure 3 above, on line:6 we configure the default layout — by specifying the Vue file for our default layout.
\src\layouts\Default.vue
Note the <slot/> tag which pulls site page files — to be wrapped by the default layout.
For further reading on layouts (and slots), look no further than the Gridsome extensive documentation pages:
https://gridsome.org/docs/layouts/
Pages
Pages are representative of the site page structure which directly correlates to a URL. On the surface, the routing of page files is handled in much the same way as you would expect from a static HTML website (of yesteryear). An exception to this is the concept of templates, which we’ll look at a little later when building our articles, but as far as pages go, we can easily map our content hierarchy.
Page files live in the folder below:
\src\pages\
An example of how the Gridsome page file structure relates to website URL structure is:
The following page file:
\src\pages\about.vue
Will resolve to the URL:
www.mywebsite.com/about
Likewise, the following page file:
\src\pages\about\history.vue
www.mywebsite.com/about/history
And for the home page, the index.vue file:
\src\pages\index.vue
Will resolve to the home/start page:
www.mywebsite.com
More information on pages in the Gridsome docs here: https://gridsome.org/docs/pages/
Home Page
For the home page we need to create the below Index file:
\src\pages\Index.vue
Note that the page HTML is between the <template> and <layout> tags:
<template>
<Layout>
the page HTML
</Layout>
</template>
The result:
News Page
The website’s news page will be accessible via the /news page in the URL, that is: www.mywebsite.com/news
As such, the News.vue file will need to be created in the below location:
\src\pages\News.vue
The news page in figure 6 defines two article teaser blocks. When we connect this page up with GraphQL and query Kontent.ai, the page will display teaser blocks for all of the articles within the CMS.
The result:
News Article Page (err… template)
For individual news articles, we don’t want to be creating a page for every single article. We want our articles to be driven by the CMS with as little effort as necessary from a development perspective — creating a brand new Vue page every time an article is published in the CMS would be less than ideal. Much in the way that a CMS handles repetitive content with templates, we also want to have a page template that can be applied to any article — new or existing. This is where Gridsome’s templates come in handy as they allow for just that — a way to apply a template to a specific page type that is re-usable for every instance of that type (such as an article as per our example).
More information on templates in the Gridsome docs here: https://gridsome.org/docs/templates/
Templates live in the below location:
\src\templates\
So, we need to create a template for our news articles. One thing to note on the naming of the template is that it should have the same file name as that of the GraphQL object it will represent. This is something I didn’t do the first time around and almost pulled my hair out trying to figure out why every article I navigated to was resulting in a 404 😖. Therefore the filename in our example will be Article.vue which is the same content type name in Kontent.ai and consequently the same object name when querying GraphQL.
\src\templates\Article.vue
We won’t be previewing this Article template as it’s not a stand-alone page, but in part three of this series, we will be using the Article template for the presentation of all articles pulled down from our CMS.
For our Article template, one last step we need to make is to update the gridsome.config.js file in order to associate the Article content type with the Article template.
\gridsome.config.js
While we’re here, let’s also configure the route for all articles to ensure they’re delivered on the /news URL section. Note the :slug in figure 10 below, in the route definition which will use the URL slug as defined in the CMS so that articles are presented on a user-friendly URL.
What’s next?
With a skeleton HTML site in place, we’re at a point where we can begin adding functionality to pull CMS content from Kontent.ai. In part three of this series, we’ll be doing just that. Part three will configure the connection between Gridsome and Kontent.ai, we will use GraphQL to query Kontent.ai and hydrate our site pages, and finally we will deploy our website using Netlify.
3-Part Series Quick Links
Part one — Setting up required tools, headless CMS content modelling and content creation
Part two — Creating a HTML skeleton site with Gridsome
Part three — Using GraphQL to hydrate our site with CMS content and deployment to Netlify
