DEV Community: Amie Chen

[Intro] Build a blog with Vuepress, Tailwind and Netlify

Amie Chen — Tue, 12 Feb 2019 03:43:48 +0000

Recently I launched a newer version of my personal website, which uses Vuepress behind the scene. Being a new Vue.js adopter, I thought Vuepress --- a static site generator built on vue.js --- was a natural choice for websites: it's intuitive, performant and flexible with markdown.

The project is still young(v.1x-alpha as of writing) so there's not a lot of resources beyond the default setup yet. I hope this 3 part walkthrough can help those who are thinking to use Vuepress for their personal websites or blogs.

What we are going to make

We are going to make a blog with a custom Vuepress theme. You will also learn how to apply some basic Vue.js-fu, incorporate functional css library like tailwind.css and eventually, deploy it to netlify.

Vuepress the static site generator

Vuepress is designed to generate documentations, but also works great for personal websites and blogs. It comes with a default "hidden" responsive theme and recommends a specific file structure. However, you can certainly roll your own.

v0 v.s v1

There is a big difference between vuepress v.0 and v.1-alpha. The few main updates that I love are:

In this whole series we are going to use the latest v.1x-alpha. If you are interested in knowing what's been added to v.1, read more about the changelog here.

When you are ready, let's start with Part 1: Setup a working Vuepress blog with Tailwind.css →

This is a cross-post from my website. Check out the original and more there!

[Part 3] Final wrap-up and deploy to netlify

Amie Chen — Tue, 12 Feb 2019 03:42:07 +0000

In this last post of the series, we will deploy our Vuepress blog to Netlify. I've spruced up the template a little bit by adding more tailwind classes, you can check out the repo on Github.

Setup Local Repository and Netlify Account

Then we have to install a local Vuepress as a dependency. This is important! Since the whole tutorial is built with 1x-alpha, we are going to install the latest.

npm install vuepress@next //mine is on 1.0.0-alpha.37

Then add a npm script to your package.json

  "scripts": {
    "build": "vuepress build"
  },

I personally like to test the build before pushing everything to netlify. In your project root directory, run the build command:

npm run build

If it builds successfully, we are safe to deploy everything to netlify.

Deployment setup

From your netlify dashboard, click the New Site from Git button on the top right. Select your repo and you should see the a screen for deployment setting. Add some configurations like the screenshot below:

Basically, we are telling Netlify to use the alpha vuepress version we installed along with the repo to run the build command, then output to a generated .dist folder. If you have put everything under a docs folder like the documentation did, your build command should be vuepress build dev and destination folder should be docs/.vuepress/dist.

Hit the deploy button and you should see your site building! Mine is deployed on here.

That's it! If you have any question please feel free to drop me a line :D Thanks for following along.

This is a cross-post from my website. Check out the original and more there!

[Part 2] Write and apply a custom Vuepress theme

Amie Chen — Tue, 12 Feb 2019 03:41:38 +0000

In this part, we are going to write some components for your theme with vue.js.

0. Setup some dummy blog posts

Let's add a few sample markdown files first. I have made some for you to download. Unzip it and put the blog folder under the root. Like the README.md you create in the last article, Vuepress will use the README.md as the default index.html of your blog folder. We will use it to display a list of blog posts.

1. Create the theme's layouts

There are 3 layouts in the theme we are going to create:

page (e.g. Homepage)
List of posts (e.g. Blog index page)
post detail (e.g. A Blog post)

If you worked with wordpress/jekyll before, you're probably familiar with the idea of page v.s post. A page is a static page without published date, it usually contains timeless content like the homepage; whereas a post is a timely blogpost.

In the layouts folder, in addition to the Layout.vue we created in the previous article, create 2 more files: PostsLayout.vue, PostLayout.vue.

Now let's give each of them some minimum template. Add this to PostsLayout.vue

<template>
  <div>
    <h1>list of posts</h1>
    <Content/>
  </div>
</template>

and add similar thing to PostLayout.vue

<template>
  <div>
    <h1>post detail</h1>
    <Content/>
  </div>
</template>

<Content /> is a Vuepress component that loads slot-free content from your markdown file. Anything that's not wrapped in-between ::: slot-key would be loaded.

In case you are not aware, it's important to know that you can only have 1 child under <template> for Vue.js to work correctly. If you have multiple children directly <template> you will get an error like Error compiling template .... Component template should contain exactly one root element.

Also, notice that in each markdown file in /blog, I've already indicated in the frontmatter that which layouts to use

---
layout: PostLayout
---

Now if you head to http://localhost:8080/blog/post-1.html you should see a page like below... which means you've binded each layout to the post correctly! Yay!

2. Create shared components

Now we are ready to add shared components like the global nav and footer. In the theme folder, create a components folder with 2 files inside: Nav.vue and Footer.vue. Notice it's a vue convention that components files are capitalized.

Nav

Simple thing first: let's add some template to the Nav.vue file.

<template>
  <header>
    <nav
      class="font-sans bg-white text-center flex justify-between my-4 mx-auto container overflow-hidden"
    >
      <a
        href="/"
        class="block text-left no-underline font-bold text-black uppercase"
      >{{$site.title}}</a>
      <ul class="text-sm text-grey-dark list-reset flex items-center">
        <li>
          <a
            class="inline-block py-2 px-3 text-grey-darkest hover:text-grey-dark no-underline"
          >menu</a>
        </li>
      </ul>
    </nav>
  </header>
</template>

As you can see, our Nav consists of a \$site title and some menu items. To programatically generate menu items, we first need to add a themeConfig object to our config.js. This is where we are going to site menu data.

module.exports = {
  title: "Vuepress Blog Example",
  description: "just another blog",
  themeConfig: {
    nav: [{ text: "Blog", link: "/blog/" }, { text: "About", link: "/" }],
  },
  postcss: {
    plugins: [
      require("tailwindcss")("./tailwind.config.js"),
      require("autoprefixer"),
    ],
  },
}

Now themeConfig will be available under the global computed $site. Did you notice we have already used it to render the \$site.title?

To programatically generate each menu item, we can utilize v-for to access the $site.themeConfig.nav that we just added to the config.js. Also, the link of each would be available to us. We can add to each item with :href.

<li v-for="item in $site.themeConfig.nav">
  <a
    :href="item.link"
    class="inline-block py-2 px-3 text-grey-darkest hover:text-grey-dark no-underline"
  >{{item.text}}</a>
</li>

v-for and :href are both Vue directives, where :href is a shorthand of v-bind:href. The first one simply means: for every item in $site.themeConfig.nav object, render this <li> block; and the later one is binding item.link to a vue rendered href. You could also use the plain old href but then you'd not be able to access to what's inside of item.

Now your Nav.vue should look like this:

<template>
  <header>
    <nav
      class="font-sans bg-white text-center flex justify-between my-4 mx-auto container overflow-hidden"
    >
      <a
        href="/"
        class="block text-left no-underline font-bold text-black uppercase"
      >{{$site.title}}</a>
      <ul class="text-sm text-grey-dark list-reset flex items-center">
        <li v-for="item in $site.themeConfig.nav">
          <a
            :href="item.link"
            class="inline-block py-2 px-3 text-grey-darkest hover:text-grey-dark no-underline"
          >{{item.text}}</a>
        </li>
      </ul>
    </nav>
  </header>
</template>

Vuepress utilizes vue-router's router-link, which is preferred than a hard-coded <a>. When in HTML5's history mode, router-link won't refresh the page on clicking links and it also progressively supports IE 9's hash-mode. For all these good reasons, we are going to replace all the <a> to <router-link>, and all href to be :to.

<template>
  <header>
    <nav
      class="font-sans bg-white text-center flex justify-between my-4 mx-auto container overflow-hidden"
    >
      <router-link
        :to="'/'"
        class="block text-left no-underline font-bold text-black uppercase"
      >{{$site.title}}</router-link>
      <ul class="text-sm text-grey-dark list-reset flex items-center">
        <li v-for="item in $site.themeConfig.nav">
          <router-link
            :to="item.link"
            class="inline-block py-2 px-3 text-grey-darkest hover:text-grey-dark no-underline"
          >{{item.text}}</router-link>
        </li>
      </ul>
    </nav>
  </header>
</template>

Footer

Not much magic is going on in the footer. Just add this template to Footer.vue

<template>
  <footer class="font-sans bg-black text-white py-8 px-4">
    <div class="text-grey-darker text-center">©2019 Yours truely. All rights reserved.</div>
  </footer>
</template>

Putting everything together

Because we want every single page to have the Nav and the Footer, we have to tell our layouts where to find them. Update the all layout files with the following:

<template>
  <div class="flex flex-col h-full">
    <Nav/>
    <Content class="flex-1 max-w-xl mx-auto leading-normal"/>
    <Footer class="pin-b"/>
  </div>
</template>

<script>
import Nav from "@theme/components/Nav";
import Footer from "@theme/components/Footer";
export default {
  components: { Nav, Footer },
  name: "Layout"
};
</script>

<style lang="stylus">
@import '../styles/theme.styl';
</style>

Since tailwind is not the main focuse of this tutorial, I already included some tailwind classes in the templates to make everything looked decent. Update the theme.styl with these css, under @tailwind components;

body, html, #app {
  height: 100%; /* makes the footer sticked to bottom */
}

By now, you should have pages look like this. Both menu items (Blog and About) are generated from our config!

localhost:8080

localhost:8080/blog/

localhost:8080/blog/post-1.html

Starting to look better, right?

3. List of posts page

To show a list of blog posts, we can create a globally computed properties posts. Update the export of PostsLayout.vue with the following:

export default {
  components: { Nav, Footer },
  name: "Layout",
  computed: {
    posts() {
      return this.$site.pages
        .filter(x => x.path.startsWith("/blog/"))
        .sort(
          (a, b) => new Date(b.frontmatter.date) - new Date(a.frontmatter.date)
        )
    },
  },
}

computed are values that will be computed when Vue starts and it will update itself when the data changes. Which means, you don't need to do extra work to get the new value ... How great is that! Inside we are saving the value of computed to the name posts.$site.pages is one of the Vuepress globals that gives you all the pages in the site, including the non-blog ones. To get a list of posts, I only want the pages under /blog. Therefore in the code above I filtered out the pages I don't need then sort the result by date before returning the value.

Now we can utilize the computed properties posts in our template. Replace <Content /> with this snippet

<ul class="flex-1 max-w-xl mx-auto leading-normal">
  <li v-for="post in posts">
    <router-link :to="post.path">{{ post.title }}</router-link>
  </li>
</ul>

Also, add the missing date into each blog post's frontmatter. Simply fake some date for the purpose of this tutorial.

date: 2019-02-11

If you go to localhost:8080/blog/ now, you should see our list of posts showing!

Wait, how come there's an empty list item on top? Right, because we forgot to filter out the README.md in /blog, which is not a blog post.

Let's add some logic to filter it out:

computed: {
  posts() {
    return this.$site.pages
      .filter(x => x.path.startsWith("/blog/") && !x.frontmatter.blog_index)
      .sort(
        (a, b) => new Date(b.frontmatter.date) - new Date(a.frontmatter.date)
      );
  }
}

In README.md(the one under the blog folder), add blog_index: true to the frontmatter

---
layout: PostsLayout
blog_index: true
---

Now if you check localhost:8080/blog/ again, the empty list item should be gone. Try click on every post link and see if it shows the correct post!

4. Use Vuepress plugins

I've always find reading-time info on Medium.com very useful, so let's add similar functionality. Luckily there's already a vuepress plugin exists so we don't have to write our own.

npm install -D vuepress-plugin-reading-time

Add plugins: ['vuepress-plugin-reading-time'] into your config.js.

Replace the <Content/> in your PostLayout.vue with this:

<article class="flex-1 mx-auto leading-normal container">
  <label class="text-grey-dark">{{$page.readingTime.text}}</label>
  <content />
</article>

Voila! Refresh any of your blog detail page, you should see the grey reading time on top:

As you can see, adding/using plugins in Vuepress is super easy and powerful. There aren't many plugins available yet so it's likely that you have to write your own.

Work with external node packages

Usually there's a published date on each post and we can easily accompolish that by adding a date in the frontmatter. But the output still has to be parsed it to be a human readable format, which Vuepress doesn't have support for it yet.

We can use extra tool like moment.js to help:

npm install moment

In PostLayout.vue, add the template to render your date, it'd render something like 2019-02-13T00:00:00.000Z.

<label class="text-grey-dark">{{$page.frontmatter.date}}</label>

To fix this, let's load moment package to our layout. Update the <script> with these:

import moment from "moment"
import Nav from "@theme/components/Nav"
import Footer from "@theme/components/Footer"
export default {
  components: { Nav, Footer },
  name: "Layout",
  methods: {
    formateDate(date) {
      return moment(date).format("MMM Do YYYY")
    },
  },
}

Then apply it onto the template

<label class="text-grey-dark">{{formateDate($page.frontmatter.date)}}</label>

Now you should see a human-readable date format like Feb 13th 2019!

5. Wrapping up

Phew You did it! This is a long tutorial I know, but if you followed through, you'd learn many concepts including

How to create a custom theme for Vuepress
How to use basic Vue directives in your theme
How to work with external node modules
How to use Vuepress plugins

Next, we are going to learn how to deploy it on Netlify. It's a short simple one, I promise! Let's go, Part 3

This is a cross-post from my website. Check out the original and more there!

[Part 1] Setup a working Vuepress blog with Tailwind.css

Amie Chen — Tue, 12 Feb 2019 03:40:57 +0000

In this part, we will setup a working Vuepress blog with Tailwind.css.

1. Getting Started

Let's create a folder called vuepress-blog then run these commands.

# cd into the folder
cd vuepress-blog

# install the latest vuepress alpha globally on your computer
npm install -g vuepress@next

# create the first markdown file
echo '# Hello VuePress' > README.md

# start the site locally
vuepress dev

When you run vuepress build, the README.md at the root level will be generated into index.html. Now head to localhost:8080, you should see a default site like this. Horay!!

Notice that some css already been applied to the page without any work (What's this magic ?! 😱). It's coming straight from the default theme packed in Vuepress. To alter it, run vuepress eject and a generated .vuepress folder will show up in your directory tree. It contains all the code for the default theme. We will go over this later when we start making a custom theme.

2. The correct directory structure

On the documentation, Vuepress recommends putting everything under a docs folder. You can name it with anything, but the important thing is that when running Vuepress commands, you'd need to run vuepress dev [folder name, i.e. docs] or you will see a 404 page.

On the other hand, you could simply leave everything at the root level under vuepress-blog. In this case, you just have to run vuepress dev like before.

3. Add tailwind.css

Since we don't have package.json yet, let's npm init the project first.

npm init

Then install tailwind

npm install tailwindcss

Now we are ready to generate the tailwind config

npx tailwind init tailwind.config.js

By now, your directory structure should look like this

vuepress-blog
├── node_modules
├── README.md
├── package-lock.json
├── package.json
└── tailwind.config.js

Next, we are going to create a custom theme that utilize tailwind.

4. Create a Custom Vuepress theme

At the root level of your project, create a .vuepress folder with a theme folder inside. Then inside of theme, create a styles folder. .vuepress houses everything, including your current theme and the vuepress config; the theme and styles folder is to override the default theme.

mkdir -p .vuepress/theme/styles

Now add a theme.styl in the styles folder to serve as the entry point of all css. Your directory tree should look like this:

vuepress-blog
├── .vuepress
│   └── theme
│       └── styles
│           └── theme.styl
├── node_modules
├── README.md
├── package-lock.json
├── package.json
└── tailwind.config.js

Add these lines to theme.styl to load all of our tailwind's styles.

@tailwind preflight;
@tailwind components;
@tailwind utilities;

Nice -- We are almost done!
Now we are going to tell Vuepress to connect to our tailwind. Create a file called config.js in .vuepress and put in these settings

module.exports = {
  title: "Vuepress Blog Example",
  description: "just another blog",
  postcss: {
    plugins: [
      require("tailwindcss")("./tailwind.config.js"),
      require("autoprefixer"),
    ],
  },
}

Lastly, we are going to add our theme index file. Create another folder named layouts in theme with a Layout.vue inside.

In Layout.vue let's add the very basic template for now

<template>
  <div>
    <h1 class="font-sans text-teal">hello world</h1>
  </div>
</template>
<style lang="stylus">
@import '../styles/theme.styl';
</style>

This Layout.vue will serve as the base layout of all your pages. If there is no layout specified in the frontmatter of a page, Vuepress will default to this layouts/Layout.vue. It's a required file for any vuepress theme.

Note: If your theme is super simple and doesn't have a layouts folder, you can leave the Layout.vue file directely under the theme.

Your final directory structure should look like this

vuepress-blog
├── .vuepress
│   ├── theme
│   │   └── layouts
│   │       └── Layout.vue
│   │   └── styles
│   │       └── theme.styl
│   └── config.js
├── node_modules
├── README.md
├── package-lock.json
├── package.json
└── tailwind.config.js

Restart your server now and run vuepress dev, you should see a page like this:

Make sure the tailwind classes are working (i.e. you should see the text being green instead of black.)

Nice job! By now, we have created a custom Vuepress theme that utilizes tailwind.css. In the next part, we are going to learn how to write your own theme and make your blog look awesome! Part 2 is here.

This is a cross-post from my website. Check out the original and more there!