I decided to build myself a blog. One of the biggest issues I had was deciding what framework to make use of. My largest requirement is that the blog must facilitate learning and not hinder it.

I settled on Vitepress since I am a long time fan of Vue. This might change in the future since there are a lot of features that I feel are missing. I am hoping to build a lot of those features. However, I don't want to invest an endless amount of time building features when it might be easier to migrate.

Setup

Create a repo on github in order to make use of Github pages. You can install Vitepress into the repo as follows:

npm add -D vitepress

Then you can initialise your project using:

npx vitepress init

Completing the setup wizard is enough to get you a boilerplate site.

You can run the site using:

npm run docs:dev

I spend some time filling in details and improving the site to suit a blog.

Github Actions

I then created a Github Action to deploy the website to Github Pages. This is an easy way to host a static website. There are built in actions namely actions/configure-pages@v2, actions/upload-pages-artifact@v1 and actions/deploy-pages@v1 that make Github Pages deployments straightforward.

The following file .github\workflow\deploy.yml is used for deployment:

name: Deploy
on:
  workflow_dispatch: {}
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: npm
      - run: npm ci
      - name: Build
        run: npm run docs:build
      - uses: actions/configure-pages@v2
      - uses: actions/upload-pages-artifact@v1
        with:
          path: blog/.vitepress/dist
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v1

You should now have a site hosted on Github Pages. This site will be hosted under <github-username>.github.io/<repo-name>.

Custom Domain Name

If you want to go a step further you can setup a custom domain name. I bought [wernervandermerwe.com] from Google Domains and it costs less than a coffee a month. At the time of writing this Google Domains has been sold to Squarespace.

Include a CNAME file in your blog directory that includes your purchased domain name. In my case it was:

wernervandermerwe.com

Deploy your changes and open up your Github repo. In the repository settings got to pages and add the purchased custom domain. In your DNS provider you will now have to setup the DNS settings.

Add a new record with host name www, type CNAME and data to your Github pages URL <github-username>.github.io/<repo-name>.. This can take up to 24 hours to take effect.

Conclusion

This is a rough guide of how I put my blog together. I want to expand it a lot into the future and would probably end up moving it onto Azure Static Web Apps. This will allow for usage tracking and better cloud integration. I also want to expand it to make use of a single .md file per post that automatically gets indexed and dated.

This post will definitely be some of the less detailed since it took a few months of experimentation to see what I like. Please provide suggestions and feedback via LinkedIn. I will end in the words of Rassie Erasmus, "Views are my own. Will share some proper stuff."