I'm so happy to finally launch my new website! In terms of the tech stack, I stayed within my favorite world -- Vue 😆. But this time I decided to use VuePress instead. In this article, I want to share how this decision came to be and what my thoughts are on using VuePress.
- What I was using before
- Why did I switch from Nuxt to VuePress
- Benefits of VuePress
- Challenges of VuePress
- Was it worth the switch from Nuxt to VuePress
Prior to this, I was using Nuxt. I chose Nuxt because it was the only one offering server-side rendering. This was important to me as it has the benefit of SEO. Let me explain what that means.
This is the initial HTML output. Vue then takes over and insert all your components into the
id=app part. That's why in Vue, you always have to indicate the element you want to attach your vue app to. As a user, you don't really notice this because it happens really fast (depending on your internet speed).
<!DOCTYPE html> <html> <body> <div id="app"></div> <script src="/js/app.js"></script> </body> </html>
As you can see it's quite bare in the initial load. And this makes it difficult for our search engine bot to crawl and mine your precious data because nothing is there to begin with.
However with Nuxt, your app is generated on the server side first. So once it hits your browser, all your pages are already populated.
<!DOCTYPE html> <html> <body> <div id="app"> <h1>Hello there</h1> </div> <script src="/js/app.js"></script> </body> </html>
Here's how I like to compare it. Vue is like those blue apron (not sponsored) meals that you have to assemble at home. And Nuxt is like ordering take out from a restaurant, everything arrives ready to eat 😋
Anyhoo, I wasn't trying to build a fancy site. I was merely trying to build a content site to display my code tidbits and articles 😄. So I didn't need a Single Page App. I just need some good ole fashion plain HTML. And that's why Nuxt was it for me!
If Nuxt was so great, why switch. Why not just keep going with it. Well, because I was lazy lol. The great thing about Nuxt is that it's super configurable. That's also its downside, I had to configure everything myself. I didn't want to do that anymore. It's like choosing to buy a property. You can either buy a piece of empty land or pre-built home. The land is great because you can build whatever home you want on top of it, you're essentially starting from scratch. But for me, I want a pre-built home where I can simply move in and not worry about anything.
And that to me was VuePress. It has a built-in search plugin, super fancy markdown already set up with tons of cool features like code highlighting, and it was designed for a content static site. Which is exactly what I was building. So I made the switch!
Runner up: Gridsome
I was so close to picking Gridsome. It provided everything I wanted to create a static content site. But the Vue team came along with their own alternative, VuePress. So I thought if the Vue team created this, I'm in! In hindsight, I think I should have looked into this more as there were some challenges with VuePress. More on this later.
Alright, let's talk about some of the stuff I love about VuePress. Here are my top 3:
This was the main reason I switched to VuePress. I remember I had such a tough time setting up markdown in Nuxt. But that might be due to my limited programming experience at that time. So I only implemented only the bare minimum for it to work. With VuePress, I barely had to do any work to get these cool features to work!
<p>I am not highlighted</p> <p>I am highlighted</p>
Using Vue in markdown
# My markdown <VueComponent />
[Home](/) <!-- I can use relative links -->
You can see the entire Markdown Extensions here
Who knew such a small feature could make such a big impact. In my old site, there was no search feature. So I would use Google to search my own site to find specific tidbits. I'm surprised I never got any complaint emails on this. Maybe those folks just stopped using my site all together 😳 I don't blame ya 🤦♀️
And guess what! VuePress had a built-in search feature. It's a header-based search plugin. What does means is it will crawl through all your markdown files, and return the header that matches your query. Fantastic!
Frontmatter is like data for your markdown file. When you write a markdown article, a lot of times you want to include some extra information along with it. For example, the author name, the created date, the modified date ...etc. How do you pass the information along in your markdown. That's with a frontmatter block.
--- author: Samantha Ming created: Jan 26 modified: Jan 30 --- # My new blog post
I wish I could say this journey of building my site in VuePress was perfect. Unfortunately, it wasn't. VuePress is great for building a technical documentation site. But my site is essentially like a blog. So here I am trying to mold VuePress to suit my needs. And this was tough.
The VuePress documentation although great for the main features. It was a bit challenging for the more advanced or configurable tasks. I found the docs a bit lacking in examples. Let me give you an example (high five on the smooth example transition 😂).
I was trying to install
vue-fontawesome into my app so I can use the Font Awesome icons. I could not figure out how to do that. Luckily, I had some guidance and finally figure it out. I wished in the docs, they wouldn't have some use case examples. I think that would definitely help me out. If you ever read the Vue documentation, it's packed with examples and so simple to read. Good news is I know the VuePress team is trying to improve on this. So here being excited for that to happen 👏
By the way, here's how you install the plugin to work with VuePress, if you're curious.
When I was using Nuxt, there was this awesome plugin called
vue-meta. It allows to programmatically to create metadata for your pages. This is super important for SEO and to create those Twitter or Facebook sharing cards.
Yes, VuePress supports this. You can set a general one in your
config file. And you can set individual ones in your markdown file.
Remember when I mentioned my runner up option, Gridsome. They HADE it! Ugh 🤦♀️ It was part of their package. Under their hood, they were using
vue-meta. I was so close to switching to Gridsome just for this feature. But I was so far along, I decided to stick with VuePress. And you might ask, why don't you just configure
vue-meta with VuePress. Great question! If you figure out how, please email me! It's not that I don't want to, I just couldn't figure it out. And time is ticking, so I decided to move on. By the way, I need to set up
vue-meta with Server Side Rendering. So the complication is a bit higher.
I also created an issue in the VuePress official repo, so hopefully they will consider adding this. Feel free to chime in if you like this feature as well:
Yes, 100% Yes!!!! It took me a full crazy 2 months working around the clock to complete the site. VuePress had so many wonderful features already pre-built into it, I saved tons of time not having to work build those myself. Speed is the game here! I don't want to spend any time configuring anything. I don't want to build anything I don't have to. I want to spend my time, just executing. That's why I wanted to pick something that had a lot of things pre-built. Hence, selecting VuePress.
Hope you enjoy this summary of my experience and feedback on using VuePress.
The next post I want to cover is why I decided to switch CSS framework and used Tailwindcss. So stay tuned 😊