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 asGatsby,Jekyll,Hugo, orVuePress!

The general flow for static sites is:

1. Write your code in a base folder (i.e.src/)
2. Run a build command (i.e.gridsome build)
3. Deploy the static output folder (i.e.dist/)

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 betweensrc/layouts andsrc/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 aresrc/ anddist/.

dist

When you first start a new project, you won't have adist/ folder since that's Gridsome's output folder. The code that ends up indist/ after runninggridsome build is the code you'll want to deploy to users.

src

Thesrc folder is where you'll be writing most of your code. This is the folder that Gridsome will compile down into thedist folder when you rungridsome build!

static

Thestatic folder stands out from the rest of the items on this list because it's the only one that isn't located in thesrc folder, but still have special functionality.

Thestatic folder is used to tell Gridsome that everything inside is off limits for the compiler and it should se sent directly todist/. Do not pass GO. Do not collect $200.

src/components

Since we're working with Vue, we want to be able to leverage the power of component-based frameworks. Thesrc/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 asSingle File Components.

src/layouts

Let's get this out of the way -technically you don't need to use thesrc/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<Layout> component!

src/pages

The TL;DR forsrc/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.

src/templates

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.