Intro to Gridsome's Folder Structure
What is a Static Site Generator?
Static site generators (SSG) are utilities/frameworks that allow you to write your website in your preferred language and then compile your code down to efficient HTML/CSS/JS. You may even have heard of some popular generators such as Gatsby, Jekyll, Hugo, or VuePress!
The general flow for static sites is:
- Write your code in a base folder (i.e.
- Run a build command (i.e.
- Deploy the static output folder (i.e.
In this post, we're going to break down the different folders in a Gridsome Project!
Folder names may vary by Static Site Generator
Folders, Folders, Folders
The biggest barrier that I see with Static Site Generators as a whole are the folder structures used and understanding which folder is for what functionality.
In particular, the distinction between
src/templates can be quite confusing since they're fairly similar in concept, but very different in use and output.
The two most important folders to note for Gridsome are
When you first start a new project, you won't have a
dist/ folder since that's Gridsome's output folder. The code that ends up in
dist/ after running
gridsome build is the code you'll want to deploy to users.
src folder is where you'll be writing most of your code. This is the folder that Gridsome will compile down into the
dist folder when you run
static folder stands out from the rest of the items on this list because it's the only one that isn't located in the
src folder, but still have special functionality.
static folder is used to tell Gridsome that everything inside is off limits for the compiler and it should se sent directly to
dist/. Do not pass GO. Do not collect $200.
Since we're working with Vue, we want to be able to leverage the power of component-based frameworks. The
src/components folder is where you can build your components to drop into your pages, layouts, and/or templates later!
Files in this folder will use the
.vue file extension and be structured as Single File Components.
Let's get this out of the way - technically you don't need to use the
src/layouts folder. It's a best practice to use it so that you can easily find and modify your layout
if when changes are needed.
Layouts at their base are
.vue file extension Single File Components, but with the understanding that these components will include at least one
<slot/> component and be used as a general structure for your pages - think a header, footer, and sidebar that will be the same on every page.
Don't forget to import and wrap your pages in your `` component!
The TL;DR for
src/pages is any one off page that you want to add. For example:
- Home page
- About page
- Uses page
- Contact page
- Blog index page
The slightly longer summary is any page that you want to tweak the contents/layout of without impacting any other pages.
If you're familiar with Static Site Generators, this is the section you've probably been waiting for - where to pass in your data and spit out a bunch of pages!
The key piece here is that you can add a
<page-query> to your
.vue file which will wrap a GraphQL query allowing you to access your data to generate your pages!
Combining this with plugins such as
@gridsome/source-filesystem to work with local markdown files, you can generate your pages.