# How to build your own blog with hugo

# Who is this written for?

If you also want to start your own blog and hope to:

- The source code is placed in a warehouse so that you can write it slowly
- The final website is automatically deployed to `yourusername.github.io`
- Try to avoid the pitfalls of GitHub Pages and Hugo as much as possible

Then this process will be easier.

I am using two warehouses here:

- Private warehouse: `blogsource`
- Public warehouse: `yourusername.github.io`

Among them, it is best to use `yourusername.github.io` directly as the name of the public warehouse. If it is your first time to use GitHub Pages, it is recommended to follow this step, which is the easiest.

## Get ready before you start

Install these things first:

- `Hugo`
- `Git`
- An editor you are comfortable with, such as `VS Code`

Then find a local folder specifically to store the blog project, for example, mine is `D:\MyBlog`.

## a little reminder

Throughout the process, try to modify files locally and then push them up through Git. Don't make changes locally for a while and then go to the GitHub webpage for a while, otherwise it will be easy to mess up the status of the warehouse.

## overall idea

The structure of this blog is actually very simple:

1. `blogsource` is used to store Hugo source code
2. `yourusername.github.io` Used to place the generated static web page
3. Write articles locally and push source code
4. GitHub Actions automatically build and deploy to public repositories

If you don't want to automate it at first, you can deploy it manually first, make sure the website can run, and then add Actions.

## 1. Initialize the Hugo project

First enter the directory where you plan to put your blog in the terminal, for example:

```powershell
cd D:\MyBlog
```

Then create the Hugo project:

```bash
hugo new site blogsource
cd blogsource
git init
git remote add origin https://github.com/yourusername/blogsource.git
```

Replace `yourusername` with your own GitHub username here.

## 2. Add a theme

I am using the `LoveIt` theme here, you can also change it to your favorite theme.

```bash
git submodule add https://github.com/dillonzq/LoveIt themes/LoveIt
```

The advantage of using submodules is that it will be more convenient to update the theme later.

## 3. Configure `hugo.toml`

First write the most basic configuration:

```toml
baseURL = "https://yourusername.github.io/"
title = "My Blog"
theme = "LoveIt"
publishDir = "public"
```

There are two places to pay special attention to here:

- `baseURL` You need to change it to your own address, and it is recommended to keep the last one `/`
- `publishDir = "public"` means that the static files generated by Hugo will be placed in `public/`

## 4. Create a test article first

First make sure Hugo itself is working properly:

```bash
hugo new posts/hello-world.md
```

Then edit `content/posts/hello-world.md` and write it like this:

```markdown
+++
title = "Hello World"
date = "2024-01-01T00:00:00+08:00"
draft = false
+++

This is my first blog post.
```

If there is `draft = true` in your article, it will not be displayed by default. It is easy to forget this place.

## 5. Local preview

Run in the project root directory:

```bash
hugo server -D
```

Then open:

`http://localhost:1313`

If you can see the homepage and the test article just now normally, it means that the local Hugo is no longer a problem.

## 6. First push the source code to the private warehouse

This step is to put the Hugo source code into the `blogsource` warehouse.

### If the remote warehouse configuration is missed

You can delete the old one first:

```bash
git remote remove origin
git remote add origin https://github.com/yourusername/blogsource.git
```

### Submit and push

```bash
git add .
git commit -m "Initial commit: Hugo project with theme"
git branch -M main
git push -u origin main
```

If you have a brand new empty repository, this is usually enough, not necessarily `--force`.

After the push is completed, you can go to GitHub to take a look:

`https://github.com/yourusername/blogsource`

Confirm that the documents have been uploaded.

## 7. First manually deploy once to the public warehouse

If you want to verify that the entire process can run smoothly, you can deploy it manually first.

First generate static files:

```bash
hugo --minify
```

Then enter `public/` and push it to the public warehouse as a separate warehouse:

```bash
cd public
git init
git add .
git commit -m "Deploy to GitHub Pages"
git remote add origin https://github.com/yourusername/yourusername.github.io.git
git branch -M main
git push -u origin main --force
```

The reason why `--force` is common here is because `public/` This warehouse is essentially a generated product, and it is usually most worry-free to directly cover it as a whole.

## 8. Configure GitHub Pages

Go to the public warehouse `yourusername.github.io` and open:

`Settings -> Pages`

Then confirm:

- Branch: `main`
- Folder: `/ (root)`

After a minute or two, visit:

`https://yourusername.github.io`

If the website can be opened, it means that the most basic deployment link has been passed.

## 9. Do automated deployment again

After you successfully deploy manually, it will be more stable to use GitHub Actions.

The goal is: in the future, you only need to push the source code to `blogsource`, and GitHub will automatically build and deploy it.

## 10. Generate SSH keys

Run in `Git Bash`:

```bash
ssh-keygen -t ed25519 -C "actions-deploy-key" -f ~/.ssh/gh-pages-key
```

There are two files after generation:

- Private key: `~/.ssh/gh-pages-key`
- Public key: `~/.ssh/gh-pages-key.pub`

You can view them separately:

```bash
cat ~/.ssh/gh-pages-key
cat ~/.ssh/gh-pages-key.pub
```

## 11. Configure the key to GitHub

### Add public key to public repository

Enter `yourusername.github.io` warehouse:

`Settings -> Deploy keys -> Add deploy key`

Then fill in:

- Title: `ACTIONS_DEPLOY_KEY`
- Key: Paste the content of `gh-pages-key.pub`
- Check `Allow write access`

### Add a private key to the source code repository

Enter `blogsource` warehouse:

`Settings -> Secrets and variables -> Actions -> New repository secret`

Then fill in:

- Name: `ACTIONS_DEPLOY_KEY`
- Value: Paste the complete content of `gh-pages-key`

## 12. Add GitHub Actions workflow

Create a new file in the project:

`.github/workflows/deploy.yml`

You can refer to the following content:

```yaml
name: Deploy Hugo Site to GitHub Pages

on:
  push:
    branches: ["main"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.145.0"
          extended: true

      - name: Build
        run: hugo --minify --gc

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: yourusername/yourusername.github.io
          publish_dir: ./public
          publish_branch: gh-pages
          keep_files: false
```

Also remember to replace `yourusername` with your own username here.

## 13. Verify whether the workflow is effective

Submit the workflow file:

```bash
git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions workflow"
git push origin main
```

Then go to GitHub’s `Actions` page to see:

- Is there a new workflow?
- Is the latest run green?
- If it fails, click in to view the log directly.

## 14. It will be much easier to write articles later

After the automated deployment is completed, the subsequent update of the blog is basically this process:

1. Write or modify articles in `content/`
2. Local preview confirms there is no problem
3. Submit source code
4. Push to `blogsource`
5. Wait for GitHub automatic deployment to complete

The command is probably:

```bash
git add .
git commit -m "Update blog content"
git push origin main
```

After pushing it, GitHub will automatically deploy the static page to `yourusername.github.io`.

## One final sentence

If you just want to get your blog running first, then complete the following steps:

1. Create a Hugo project
2. Add topic
3. local preview
4. Manual deployment was successful once

After this link is established, and automation is added, the mentality will be much more relaxed, and it will be less likely to be discouraged by a bunch of Git and Actions errors.