Hugo + GitHub Action, build your blog automatic publishing system

foreword

In the previous article ” Free Personal Blog System Construction and Deployment Solution (Hugo + GitHub Pages + Cusdis) “, I mentioned that I used Hugo , a static website generator, to really build my personal blog and open source it on Hugo Based on the theme hugo-theme-den in the community, some personal customization transformations and configurations have been carried out to meet their own needs.

My program is mainly divided into the following core parts:

Personal blog source warehouse, version management for blog configuration and all article .md source files, automatic deployment with GitHub Action, automatic generation of static sites and push to GitHub Pages blog publishing warehouse.
GitHub Pages blog publishes a repository, a repository named in the form of username.github.io , uses GitHub Pages to implement website deployment, and can use a custom domain name through domain name CNAME resolution.
Hugo theme warehouse, fork favorite themes, and version management for your own personal customized transformation configuration, link to personal blog source warehouse through git submodule .
Other component source repositories, such as umami website statistics and Cusdis website comment system , etc.

The following will explain in detail the process of construction, local testing, automated deployment and maintenance, and hope to help you all.

Blog with Hugo

Hugo is a blog tool implemented in Go. It uses Markdown for article editing, automatically generates static site files, supports rich theme configurations, and can also be embedded with plugins such as commenting systems through js, which is highly customized. In addition to Hugo, there are also options such as Gatsby, Jekyll, Hexo, Ghost, etc. The implementation and use are similar, and you can choose according to your own preferences.

Install Hugo

I am using macOS, so I use the officially recommended homebrew method to install the hugo program, and other systems are similar.

 brew install hugo

Once done, verify with the following command:

 hugo version

Create a Hugo website

After installing the hugo program through the above command, you can use the hugo new site command to create, configure and debug the website locally.

 hugo new site blog-test

Configure the theme

After creating our site through the above command, you need to configure the theme. The Hugo community has a lot of themes. You can select your favorite style through the Themes menu on the official website, check the preview effect, and enter the theme project warehouse after selection. Generally, There are very detailed installation and configuration instructions. Next, I will use the hugo-theme-den theme I am currently using as an example to demonstrate the configuration process.

Associated Theme Repository

We can directly git clone the theme repository for use, but this method has some drawbacks. When we modify the theme later, it may cause some conflicts with the original theme, which is inconvenient for version management and subsequent updates. What I use is to fork the original theme warehouse to my own account, and use the git submodule method to link the warehouse, so that subsequent changes to the theme can be maintained separately.

 cd blog-test/ git init git submodule add https://github.com/pseudoyu/hugo-theme-den themes/hugo-theme-den

Update theme

If you clone someone else’s blog project for modification, you need to initialize it with the following command:

 git submodule update --init --recursive

If you need to synchronize the latest changes to the theme repository, you need to run the following command:

 git submodule update --remote

Initialize topic configuration and publishing

Each theme generally provides some example configurations and initial pages. When you start using the theme, you can copy the files in the exampleSite/ directory to the site directory, and adjust the configuration on this basis.

 cp -rf themes/hugo-theme-den/exampleSite/* ./

After initializing the basic configuration of the theme, we can configure the site details in the config.toml file. For specific configuration items, refer to the documentation of each theme.

Once done, new articles can be published via the hugo new command.

 hugo new posts/blog-test.md

local debug site

Hugo will generate static web pages. When editing and debugging locally, we can use the hugo server command to perform local real-time debugging preview without having to regenerate it every time.

 hugo server

After running the service, we can access our local preview webpage through the browser http://localhost:1313 address.

Getting started with GitHub Pages

Domain purchase

As an externally published website, we need to purchase a domain name and configure resolution to point to the server where our website is located, so that the outside world can access it in a more convenient way. There are many domain name purchasing platforms. I have used Cloudflare , NameSilo , GoDaddy , etc. The last one I use is Cloudflare, because it also provides powerful functions such as CDN, website data analysis, and custom rules.

First, we need to register a Cloudflare account. After logging in, select “Register Domain” in the left sidebar and search for the domain name you want to register.

After selecting the desired domain name, click and select the purchase time limit and fill in the personal information.

Select the payment method, it is recommended to choose automatic renewal, so as not to forget to renew.

Select Personal as the type, and click to complete the purchase.

You can view the information after waiting for Cloudflare to process it.

GITHUB PAGES warehouse

GitHub Pages projects need to conform to the special naming format of username.github.io . After the repository is created, you can configure your own custom domain name in the settings to point to the URL generated by GitHub Pages. In addition, you need to change the baseURL in the blog site configuration file config.toml to your own custom domain name in the format "https://www.pseudoyu.com/" , so that the blog site can normally access the website service generated by GitHub Pages.

DNS

After registering according to the above steps, you need to perform DNS resolution at the domain name host. Here we need to select CNAME to point to our GitHub Pages URL.

Because CNAME resolution cannot set the root domain name, that is, only www.pseudoyu.com or other subdomain names can be set, not pseudoyu.com . Therefore, we can set domain name redirection through custom rules on Cloudflare. The specific configuration is as follows, only need Just replace my domain name with your own. Even if you have a domain name registered through NameSilo, you can add your site for functionality through Cloudflare, or other hosting platforms have similar functionality, just follow the instructions to configure it.

GitHub Pages publish blog

After completing the above preparations, we can now access our GitHub Pages page through a custom domain name. At present, because the project repository is empty, a 404 page will be reported after visiting.

We hope that the static website generated by Hugo can be hosted through the GitHub Pages service without maintaining the service by ourselves, which is more stable and secure, so we need to upload the static webpage files generated by Hugo to the GitHub Page project repository.

Manual release

When we edit the blog content and debug it locally through hugo server , we can generate static web page files through hugo command.

 hugo cd public/

Hugo will store the generated static web files in the public/ directory by default. We can push our web static files by initializing the public/ directory as a git repository and associating with our pseudoyu/pseudoyu.github.io remote repository.

 git init git remote add origin [email protected]:pseudoyu/pseudoyu.github.io git add . git commit -m "add test"

After checking the file modification, you can push it to the GitHub Pages repository through git push origin master . After a few minutes, you can access our blog site through our custom domain name, which is exactly the same as our hugo server local debugging.

auto-publish

With the above command we can manually publish our static files, but there are still the following drawbacks:

The publishing steps are still cumbersome, and after local debugging, you need to switch to the public/ directory for uploading
Unable to backup and version manage blog .md source files

Therefore, we need a simple and smooth way to publish blogs. First, we initialize the repository of blog source files. For example, my repository is pseudoyu/yu-blog .

Because our blog is based on GitHub and GitHub Pages, CI can be automatically published through the official GitHub Action, which I will explain in detail below. GitHub Action is a continuous integration and continuous delivery (CI/CD) platform that can be used to automate build, test, and deployment pipelines. There are already many developed workflows that can be used directly with simple configuration.

The configuration is under the warehouse directory .github/workflows , with .yml as the suffix. My GitHub Action is configured as pseudoyu/yu-blog deploy.yml , and the example configuration for automatic publishing is as follows:

 name: deploy on: push: workflow_dispatch: schedule: # Runs everyday at 8:00 AM - cron: "0 0 * * *" jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v2 with: submodules: true fetch-depth: 0 - name: Setup Hugo uses: peaceiris/actions-hugo@v2 with: hugo-version: "latest" - name: Build Web run: hugo - name: Deploy Web uses: peaceiris/actions-gh-pages@v3 with: PERSONAL_TOKEN: $ EXTERNAL_REPOSITORY: pseudoyu/pseudoyu.github.io PUBLISH_BRANCH: master PUBLISH_DIR: ./public commit_message: $

on represents the trigger condition of GitHub Action, I set three conditions of push , workflow_dispatch and schedule :

push , when a push action occurs in the project repository, execute the GitHub Action
workflow_dispatch , which can be manually invoked in the Action toolbar of the GitHub project repository
schedule , execute GitHub Action regularly. For example, I set it to execute every morning in Beijing time. It mainly uses some automated statistical CI to automatically update the about page of my blog, such as this week’s coding time, video recording, etc., if you do not need the timing function , you can remove this condition

jobs represent the tasks in GitHub Action, we set up a build task, runs-on represents the GitHub Action running environment, and we chose ubuntu-latest . Our build task includes four main steps: Checkout , Setup Hugo , Build Web and Deploy Web , where run is the command to execute, uses is a plugin in GitHub Action, we use peaceiris/actions-hugo@v2 and peaceiris/actions-gh-pages@v3 These two plugins. Among them, in the Checkout step with , the submodules value of true can be configured to synchronize the submodules of the blog source warehouse, that is, our theme module.

First, you need to change the EXTERNAL_REPOSITORY in the above deploy.yml to your own GitHub Pages repository, such as my setting is pseudoyu/pseudoyu.github.io .

Because we need to push from the blog repository to the external GitHub Pages repository, specific permissions are required, and a Token must be created under Setting - Developer setting - Personal access tokens under the GitHub account.

Permissions need to open repo and workflow .

Copy the generated Token after configuration (note: it will only appear once), and then add the PERSONAL_TOKEN environment variable to the Token just now in Settings - Secrets - Actions of our blog source repository, so that GitHub Action can get the Token.

After completing the above configuration, push the code to the repository to trigger GitHub Action to automatically generate blog pages and push them to the GitHub Pages repository.

After the GitHub Pages warehouse is updated, it will automatically trigger the official page to deploy CI to realize our website release.

After the above configuration, we have realized the functions of Hugo blog local construction and version management, GitHub Pages deployment website release, Hugp theme management and update and other functions, and realized a complete system. Now whenever we finish editing the blog content locally through the familiar Markdown syntax, we only need to push the code, wait a few minutes, and then access the updated website through our custom domain name.

Component expansion

A complete blog system also needs some components, such as website data statistics, comment system, etc. I have also written a complete serverless construction tutorial for these two core requirements, which can be deployed and configured according to requirements.

Summarize

The above is the free blog automatic deployment system I implemented through Hugo and GitHub Action. My own implementation repository is in the pseudoyu/yu-blog repository, and my customized theme repository is in pseudoyu/hugo-theme-den .

I have also implemented a lot of interesting automated personal statistics functions using GitHub Action, automatically updating my GitHub Profile , the project repository is pseudoyu/pseudoyu , and you can go to .github/workflows to explore by yourself. These systems are still being improved, and everyone is welcome to contribute and communicate.

References

This article is reproduced from: https://sspai.com/post/73512
This site is for inclusion only, and the copyright belongs to the original author.