← Back to all posts한국어로 읽기

Building a Blog: A Complete Beginner-to-Live Guide

This is the exact process I used to build this blog. Commands included, with a one-line “why” for each.

Step 1. Decide what you want

  • Topic — tech, daily life, reviews, practitioner notes in a specific field. The clearer this is, the easier everything later becomes.
  • Deployment method — GitHub Pages requires knowing git. Cloudflare Pages deploys with one terminal command. This guide uses the latter.
  • Design tone — roughly simple or colorful. Doesn’t need to be exact yet.

Step 2. Set up your dev environment

Opening a terminal (macOS): ⌘ + Space → type “Terminal” → Enter.

Check if Node.js is installed:

node -v
npm -v

Version numbers = you’re set. Nothing shown = install it:

brew install node

If brew itself doesn’t work, install Homebrew first from brew.sh.

Step 3. Scaffold the blog with Astro

Astro is a lightweight framework built for content-first sites like blogs. One command scaffolds the whole thing:

npm create astro@latest -- my-blog --template blog --install --no-git --yes
  • my-blog → rename to whatever folder name you want
  • --template blog → includes a post list, individual post pages, and RSS, all by default
cd my-blog
npm run dev

Open http://localhost:4321 in a browser — seeing the default template blog means it worked. It auto-refreshes every time you save a file.

Step 4. Replace the placeholder info

The template ships with fake filler text (lorem ipsum). Fix these two first.

src/consts.ts:

export const SITE_TITLE = 'Your Blog Name';
export const SITE_DESCRIPTION = 'A one-line description.';

src/pages/about.astro: delete the placeholder bio, write your real one.

Edit with a code editor like VS Code — its file browser plus live preview (⌘+Shift+V) makes it approachable even without much coding background.

Step 5. Prepare Cloudflare Pages

Right now everything only exists on your computer. For anyone else to see it, it needs to go on a server (deployment).

npm install -D wrangler
npx wrangler login

login opens a browser tab automatically — click approve there, and that’s it. No account yet? You can create one free from that same screen.

Step 6. Actually deploy it

Watch out for this: newer wrangler versions try to auto-switch you to a more complex deployment model (Workers) by default, and it fails. Always include --force the first time you create the project, to block that:

npx wrangler pages project create my-blog --production-branch=main --force

After that, every deploy is just these two lines:

npm run build
npx wrangler pages deploy dist --project-name=my-blog

https://my-blog.pages.dev, printed in the terminal, is your blog’s address. Run these two lines again every time you want a new post to actually go live.

Tired of typing both every time? Add this to scripts in package.json:

"deploy": "astro build && wrangler pages deploy dist --project-name=my-blog"

Then npm run deploy alone does both.

Step 7. How to write posts

One .md file in src/content/blog/ = one post. The filename becomes the URL (first-post.md → /blog/first-post).

---
title: 'Post Title'
description: 'A one-line summary.'
pubDate: 'Sep 18 2026'
---

The body starts here.

Everything between --- is frontmatter (title, date, etc.); everything below is the actual post content.

Five Markdown symbols cover most of what you need:

  • **bold**
  • *italic*
  • ## subheading
  • - list item
  • [link text](url)

Save it, and it shows up on /blog automatically. But you still need to re-run the deploy command from Step 6 for it to actually reach the live site — saving alone only you can see.

Step 8. Adjust the design

All the color values live together near the top of src/styles/global.css, inside :root { } (e.g. --accent). Change one value, and every button, link, and underline using that color updates at once.

Don’t try to perfect it before deploying — it’s faster to deploy something rough and adjust once you can see it live.

Step 9. Get it into search engines (SEO)

What you have now is a site that exists, not one that’s findable.

  1. Set site in astro.config.mjs to your real URL: 
    site: 'https://my-blog.pages.dev',
  2. Create public/robots.txt: 
    User-agent: *
Allow: /

Sitemap: https://my-blog.pages.dev/sitemap-index.xml
  3. Register at Google Search Console — pick “URL prefix,” not “Domain.” (pages.dev isn’t your DNS, so “Domain” verification fails.) “URL prefix” instead offers “HTML tag” verification — paste the code you’re given into the <head> inside src/components/BaseHead.astro, then redeploy.
  4. Once verified, submit sitemap-index.xml under Sitemaps.

Note: submitting doesn’t mean you show up in search instantly. It can take days, and that’s normal. Resubmitting repeatedly doesn’t speed it up.

Step 10. Always check it on mobile

A page can look fine on desktop and still have images overflowing the screen on a phone. One rule: open the real site on an actual phone, and screenshot anything that looks off right then. A screenshot finds the cause far faster than “something looks weird.”

Common mistakes

  • npm says “command not found” → double-check Node.js is actually installed.
  • Deployed, but the site didn’t change → you probably skipped npm run build, or it’s a browser cache issue — try a hard refresh (⌘+Shift+R).
  • SEO verification keeps failing → you likely picked “Domain” instead of “URL prefix.” Switch and try again.

Wrapping up

Decide what you want → set up your environment → install Astro → fill in your info → prepare deployment → deploy → write → design → SEO → check mobile.

You don’t need a perfect start. Deploy something, then fix whatever you actually notice, one thing at a time.