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.


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:

  1. Node.js(v8.3+)
  2. NPM or Yarn
  3. 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:

  1. gridsome develop to start the local server for development, this application is usually available at localhost:8080.
  2. gridsome explore to start the local server only to allow us to explore the GraphQL data.
  3. gridsome build to 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.

Read more about layouts here.

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.vue will be available at /.
  • src/pages/Blog.vue will be available at /blog.
  • src/pages/user/Settings.vue will 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

Creating content