How to build a Markdown blog using Gridsome
Gridsome is a static site generator used for building powerful frontend applications, it was built on the Vue.js framework. One of the beauties of Gridsome apart from its ability to generate server-side rendered applications is its compatibility with any headless CMS out there.
In this article, we’ll be looking at how to build a blog application using Gridsome for the frontend and Markdown for content.
Requirements
Before proceeding any further, It is required that you have adequate knowledge of JavaScript, Vue.js and the command line. While some knowledge of Gridsome and GraphQL is not required, It is recommended you go through the Gridsome documentation a bit.
Other prerequisites include:
- Node.js(v8.3+)
- NPM or Yarn
- Gridsome CLI
Creating the project
To create the application using the Gridsome CLI:
Install the Gridome CLI
Using NPM
npm install -g @gridsome/cli
Using Yarn
yarn global add @gridsome/cli
Creating the project
Creating a project using the CLI tool will scaffold the application using the default starter template.
gridsome create my-gridsome-blog
(or any other name you want to use )
Running the command above will create a folder in that directory my-gridsome-blog
Now we can start the development server by running:
cd my-gridsome-blog && gridsome develop
There are three commands you need to know when working with Gridsome:
gridsome developto start the local server for development, this application is usually available at localhost:8080.gridsome exploreto start the local server only to allow us to explore the GraphQL data.gridsome buildto build to the application for production, the production-ready files will be available in the /dist folder.
An overview of Gridsome
Before we dive into development, we need to understand a few concepts about Gridsome. Gridsome is said to be a framework on its own, so it brings a new way to structure applications.
If you already have some knowledge about Gridsome, you can skip to this section.
This is how a basic Gridsome project is structured, we’ll be getting into more detail below,
├── package.json
├── gridsome.config.js
├── gridsome.server.js`
├── static/
└── src/
├── main.js
├── index.html
├── App.vue
├── layouts/
│ └── Default.vue
├── pages/
│ ├── Index.vue
│ └── Blog.vue
└── templates/
└── BlogPost.vue
We’ll be looking at the structure by directories.
The root directory
package.json file
This file contains information about the project and the plugins installed.
gridsome.config.js file
This file contains the configurations of the application and can be used to set options for the installed plugins.
Read more about project configuration here.
gridsome.server.js file
This file is used to perform operations on the Gridsome server, it is optional at times, but in our case, this is the file we’ll use to create pages from the entries in the GraphQL layer.
Read more on the server API here.
The /src directory
This directory contains the main files and sub-directories which make up the project.
main.js file
Import global CSS and scripts here, the client API can also be used here. This file exports a function with access to Vue. Components, directives and plugins can be registered inside this function.
Components directory
Place reusable components in this folder, buttons for example, or individual postcards.
Layouts directory
Create new components in this directory to define layouts that will be shared across pages and templates.
Pages directory
Gridsome has a file-based routing system, so single file components in src/pages would be used as the component on a route with the matching name. For example:
src/pages/Index.vuewill be available at/.src/pages/Blog.vuewill be available at/blog.src/pages/user/Settings.vuewill be available at/user/settings.
Templates directory
Templates are used to generate single pages for every node in our GraphQL layer, A single file component in this directory must match the node’s typeName in order for it to be used, more on that later.
The /static directory
All files placed here are not modified by Gridsome in any way, they will be available in the root directory on our site after it’s deployed. For example, static/robots.txt will be available at yoursite.com/robots.txt.