Or How to upgrade your personal site, by breaking it three times
disclaimer This post will be filled with sarcasm and self-deprecation.
TLDR; I rebuilt my portfolio site using three separate JAMSTACK tools and landed on Gridsome over Nuxt and 11ty for a few basic reasons.
- Gridsome allowed me to reuse 90% of my jekyll code and internal project structure
- I wanted to learn how to use a Vue based JAMSTACK tool and
- Change is hard sometimes
The Long Way Round
But who is wurs shod, than the shoemakers wyfe, With shops full of newe shapen shoes all hir lyfe?
[1546 J. Heywood Dialogue of Proverbs i. xi. E1V]
Throughout my web career, I have put various degrees of effort into maintaining my own personal portfolio. Upon entering this new chapter as a Software Engineer, I wanted to log my thoughts because I had some personal AHA! moments, and maybe these moments would resonate and help someone else.
My previous site was built on Jekyll, and it was the first modern flat site generator I had used. Jekyll was a joy to work with because of its great documentation and the ease of working with liquid syntax.
For me, Jekyll still has some ease of use advantages over some of its modern JS peers. This is not meant as a slight against, Next, Gatsby, 11ty, Nuxt, etc.. They all have different strengths and weaknesses. The elegance of the Liquid syntax really streamlines mundane theming tasks through common sense convenience seldom found in these other places, (although as of this writing 11ty's latest incarnation is Liquid friendly v0.11.0).
So part of my struggle was finding a framework that met my needs the same way that Jekyll did. This is a short list of requirements I had in order to migrate onto a new platform:
- Vue based - day to day I am in REACT land but I like Vue and I wanted to work with it more
- Markdown and YAML support baked in or easy to add
- Template inclusion should work in native files or Markdown files
- Little to no build process management
- Documentation gotta be 😙👌
Three Builds
I don't like to change things often, and as I was researching and testing different frameworks, I basically rebuilt or ported my site three different times. It was a Goldilocks style elimination bracket to get down to my current tech stack. Some frameworks were too soft, some were too firm, but Gridsome was just right.
Because Gridsome combines the template and file organization I like from Jekyll and the workflow I am accustomed to with Next, the build went quicker and adding features like this blog was fairly easy after getting through a few little config items.
I like YAML for HTML inclusion
I didn't want to take my existing data and run my YAML files through a JSON conversion script for the following reasons:
- I wanted to be able to re-use all my existing content for the time being
- I prefer reading formatted HTML in YAML because seeing \n makes me grumpy
I know this is a pedantic point but I am serious about it. I find JSON highly valuable when consuming pre-formatted content from an API endpoint, but for personal projects, I prefer YAML. It is easier to read and format.
Template inheretence
A great example of this is the inclusion of a template inside of a markdown file like below:
// Imagine this is the markup of my-article.md after the Front Matter
import MyComponent from '~/components/MyComponent.vue'
## Secondary Header
Description paragraph of text and then:
<MyComponent />
Another description paragraph of text.
Simple and effective way of walling off your functional things from static things.
Where are you coming from?
Two personal portfolios ago was a Word Press blog, one build ago was Jekyll, and now I am comfortably adjusting to the ways of Gridsome. If you see your experience as similar to mine, a designer turned UX and then developer or similar, then I would highly recommend giving Gridsome a spin. It has everything you are used to working with plus the modern conveniences of baked in build process config, and GraphQL.
If you are looking for some more detailed examples you could start here:
Note: This post was updated 12/31/2020 to reflect some edits that a couple of friends recommended as well as a minor update to the Vue Remark.