A simple way to hosting personal technical blog website with minimal efforts. Vuepress (opens new window) allow us to generate a static website with Vuejs and Markdown files, and Github pages (opens new window) facilitate a free domain for hosting website.

Generate static website

Setup Vuepress

by reference the official document (opens new window), setup vuepress from a project directory

# install as a local dependency
yarn add -D vuepress # OR npm install -D vuepress

# create a blog directory
mkdir blog

# create general version control for nodejs
touch package.json

# local dependencies for vuepress and blog specific plugins
yarn add -D vuepress
yarn add -D @vuepress/plugin-blog
yarn add -D @vuepress/theme-blog

Add some basic script to package.json, it might finally look like:

  "scripts": {
    "dev": "vuepress dev blog",
    "build": "vuepress build blog"
  },
  "devDependencies": {
    "@vuepress/plugin-blog": "^1.9.2",
    "@vuepress/theme-blog": "^2.1.0",
    "vuepress": "^1.3.1"
  }

.gitignore file for git

# ignore the dependencies for node
node_modules/

# ignore the generated production build files
blog/.vuepress/dist/

Content for website

blog/.vuepress/config.js is the most important config for @vuepress/blog Please also reference @vuepress/plugin-blog (opens new window) and @vuepress/theme-blog (opens new window) for blog content. They are work closely with each other.

module.exports = {
  theme: '@vuepress/theme-blog', // empty means default theme
  plugins: [
    [
      '@vuepress/blog',
      // below used for specify the website config with blogs & tags
      {
        directories: [
          {
            // Unique ID of current classification
            id: 'blog',
            // NOTE: Target directory, which means your readme file will have to stay under this directory
            dirname: 'posts',
            // Path of the `entry page` (or `list page`)
            path: '/',
            itemPermalink: '/:year/:month/:day/:slug',
            pagination: {
              lengthPerPage: 5
            }
          }
        ],
        frontmatters: [
          {
            id: 'tags',
            keys: ['tags'],
            path: '/tag/'
          }
        ]
      }
    ]
  ],
  themeConfig: {
    nav: [
      { text: 'Blog', link: '/' },
      { text: 'Tags', link: '/tag/' }
    ]
  }
};

Your content will need to store under blog/_posts, e.g. blog/_posts/2020-3-1-first-post.md:

---
title: First Post
date: 2020-3-1
tags:
  - tag1
  - tag2
  - tag3
author: Marvin CAI
location: Hong Kong
---
... Markdown Content below

After that, yarn dev will bring up a working website in localhost 🎉

Deploy

Please follow official document (opens new window) to setup a repo for hosting Github page.

Since I am taking advantage of a free tier while looking for a good way to secure my source code with version control. I keep my source code into a private github repo like https://github.com/marvin5064/github-pages, and create a public repo https://github.com/marvin5064/marvin5064.github.io for hosting.

After that, you need a deploy script to push latest change to the hosting repo

touch deploy.sh
chmod +x deploy.sh

deploy.sh:

#!/usr/bin/env sh

# abort on errors
set -e

# clear up previous generated files
rm -rf blog/.vuepress/dist

# build
yarn build # or npm run build

# navigate into the build output directory
cd blog/.vuepress/dist


git init
git add -A
git commit -m 'deploy'

# please replace the GITHUB_USERNAME below
git push -f git@github.com:GITHUB_USERNAME/GITHUB_USERNAME.github.io.git master

cd -

after all, deployment could simply happen by running the deployment script 🎉

Conclusion

Overall it is quite easy to bootstrap a basic personal blog website and host it in a second, there are some topics worth to further develop.

Default theme ⚒ Blog theme

Default theme:

• give you more thing under control
• more align with the fundamental of vuepress design
• more effort to get tags & filter works
• reference (opens new window)

Blog theme:

Note that this plugin has been deeply integrated into @vuepress/theme-blog

quote from blog plugin (opens new window)

• Blog tags, pagination and filtered content comes free
• Tight coupling of plugin-blog and theme-blog
  • I've tried to have only plugin-blog work with default theme, it is not working as expected. You might be able to get tags in use, hosting a filter page and pagination requires efforts
• Need think of how to override certain theme to be more customized for personal use, here might be a good reference to write a blog theme (opens new window)

Alternatives of deployment

There are multiple alternatives other than github pages

• Netlify
• Google firebase
• Surge
• Heroku
• ZEIT Now

Which you might reference here (opens new window)

Technical blog website with Github sounds professional, its free host with a proper domain is the main selling point for me to host the website here. It is quite a personal decision made here.

Docs hosting

Vuepress was originally designed as an open-source project for documentations with a good performance. Hosting a blog added extra work and complexity to it. With the simply markdown and hosting process, its definitely worth consideration in the future for Docs.