---
title: Blog 사용법
date: 2026-07-04
type: guide
domain: homelab
tags: [hugo, blog, usage, papermod]
---


이 blog(`~/blog`)에 글을 쓰는 방법 요약. 전체 설계는 `~/Documents/docs/knowledge-base-architecture.md` 참조.

## 번들 구조: 문서 1건 = 폴더 1개

```
<번들 슬러그>/
├── index.md      <- 본문 (markdown 원본 그대로)
└── files/        <- 이 글에서 나온 코드·그림·스크립트
    └── verify.sh
```

본문에서는 `files/<파일명>` 형태의 상대 링크로 부속 산출물을 참조한다. 예: `[검증 스크립트](files/sample.sh)`.

## logs vs docs

| 기준 | `content/logs/` | `content/docs/<도메인>/` |
|---|---|---|
| 내용 | 그날의 작업 기록 | 두고두고 볼 지식 |
| 공개 범위 | private (Caddy basic auth) | public |
| 정렬 | 시간순 (`YYYY-MM-DD_<slug>`) | 도메인별 (`<slug>`, 날짜는 frontmatter) |
| 홈 피드/RSS/sitemap/검색 | 제외 (cascade로 차단) | 노출 |

기본은 로그로 남긴다. 두고두고 볼 가치가 있다고 판단되면 로그에서 정제해 `content/docs/<도메인>/`에 **새 글로 파생**한다 (원 로그는 그대로 둠 — 이동이 아니라 정제 재작성).

## frontmatter 계약

```yaml
title: string
date: YYYY-MM-DD
type: log | guide | runbook | note | ref
domain: <도메인 태그>
tags: [ ... ]
```

`archetypes/logs.md`, `archetypes/docs.md`로 각 섹션에 맞는 기본 frontmatter가 채워진 새 글을 만들 수 있다:

```bash
hugo new content/logs/2026-07-05_example/index.md
hugo new content/docs/homelab/example/index.md
```

## raw markdown 보기

모든 글 페이지 본문 하단에 **Raw Markdown** 링크가 붙는다. 이 링크는 같은 URL 경로의 `index.md`로 연결되며, 렌더링 없이 frontmatter + 원본 markdown 그대로를 반환한다 (custom output format, `layouts/single.markdown.md`). 예: 이 글의 raw 원본은 이 페이지 URL 뒤에 `index.md`를 붙이면 된다.

## 도메인

기존 도메인(istio, k8s, kernel, networking, ebpf, llm, homelab)을 우선 사용한다. 새 도메인은 독립 주제 + 5건 이상일 때만 신설한다.