운영하기 2026년 5월 7일 수정일 2026년 5월 7일

VS Code로 Astro 블로그 관리하는 방법

Visual Studio Code에서 Astro 블로그 프로젝트를 열고, MDX 글을 작성하고, Git으로 변경사항을 관리하고, GitHub push와 Cloudflare 배포까지 이어가는 작업 흐름을 정리합니다.

#VSCode #Astro #Git #MDX #블로그운영

들어가며

Astro 블로그를 만들고 나니, 실제로 글을 쓰고 코드를 관리하는 작업은 Visual Studio Code에서 하는 것이 가장 편하다는 생각이 들었다.

처음에는 터미널 명령어 위주로 작업했지만, 글이 늘어나고 컴포넌트와 스타일 파일도 많아지면서 프로젝트 전체를 한눈에 보면서 관리할 수 있는 도구가 필요했다.

이번 글에서는 chailmon.com 블로그를 VS Code에서 관리하기 위해 설정한 작업 흐름을 정리한다.

목표는 단순하다.

1. VS Code에서 Astro 프로젝트 열기
2. MDX 글 작성하기
3. 로컬에서 글 확인하기
4. 빌드 테스트하기
5. Git 변경사항 확인하기
6. commit / push 하기
7. Cloudflare 자동 배포 확인하기

1. VS Code 기본 세팅

macOS에서는 VS Code를 설치한 뒤 프로젝트 폴더에서 아래 명령어로 바로 열 수 있게 설정해두면 편하다.

code .

이 명령어가 동작하지 않는다면 VS Code에서 Command Palette를 열고 다음 명령을 실행하면 된다.

Shell Command: Install 'code' command in PATH

그다음 터미널을 새로 열고 아래 명령어로 확인한다.

code --version

정상적으로 버전이 나오면 터미널에서 VS Code를 열 수 있다.

2. 필요한 VS Code 확장 설치

Astro 블로그를 관리할 때 기본적으로 설치해둔 확장은 다음과 같다.

Astro
Tailwind CSS IntelliSense
MDX
Prettier - Code formatter

각 확장의 역할은 다음과 같다.

Astro
→ .astro 파일 문법 강조와 자동완성

Tailwind CSS IntelliSense
→ Tailwind CSS 클래스 자동완성

MDX
→ .mdx 글 작성 시 문법 강조

Prettier
→ 코드와 문서 포맷 정리

추가로 있으면 편한 확장도 있다.

GitLens
Error Lens
Path Intellisense

처음에는 필수 확장만 설치해도 충분하다.

3. VS Code에서 프로젝트 열기

내 블로그 프로젝트는 로컬에 다음 경로로 관리하고 있다.

cd ~/Dev/projects/chailmon-blog

또는 실제 프로젝트 경로에 맞춰 이동한다.

cd /Users/ib10500014/Developer/projects/chailmon-blog

그다음 VS Code로 프로젝트를 연다.

code .

VS Code의 Explorer에 아래 파일과 폴더가 보이면 프로젝트 루트를 제대로 연 것이다.

astro.config.mjs
package.json
package-lock.json
src
public
templates
wrangler.jsonc

중요한 점은 src 폴더만 여는 것이 아니라, chailmon-blog 프로젝트 폴더 전체를 열어야 한다는 것이다.

4. VS Code 터미널 사용하기

VS Code 안에서 터미널을 열면 프로젝트 폴더를 기준으로 바로 명령어를 실행할 수 있다.

Terminal
→ New Terminal

macOS에서는 단축키로도 열 수 있다.

Control + `

터미널을 열고 현재 위치를 확인한다.

pwd

결과가 chailmon-blog로 끝나면 정상이다.

/Users/ib10500014/Dev/projects/chailmon-blog

VS Code 터미널에서는 앞으로 자주 쓰는 명령어를 바로 실행할 수 있다.

git status
npm run dev
npm run build
git push

5. 프로젝트 폴더 구조 이해하기

VS Code에서 블로그를 관리하려면 자주 수정하는 폴더를 먼저 알아두는 것이 좋다.

src/content/blog
→ 블로그 글 MDX 파일

templates
→ 새 글 작성 템플릿

src/pages
→ 페이지 라우팅

src/components
→ Header, Footer, PostCard 같은 컴포넌트

src/layouts
→ 공통 레이아웃

src/styles/global.css
→ 본문 Typography, 코드블록, 표 스타일

src/lib/categories.ts
→ 카테고리 설정

글만 쓸 때는 대부분 아래 두 위치만 보면 된다.

src/content/blog
templates/blog-post-template.mdx

디자인이나 구조를 바꿀 때는 src/components, src/pages, src/styles/global.css를 수정한다.

6. 새 글은 템플릿으로 시작하기

새 글을 쓸 때는 매번 빈 파일을 만들지 않고, 템플릿을 복사해서 시작한다.

템플릿 파일은 블로그 글 폴더가 아니라 templates 폴더에 둔다.

templates/blog-post-template.mdx

이 위치에 있으면 Astro가 실제 블로그 글로 인식하지 않는다.

새 글을 만들 때는 다음처럼 복사한다.

cp templates/blog-post-template.mdx src/content/blog/new-post-name.mdx

예를 들어 VS Code 작업 흐름 글을 만들 때는 이렇게 했다.

cp templates/blog-post-template.mdx src/content/blog/vscode-astro-blog-workflow.mdx

파일명은 URL이 되기 때문에 영어 소문자와 하이픈을 사용하는 것이 좋다.

좋은 예시는 다음과 같다.

vscode-astro-blog-workflow.mdx
windows-astro-blog-setup-guide.mdx
astro-blog-readability-improvement.mdx

피하고 싶은 예시는 다음과 같다.

새글.mdx
VS Code Blog Guide.mdx
blog_post_1.mdx

7. MDX frontmatter 작성하기

MDX 파일 맨 위에는 글의 메타정보를 넣는다.

---
title: "VS Code로 Astro 블로그 관리하는 방법"
description: "Visual Studio Code에서 Astro 블로그 글을 작성하고 Git으로 관리하는 작업 흐름을 정리합니다."
pubDate: 2026-05-07
updatedDate: 2026-05-07
category: "운영하기"
tags: ["VSCode", "Astro", "Git", "블로그운영"]
draft: false
cover: "/images/og-default.svg"
---

각 항목의 의미는 다음과 같다.

title
→ 글 제목

description
→ 글 목록, SEO, SNS 미리보기에 표시될 설명

pubDate
→ 최초 작성일

updatedDate
→ 수정일

category
→ 글 카테고리

tags
→ 태그 목록

draft
→ 공개 여부

cover
→ OG 이미지

현재 블로그의 카테고리는 세 가지로 제한했다.

만들기
운영하기
써보고 남기기

다른 값을 넣으면 빌드 오류가 날 수 있다.

예를 들어 다음은 잘못된 값이다.

category: "개발"

현재 구조에서는 아래처럼 써야 한다.

category: "운영하기"

8. draft 값으로 공개 여부 관리하기

글을 작성 중일 때는 draft: true로 둔다.

draft: true

이 상태에서는 글이 블로그 목록에 노출되지 않는다.

글을 완성해서 공개할 때는 draft: false로 바꾼다.

draft: false

주의할 점은 draft: true라고 해서 frontmatter 검증을 피할 수 있는 것은 아니라는 것이다.

Astro Content Collection은 초안 글도 먼저 스키마 검증을 한다.

그래서 초안 글도 title, description, pubDate, category, tags 형식은 정확히 맞아야 한다.

9. MDX 본문 작성 방식

frontmatter 아래부터는 Markdown처럼 글을 쓰면 된다.

## 들어가며

이 글에서는 VS Code로 Astro 블로그를 관리하는 방법을 정리합니다.

## 기본 작업 흐름

1. VS Code에서 프로젝트 열기
2. 새 MDX 글 작성하기
3. 로컬 서버로 확인하기
4. Git으로 커밋하기
5. GitHub에 push하기

본문에서는 # 제목보다 ## 제목부터 사용하는 것을 추천한다.

#는 글 제목과 겹칠 수 있기 때문이다.

명령어는 코드블록으로 정리한다.

```bash
npm run dev
npm run build
```

PowerShell 명령어는 다음처럼 구분해서 쓸 수 있다.

```powershell
git status
git add .
git commit -m "Add new post"
git push
```

내부 링크는 상대경로를 사용하는 것이 좋다.

[Astro 블로그 구축 과정](/blog/astro-adsense-blog-build-guide)

10. 로컬에서 글 확인하기

글을 작성하면서 바로 확인하려면 개발 서버를 실행한다.

npm run dev

브라우저에서 확인한다.

http://localhost:4321

글 목록은 다음 주소에서 확인한다.

http://localhost:4321/blog

새 글 주소는 파일명을 기준으로 만들어진다.

src/content/blog/vscode-astro-blog-workflow.mdx
→ http://localhost:4321/blog/vscode-astro-blog-workflow

다만 draft: true 상태라면 실제 페이지가 생성되지 않을 수 있다.

로컬에서 화면 확인이 필요하면 잠시 draft: false로 바꾸고 확인한 뒤, 아직 공개할 글이 아니면 다시 draft: true로 돌려두면 된다.

11. 빌드 확인하기

글을 쓰거나 코드를 수정한 뒤에는 반드시 빌드한다.

npm run build

빌드에서 자주 나는 오류는 다음과 같다.

frontmatter 형식 오류
category 값 오류
tags 배열 문법 오류
MDX 코드블록 닫힘 누락
HTML 태그 닫힘 누락
import 경로 오류

특히 tags는 문자열이 아니라 배열이어야 한다.

잘못된 예시는 다음과 같다.

tags: "Astro, VSCode"

올바른 예시는 다음과 같다.

tags: ["Astro", "VSCode"]

12. Git 변경사항 확인하기

VS Code 왼쪽의 Source Control 아이콘을 누르면 변경된 파일을 확인할 수 있다.

터미널에서는 다음 명령어를 사용한다.

git status

변경 내용을 자세히 보려면 다음 명령어를 쓴다.

git diff

VS Code에서는 변경된 파일을 클릭하면 이전 내용과 현재 내용을 비교해서 볼 수 있다.

이 작업은 매우 중요하다.

커밋 전에 아래를 확인해야 한다.

의도한 파일만 수정됐는지
.env 파일이 포함되지 않았는지
dist 폴더가 커밋 대상에 들어가지 않았는지
draft 값이 의도한 상태인지
category 값이 정해진 세 가지 중 하나인지

13. commit과 push 하기

커밋과 푸시는 터미널에서 하는 방식이 가장 명확하다.

git status
git add .
git commit -m "Add VS Code Astro blog workflow guide"
git push

특정 파일만 커밋하고 싶다면 파일을 지정한다.

git add src/content/blog/vscode-astro-blog-workflow.mdx
git commit -m "Add VS Code Astro blog workflow guide"
git push

VS Code Source Control에서도 커밋할 수 있다.

1. Source Control 아이콘 클릭
2. 변경 파일 확인
3. + 버튼으로 Stage
4. 커밋 메시지 작성
5. Commit 클릭
6. Sync Changes 또는 Push 클릭

하지만 현재는 변경 확인은 VS Code에서 하고, 커밋과 푸시는 터미널에서 하는 방식을 선호한다.

14. Cloudflare 자동 배포 확인하기

GitHub에 push하면 Cloudflare가 자동으로 배포한다.

확인 위치는 다음과 같다.

Cloudflare Dashboard
→ Workers & Pages
→ chailmon-blog
→ Builds 또는 Deployments

배포가 성공하면 실제 사이트에서 확인한다.

https://chailmon.com
https://chailmon.com/blog

새 글을 공개했다면 글 주소도 확인한다.

https://chailmon.com/blog/vscode-astro-blog-workflow

draft: true 상태로 push했다면 Cloudflare 배포는 되지만 운영 블로그에는 노출되지 않는 것이 정상이다.

15. 자주 쓰는 작업 루틴

앞으로 새 글을 쓸 때는 이 순서로 진행한다.

cd ~/Dev/projects/chailmon-blog
git status
git pull

cp templates/blog-post-template.mdx src/content/blog/new-post-name.mdx
code src/content/blog/new-post-name.mdx

npm run dev
npm run build

git status
git add src/content/blog/new-post-name.mdx
git commit -m "Add new blog post"
git push

기존 글을 수정할 때는 템플릿 복사 과정만 빼면 된다.

cd ~/Dev/projects/chailmon-blog
git pull

code src/content/blog/기존글파일명.mdx

npm run dev
npm run build

git status
git add src/content/blog/기존글파일명.mdx
git commit -m "Update blog post"
git push

디자인이나 코드 수정은 파일 위치를 먼저 확인하고 진행한다.

Header 수정
→ src/components/Header.astro

Footer 수정
→ src/components/Footer.astro

글 카드 수정
→ src/components/PostCard.astro

메인 페이지 수정
→ src/pages/index.astro

블로그 목록 수정
→ src/pages/blog/index.astro

글 상세 페이지 수정
→ src/pages/blog/[id].astro

본문 스타일 수정
→ src/styles/global.css

카테고리 수정
→ src/lib/categories.ts

정리

VS Code를 중심으로 블로그를 관리하면 글 작성과 코드 수정, Git 관리가 훨씬 편해진다.

이번에 정리한 핵심 흐름은 다음과 같다.

VS Code에서 프로젝트 열기
MDX 파일로 글 작성
npm run dev로 로컬 확인
npm run build로 배포 전 점검
git status와 diff로 변경사항 확인
commit과 push
Cloudflare 자동 배포 확인

처음에는 터미널 명령어가 많아 보여도, 실제로 반복해서 쓰는 명령어는 많지 않다.

git pull
npm run dev
npm run build
git status
git add .
git commit -m "message"
git push

이 루틴만 익숙해지면 VS Code에서 Astro 블로그를 안정적으로 관리할 수 있다.