Imran's Blog
Stuff I feel like blogging about.

Setting up my blog

Posted on

I wanted to use Docusaurus to setup my blog because I might be using it for work and wanted to test it out. I am also a fan of the fact that it's a static site builder, which means I can use it with a free static site hosting solution. I decided to go with GitLab Pages because I am already using GitLab and it lets me use a custom domain.

# Setting up the GitLab project

This was pretty straight forward. I followed this guide.

First I created a simple enough html page.

echo 'This is me testing stuff.' > index.html

Followed by a .gitlab-ci.yml.

image: alpine:3.12.0

workflow:
  rules:
    - if: "$CI_COMMIT_BRANCH"

pages:
  script:
    - mkdir public
    - cp index.html public/index.html
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'

Then another quick guide for setting up a custom domain + SSL certificate.

And voilà!

custom domain setup

# Using Docusaurus

Like most modern JavaScript projects, to actually use Docusaurus I needed to first install an initializer that would setup a project for me. The install docs mentioned using npx to install and use the initializer.

This was my first time hearing about npx and I wasn't too keen on installing yet another JavaScript tool on my system.

yarn add @docusaurus/init@next
node node_modules/@docusaurus/init/bin/index.js init my-blog classic

This seemed to work well enough, the sole issue was the Docusaurus files were now in a dir called my-blog rather than my project root.

First I needed to cleanup the install files then move everything in my-blog a directory up.

rm -rf node_modules package.json yarn.lock
mv my-blog/* .
rm -rf my-blog

yarn start now showed me the default Docusaurus project page. At this point all that I had to do was to follow the Blog-only mode guide and customize to my needs.

One annoying thing is that the doc directory has to exist with a single .md file in it to prevent Docusaurus from failing to start.

# Updating .gitlab-ci.yml

Updated my CI configuration to use a node image and to cache node_modules/yarn cache

image: node:14.13.1-alpine3.12

workflow:
  rules:
    - if: "$CI_COMMIT_BRANCH"

cache:
  key: "$CI_PROJECT_ID"
  paths:
    - node_modules/
    - .yarn/

pages:
  script:
    - yarn config set cache-folder .yarn
    - yarn install
    - yarn build --out-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'