블로그 글을 쓰려고 새 화면을 만들 필요는 없습니다. src/content/blog/ 아래에 Markdown 파일 하나를 추가하면 빌드가 글 페이지를 만들고, 언어별 목록·RSS·사이트맵에도 함께 반영합니다. 글쓴이는 본문과 frontmatter만 관리하고, 반복되는 화면과 연결은 사이트 코드가 맡습니다.
왜 관리자 화면을 만들지 않았을까?
이 블로그의 주된 작업은 글을 쓰고 배포하는 일입니다. 관리자 화면을 먼저 만들면 로그인·권한·저장 API·에디터를 함께 운영해야 합니다. 반면 Markdown은 git에서 변경 이력을 볼 수 있고, 글과 코드가 같은 저장소에 있어 한 번의 빌드로 공개 결과를 확인할 수 있습니다.
그래서 글의 입력 단위를 작게 정했습니다.
파일에는 frontmatter를 먼저 적고, 그 아래에 본문과 필요할 때 d3-flow 같은 도식 블록을 둡니다. 이 구조를 글마다 반복하면 별도 에디터 없이도 같은 렌더링 규칙을 사용할 수 있습니다.
파일 하나가 글 하나입니다. 파일명은 URL의 slug가 되므로 처음 정한 이름을 계속 사용합니다. 글을 고치더라도 주소는 바뀌지 않습니다.
frontmatter가 맡는 일
본문 위의 frontmatter에는 제목·설명·발행일·태그를 적습니다. lang을 생략하면 한국어 글이 되고, 다른 언어 글은 lang과 한국어 원문의 pair를 적어 언어 메뉴와 hreflang 연결을 만들 수 있습니다.
---
title: 글 제목
description: 검색 결과에 보일 한 줄 요약
pubDate: 2026-10-24
tags: [Astro, Markdown]
---제목과 설명의 길이는 content schema가 빌드 때 검사합니다. 필수 값이 빠지거나 허용하지 않은 언어가 들어가면 배포 전에 오류를 알 수 있습니다. 글마다 규칙을 기억해서 검사하는 대신, 콘텐츠를 읽는 경계에서 확인하는 방식입니다.
한 파일이 여러 결과가 되는 과정
빌드할 때 Astro content collection이 src/content/blog/*.md를 읽습니다. draft: true인 글은 목록에서 제외하고, 언어별 글은 발행일 최신순으로 정렬합니다. 같은 태그를 가진 글이 충분히 쌓이면 관련 글도 자동으로 붙습니다.
이 흐름의 장점은 연결을 빠뜨릴 수 있는 지점을 줄인다는 데 있습니다. 글 목록에 따로 등록하거나 RSS 파일을 직접 고치지 않습니다. 새 글이 컬렉션에 들어오면 각 결과가 같은 원본에서 만들어집니다.
도식도 본문 안에 함께 둔다
긴 설명에는 직접 만든 D3 도식을 코드 블록으로 넣습니다. 예를 들어 위 흐름도는 d3-flow 블록 안에 JSON을 적은 것입니다. 빌드 플러그인이 이를 SVG로 바꾸므로 외부 이미지나 캡처 파일이 필요하지 않습니다.
도식에 넣는 문장도 본문과 같은 기준으로 씁니다. 확인하지 않은 수치나 운영 정보를 넣지 않고, 글의 흐름을 설명하는 데 필요한 이름만 둡니다. JSON이 잘못되면 빌드 로그의 경고를 보고 수정할 수 있습니다.
글을 추가할 때 확인할 것
새 글을 쓸 때는 네 가지만 확인합니다.
- 파일명이 소문자 영문·숫자·하이픈으로 된 고유 slug인가?
- 제목·설명·발행일이 frontmatter에 있는가?
- 본문에
# H1을 쓰지 않았는가? - D3 도식과 Markdown 문법이 빌드에서 정상 처리되는가?
마지막 확인은 다음 명령으로 합니다.
pnpm --filter site30cut build글 파일을 하나 추가하는 방식은 단순하지만, 단순함을 유지하려면 자동 연결을 믿고 수동 등록을 늘리지 않는 것이 중요합니다. 글의 내용은 Markdown에, 글의 공통 동작은 사이트 코드에 두면 둘 사이의 책임이 섞이지 않습니다.
자주 묻는 질문
나중에 관리자 화면을 추가해야 하나요?
글을 작성하고 검토하는 사람이 늘거나 비개발자 편집이 필요해질 때 검토할 수 있습니다. 현재처럼 git에서 글을 관리하는 흐름이 충분하다면, 관리자 화면은 저장소·권한·에디터를 추가로 운영하는 대가가 생깁니다.
글을 임시로 숨길 수 있나요?
frontmatter에 draft: true를 적으면 빌드 결과에서 제외됩니다. 공개할 때 값을 지우거나 false로 바꾸고 다시 빌드하면 됩니다.
글마다 페이지 코드를 만들어야 하나요?
만들지 않습니다. 컬렉션의 글 데이터를 공통 블로그 페이지 컴포넌트가 읽습니다. 글마다 달라지는 것은 Markdown 파일과 frontmatter입니다.