A brief introduction to blog building

Hugo and its mirror

#

For details on specific files, see HUGO installation documentation. The following mainly explains the docker deployment method.

lakegg/hugo mirrors 4 systems based on Busybox, Alpine, Debian and Ubuntu. Each of these systems is divided into 6 types: normal, ext, onbuild, ci, ext-ci, and ext-onbuild. Busybox is not ext-related. Here is a brief introduction to the differences between the types

• normal: Only basic hugo commands. The default Entrypoint is hugo, so common only needs to write server to execute hogu server
• ext: Extended version, which adds extended tools such as go, git, nodejs, etc. on the basis of normal (recommended)
• ci: Mainly used for continuous integration/deployment. On top of normal, it adds the environment variable HUGO_ENV, removes the default Entrypoint, and requires you to add the container running command yourself
• onbuild: This version is mainly used for compiling and building and can separate the source code and output. The default source code folder is /src and the output folder is .target, which can be customized using HUGO_DIR and HUGO_DESTINATION_ARG.

The docker image version is as follows:

For the Hugo template, see https://themes.gohugo.io/

Blowfish Template Usage

#

Hugo themes mainly use blowfish. The following is a brief explanation of the use of blowfish

The GitHub for blowfish mainly introduces the deployment methods using git submodules and Hugo. Here, we will mainly introduce how to use the hugo docker image introduced above for deployment

1. Add blowfish to go.mod

require github.com/nunocoracao/blowfish/v2 version // indirect

2. config/_default/module.toml file add:

[[imports]]
path = "github.com/nunocoracao/blowfish/v2"

3. Reference the root directory to the /src directory within the image and start docker

Use blowfish to build a blog. For details, refer to documentation.

Custom browser corner icon

#

Use favicon.io to generate your own image into icons of various sizes. Just extract the favicon.io icon package and place it in the /static directory.

Custom icons

#

Place the custom svg file in the /asserts/icons directory. In order to make the icons adaptive to the theme, you need to add the attribute fill=“currentColor” to the svg file as follows:

<svg>
    <path fill="currentColor" d="xxx"/>
</svg>

Chinese character count issue

#

You need to add the following attribute to config/_default/config.toml:

hasCJKLanguage = true

Comment plugin

#

For the comment component/service in Hugo, please refer to Comments. More than ten open source solutions are presented here, most of which require Docker or Kubernetes deployment. In addition, there are two comment components that require Github Discussions or Github issues: giscus and utterances. The following example uses giscus.

For more information on adding comments to the blowfish theme, see blowfish-Comments.

To add a file layouts/partials/comments.html, see the example in giscus for details:

<script src="https://giscus.app/client.js"
        data-repo="[enter the repository here]"
        data-repo-id="[enter the repository ID here]"
        data-category="[enter the category name here]"
        data-category-id="[enter the category ID here]"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

GitHub Page Deployment Hugo

#

Add a yml file to the .github/workflows directory. For documentation, see Host on GitHub Pages. A sample yml file is as follows:

name: Deploy Hugo site to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build
  build:
    runs-on: ubuntu-latest
    env:
      # Hugo version
      HUGO_VERSION: 0.121.0
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
      - name: Install Dart Sass
        run: sudo snap install dart-sass
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: recursive
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Build with Hugo
        env:
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --minify \
            # Blog address
            --baseURL "https://example.com"          
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # hugo is built and generated by default in the public directory.
          path: ./public

  deploy:
    environment:
      name: github-pages
      # blog address
      url: https://example.com
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Integrate Umami site statistics

#

This part is written in another article. For details, see this