Building Your Own Blog from Scratch: GitHub, Cloudflare Pages, Mizuki, and Obsidian#

First, Register for GitHub and Cloudflare#

If you don’t have these two accounts, it’s best to register for them. GitHub and Cloudflare are both famous cyber philanthropists! And generally, the earlier you register for a GitHub account, the more benefits you can enjoy!

First, register for GitHub:

Sign up for GitHub · GitHub

GitHub is used to host your blog repository and can also use Actions to implement an automatic upload workflow after commits.

If you can’t register, try switching nodes, using an incognito browser, or registering on your phone. For example, I ended up registering on my phone QAQ~~*those were my steps, haha.

Next, register for Cloudflare:

https://dash.cloudflare.com/sign-up

This registration is quite easy. I, the site owner, could register with a random Outlook email. Truly a CF philanthropist.

Cloudflare Pages is used to host your blog. It will put the built static files on Cloudflare’s network and give you a pages.dev domain.

https://github.com/zhuima/awesome-cloudflarE, here’s also a CF usage guide with 14k stars on GitHub, I recommend everyone save it!

Install Local Tools#

Download these tools from their official websites:

• Node.js: https://nodejs.org/
• pnpm: https://pnpm.io/installation
• Git: https://git-scm.com/downloads
• Obsidian: https://obsidian.md/download

After installation, open your terminal and check:

1
node -v
2
git -v
3
pnpm -v

If pnpm -v yields no results, you can enable it with Corepack:

1
corepack enable
2
corepack prepare pnpm@latest --activate

Windows users are advised to use PowerShell first. macOS and Linux users can just use the system’s built-in terminal.

Create a New GitHub Repository#

Open GitHub, click New repository.

For the repository name, you can write:

1
my-blog

After creating it, clone the repository to your local machine:

1
git clone https://github.com/你的用户名/my-blog.git
2
cd my-blog

Add My Obsidian Blog Template#

I’m not directly using the official Mizuki content repository here.

You can see the official content repository here:

https://github.com/matsuzaka-yuki/Mizuki-Content

But I usually write articles using Obsidian, so I’ve put together my own template. This template places the writing source in articles/, and then a script syncs it to the directory Mizuki needs.

The template now also retains two writing styles: regular articles and essays. Regular articles are placed in articles/posts/<slug>/<slug>.md and will generate independent pages; shorter notes can be placed in articles/essays/<slug>.md, and after publishing, they will be aggregated on the essays page.

Template repository:

https://github.com/Amiyadesi/astro-mizuki-blog-from-zero

If you use this template directly, the final directory should look like this:

1
my-blog/
2
  articles/
3
    posts/
4
    friends/
5
    spec/
6
    site/
7
    assets/
8
  blog/
9
    package.json
10
    src/
11
    scripts/
12
  .github/
13
    workflows/
14
      deploy-cloudflare-pages.yml

Remember this one thing first:

1
articles/ 是你写东西的地方
2
blog/ 是网站程序本体

In the future, don’t manually write articles in blog/src/content/posts. That directory is a synced output.

Open ‘articles’ with Obsidian#

Open Obsidian, select:

1
打开本地文件夹

Then choose:

1
my-blog/articles

This directory will be your blog’s backend from now on.

Remember these common locations first:

1
articles/posts/             文章
2
articles/friends/           友链卡片
3
articles/spec/about.md      关于页
4
articles/spec/friends.md    友链页正文和申请说明
5
articles/site/profile.json  头像、昵称、简介、社交链接
6
articles/site/navigation.json 导航栏
7
articles/site/banner.json   首页 Banner 和文案
8
articles/assets/            头像、Banner、音乐、友链头像等素材

If you find these JSON files hard to modify, you can directly search for ‘site-config-hub’ in Obsidian.

Here, the About page, Friends page, site JSON, and asset directory are all centrally located, making them easier to modify.

Local Plugin Startup#

After installation, open the third-party plugins page in Obsidian settings and enable the plugins included with the template.

Enable third-party plugins, check the one that exists by default.

Then two new items will appear in the left sidebar.

本地预览博客 button and 一键推送按钮

本地预览博客 automatically does these things under the hood:

1
同步 articles -> blog 内容
2
如果 blog 依赖还没装好，自动安装依赖
3
本地 build 博客
4
启动本地预览服务

So, the first time you click the local preview button, if blog/node_modules doesn’t exist yet, it will first complete the dependencies in the background, which will take a bit longer; subsequent clicks will be much faster.

It looks like a button, but behind it, it’s still calling local tools like Node, pnpm, and Git. The difference is that during normal use, you don’t have to go into the command line yourself to handle installation, syncing, building, and pushing.

After successful startup, it will automatically redirect you to the local preview address and switch to an active state.

1
Blog: http://127.0.0.1:4173/

This button is a toggle:

1
第一次点：启动预览并自动打开浏览器
2
第二次点：停止预览服务

The other one is automatic commit and upload after clicking.

Write Your First Article#

Create a new folder under ‘post’ to put everything an article needs, then create a new article and insert the template.

Then you can happily start writing! Common Markdown and some Obsidian syntax are all supported for parsing!

In the default template, draft: true is a draft. If you’re ready to publish, change it to draft: false; if this is just a short note and you don’t want it to appear as a standalone article, you can put it as a single Markdown file into articles/essays/.

If you want to place two or more photos side-by-side, you don’t need to write HTML by hand; you can write it like this:

1
:::photo-grid
2
![[left.png|左边照片说明]]
3
![[right.png|右边照片说明]]
4
:::

The description below the image will take the text after |. Regular Markdown images also support the same layout:

1
![说明](photo.png)

They will appear side-by-side on a computer and automatically stack into a single column on a phone.

There’s also a black block hint, suitable for answers, spoilers, or content you don’t want to see at first glance:

1
这里有一个 {{被遮住的内容|鼠标移上去会看到提示}}。

After publishing to the blog, hovering over it with the mouse or selecting it with the keyboard will reveal the main text and hint; tapping on a phone will also expand it.

Sync and Build#

Just click the button in the image, assuming you’ve already configured GitHub secrets. This template comes with actions built-in.

This button will commit and push your articles, configurations, and synced blog content to GitHub. After a successful push, it’s not your local machine directly deploying, but GitHub Actions that then builds the blog and publishes it to Cloudflare Pages.

And how to configure it is right below!

Create a Cloudflare API Token#

Open Cloudflare’s API Token page:

https://dash.cloudflare.com/profile/api-tokens

Create a Token; these permissions are sufficient.

You need to save three things:

1
CLOUDFLARE_ACCOUNT_ID
2
CLOUDFLARE_API_TOKEN
3
CLOUDFLARE_PROJECT_NAME

CLOUDFLARE_ACCOUNT_ID can be seen in the bottom right corner of Workers & Pages, it’s in the image above (lol).

CLOUDFLARE_API_TOKEN will only be fully displayed once. Copy it and quickly fill it into GitHub Secrets.

CLOUDFLARE_PROJECT_NAME is the name the Action will use to automatically create the Pages project.

Configure GitHub Secrets#

Go back to your GitHub repository page.

Go to:

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

Add these three:

1
CLOUDFLARE_ACCOUNT_ID
2
CLOUDFLARE_API_TOKEN
3
CLOUDFLARE_PROJECT_NAME

Names and values correspond.

Confirm GitHub Actions Workflow#

This file is already in the template:

1
.github/workflows/deploy-cloudflare-pages.yml

What it does is roughly:

1
拉取仓库
2
安装 Node 和 pnpm
3
进入 blog/
4
安装依赖
5
构建 Astro/Mizuki
6
用 Wrangler 把 dist 上传到 Cloudflare Pages

Of course, it’s best to start a local preview and check before committing.

Commit and Publish#

After pushing, open your GitHub repository’s Actions page.

If you see a green checkmark, it means deployment was successful.

If it fails, click in to see the logs. There are only a few common issues:

1
Secrets 名字拼错
2
Cloudflare Token 权限不够
3
PROJECT_NAME 填错
4
blog/ 构建失败
5
pnpm-lock.yaml 和依赖不一致

Open pages.dev#

After successful deployment, open:

1
https://你的项目名.pages.dev

If you can see the page, it means the first part is done.

By this point, you have a blog that you can write on, preview, and automatically deploy.

Let’s Stop Here for This Part#

The next part will cover domains, comment systems, and other small internet-related things, services, and communities relevant to site owners!