JSON과 Markdown으로 사이트 운영하기: Naru 정적 사이트 생성기와 GitHub Pages
Naru의 기본 템플릿으로 Markdown 글과 JSON 카탈로그를 만들고 GitHub Actions와 GitHub Pages로 배포합니다.
사이트를 운영할 때 글을 추가할 때마다 HTML을 직접 만들고 배포 파일을 정리하는 일은 번거롭다. Naru는 Markdown과 JSON으로 콘텐츠를 관리하고, Python 패키지에 포함된 템플릿으로 정적 사이트를 만드는 생성기다.
사이트마다 생성기 코드를 복사하지 않아도 된다. 사이트 저장소에는 설정과 콘텐츠를 두고, GitHub Actions가 고정된 Naru 버전을 설치해 빌드한 뒤 GitHub Pages에 결과물을 전달한다.
이 글은 Naru 0.1.3, Python 3.11 이상과 Windows PowerShell을 기준으로 한다. 예제는 myname.github.io 형태의 GitHub 사용자 사이트를 사용한다. myname은 자신의 GitHub 사용자 이름으로 바꾼다.
1. 전체 구조와 준비물
내 사이트 저장소
├── naru.yml 사이트 이름과 공개 주소
├── requirements.txt Naru 버전
├── content/
│ ├── posts/ Markdown 글
│ └── data/ JSON 카탈로그
└── .github/workflows/ GitHub Actions 배포 설정
│
├── PyPI에서 naru-sitegen 설치
├── dist/에 사이트 빌드
└── GitHub Pages에 배포
naru-sitegen은 PyPI 패키지 이름이고, 실행 명령은 python -m naru다. HTML 템플릿과 기본 CSS는 패키지에 들어 있으므로 이 예제에서 따로 만들지 않는다.
준비할 것은 Python 3.11 이상, Git, GitHub 계정과 인터넷 연결이다. GitHub Free에서 새 Pages 사이트를 만들 때는 공개 저장소를 사용한다. 저장소 조건은 GitHub Pages 사이트 만들기를 확인한다. Pages로 게시된 내용은 공개되므로 비밀키나 비공개 자료를 넣지 않는다.
2. 작업 폴더와 의존성 만들기
PowerShell에서 새 빈 폴더를 만든다. 기존 프로젝트가 있다면 먼저 별도 폴더에서 실습한다.
mkdir naru-demo
Set-Location naru-demo
python --version
python -m venv .venv
작업 폴더에 ./requirements.txt를 만들고 다음 한 줄을 저장한다.
naru-sitegen==0.1.3
가상환경을 활성화하지 않아도 그 안의 Python으로 설치하고 실행할 수 있다.
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m naru --version
naru 0.1.3이 출력되면 준비가 끝났다. 이 파일은 Naru 버전을 고정하지만 하위 의존성의 정확한 버전까지 잠그지는 않는다. 콘솔에서 한글이 깨지면 현재 PowerShell 창에서 $env:PYTHONUTF8 = "1"을 설정한다.
3. 사이트 설정하기
작업 폴더에 ./naru.yml을 만들고 사이트 이름과 실제 공개 주소를 적는다.
site_name: My Journal
site_origin: https://myname.github.io
이 두 항목이 필수다. site_origin에는 경로를 넣지 않는다. 사용자 사이트의 루트에서 서비스할 때는 별도 base_url이 필요 없다. 사이트 설명과 작성자 이름을 바꾸고 싶다면 다음처럼 추가할 수 있다.
site_name: My Journal
site_origin: https://myname.github.io
site_description: 만들고 배운 것을 기록하는 공간
author_name: My Name
작성자 이름을 생략하면 사이트 이름을 사용한다. 추가 설정과 기본값은 Naru의 설정 예제를 참고한다. 오타가 있는 필드나 잘못된 값은 무시하지 않고 오류로 알려 준다.
4. Markdown으로 첫 글 쓰기
content/posts/ 폴더를 만들고 그 안에 ./first-post.md를 저장한다.
---
title: 첫 글
nav_title: 첫 글
slug: first-post
description: Naru로 작성한 첫 글
published_date: '2026-01-01'
updated_date: '2026-01-01'
category: blog
tags: [Naru]
---
안녕하세요. Markdown으로 작성한 첫 글입니다.
## 기록하고 싶은 것
사이트의 원본은 Markdown으로 관리합니다.
위쪽의 --- 사이를 front matter라고 한다. 제목, 설명, 게시일, 수정일, 태그와 주소에 사용할 slug를 적는다. 날짜는 YYYY-MM-DD, slug는 영문 소문자와 하이픈으로 작성한다. 수정일은 게시일보다 빠를 수 없다. 카테고리는 같은 주제의 글을 모으는 데 사용한다.
글이 없어도 빈 사이트는 빌드할 수 있다. 새 글을 쓸 때는 Markdown 파일을 추가하고 slug가 다른 글과 겹치지 않는지 확인한다.
5. JSON으로 링크 카탈로그 만들기
JSON 카탈로그가 필요하면 content/data/에 파일을 추가한다. 필요하지 않다면 이 단계와 폴더를 생략해도 된다. 예를 들어 content/data/links.json을 다음처럼 작성한다.
{
"page_info": {
"title": "참고 링크",
"nav_title": "참고 링크",
"slug": "links",
"description": "자주 참고하는 문서 모음",
"published_date": "2026-01-01",
"updated_date": "2026-01-01",
"tags": ["문서"]
},
"sites": [
{
"id": "python",
"name": "Python",
"url": "https://www.python.org/",
"description": "Python 공식 사이트",
"status": "active"
}
]
}
page_info는 카탈로그 페이지의 정보이고 sites는 목록이다. 빌드하면 이 예제의 페이지는 /links/에 생성된다. status는 화면에 표시할 값이므로 실제 접속 상태를 자동으로 검사한다는 뜻은 아니다. 링크와 상태는 운영자가 확인하고 갱신해야 한다.
6. 로컬 빌드와 미리보기
작업 폴더에 .gitignore를 만들고 가상환경과 빌드 결과물을 제외한다.
.venv/
dist/
__pycache__/
사이트 루트에서 다음 명령을 실행한다.
.\.venv\Scripts\python.exe -m naru build --site-root . --output dist
성공하면 dist/index.html과 첫 글의 dist/posts/first-post/index.html이 생긴다. JSON 예제를 추가했다면 dist/links/index.html도 만들어진다. RSS와 사이트맵도 결과물에 포함된다.
.\.venv\Scripts\python.exe -m http.server 8000 --directory dist
브라우저에서 http://localhost:8000/을 열어 홈과 글, 카탈로그를 확인한다. 마친 뒤 PowerShell에서 Ctrl+C로 서버를 종료한다. 이 서버는 로컬 확인용이다.
Naru는 비어 있는 출력 폴더나 같은 사이트의 .naru-output 표식이 있는 폴더만 사용한다. 기존 파일이 든 폴더에서 오류가 나면 내용을 무작정 지우지 말고 비어 있는 다른 출력 경로를 지정한다. 로컬 재빌드에는 표식을 남겨 둔다. --output을 생략하면 기본 출력은 docs이므로 dist를 사용하려면 위처럼 명시한다.
7. GitHub 저장소 연결하기
GitHub에서 New repository를 선택해 myname.github.io라는 공개 저장소를 만든다. 사용자 사이트 저장소 이름의 조건은 GitHub 공식 문서를 확인한다.
새 빈 저장소를 연결하는 예시는 다음과 같다.
git init
git branch -M main
git remote add origin https://github.com/myname/myname.github.io.git
URL을 자신의 계정으로 바꾼다. 이미 Git 저장소나 원격 저장소가 있다면 위 명령을 반복하기 전에 현재 설정을 확인한다. GitHub에 push하려면 별도로 Git 인증이 필요하다.
8. GitHub Actions로 Pages 배포하기
.github/workflows/deploy.yml 파일을 만들고 다음 내용을 저장한다. 이 예제는 GitHub의 공식 Pages artifact 방식을 사용한다.
name: Deploy Naru site
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
cache: pip
cache-dependency-path: requirements.txt
- uses: actions/configure-pages@v5
- name: Install Naru and build
run: |
python -m pip install -r requirements.txt
python -m naru build --site-root . --output dist
python -c "from pathlib import Path; Path('dist/.naru-output').unlink(); Path('dist/CNAME').unlink()"
- uses: actions/upload-pages-artifact@v3
with:
path: dist
- id: deployment
uses: actions/deploy-pages@v4
이 워크플로는 저장소를 내려받아 같은 Naru 버전을 설치하고 dist를 빌드한다. 사이트의 로컬 경로가 들어 있는 .naru-output은 공개 artifact에서 제외한다. 이 예제는 기본 Pages 주소를 사용하므로 Naru가 만든 CNAME도 artifact에서 제외한다. 두 파일의 삭제는 Actions에서 새로 만든 결과물에만 적용하며, 로컬 재빌드용 표식은 지우지 않는다.
GITHUB_TOKEN은 GitHub가 제공하므로 개인 토큰을 코드에 적지 않는다. Pages 배포 권한과 설정은 GitHub Actions Pages 배포 문서를 참고한다.
9. Pages 설정과 첫 배포
저장소의 Settings → Pages → Build and deployment → Source에서 GitHub Actions를 선택한다. 기존 사이트를 변경하는 경우에는 먼저 기존 Pages 설정과 도메인을 확인한다.
사이트 원본과 워크플로를 커밋하고 push한다.
git status --short
git add .gitignore requirements.txt naru.yml content .github
git diff --cached --stat
git commit -m "Add Naru site"
git push -u origin main
저장소의 Actions 탭에서 Deploy Naru site의 설치, 빌드, artifact 업로드와 배포 단계가 성공했는지 확인한다. Pages 설정에 표시된 주소에서 홈과 글을 열어 본다. 계정과 저장소 정책에 따라 추가 권한이나 설정이 필요할 수 있다.
이 글의 공식 Pages artifact 워크플로는 예제다. GitHub 저장소 설정과 실제 배포는 각자의 환경에서 확인해야 한다.
10. 기본 템플릿과 사이트 설정 바꾸기
기본 화면으로 충분하다면 템플릿을 만들 필요가 없다. 특정 템플릿을 바꾸고 싶을 때만 사이트의 templates/에 같은 이름의 파일을 두면 그 파일을 우선 사용한다. 나머지 템플릿은 패키지 기본값을 사용한다.
스타일을 바꾸려면 assets/naru.css 또는 static/assets/naru.css를 제공한다. 자체 head 템플릿을 사용한다면 CSS 연결도 직접 관리한다. 가능한 템플릿 이름과 전체 설정은 Naru 사용 문서를 참고한다.
현재 템플릿 자리 표시자와 페이지 구조는 정해져 있고, 일부 화면과 카테고리 설명은 한국어 기술 블로그를 전제로 한다. 어떤 사이트든 완전히 자유롭게 꾸미는 범용 테마 시스템은 아니므로 결과물을 확인한 뒤 필요한 부분을 바꾼다.
https://myname.github.io/project/ 같은 프로젝트 사이트는 base_url: /project를 설정할 수 있다. 다만 직접 작성한 템플릿과 정적 파일의 절대 경로는 자동으로 고쳐 주지 않는다. 이 글의 배포 실습은 루트 사용자 사이트 기준이며 하위 경로는 별도로 검증해야 한다.
11. DevBJ와 새 버전 적용
DevBJ도 사이트 원본과 Naru 패키지를 분리한다. 다만 위 예제의 공식 Pages artifact 방식이 아니라, Actions에서 dist를 만든 다음 peaceiris/actions-gh-pages로 배포 전용 gh-pages 브랜치에 올린다. 사용자 지정 도메인 devbj.com도 별도로 설정되어 있다. 두 방식은 대안이므로 새 사이트에서 둘을 동시에 설정할 필요는 없다.
글을 추가하거나 JSON을 수정할 때는 원본을 고치고 다시 빌드한다. Naru가 새 버전으로 배포되어도 고정된 버전은 자동으로 바뀌지 않는다. 적용하려면 PyPI의 Naru 페이지에서 버전을 확인하고 다음 순서로 진행한다.
./requirements.txt의 버전을 바꾼다.- 패키지를 다시 설치하고 로컬 빌드를 실행한다.
- 주요 페이지, 링크, RSS와 사이트맵을 확인한다.
- 원본과 의존성 변경을 커밋하고 배포한다.
문제가 있다면 이전에 검증한 버전으로 되돌려 다시 빌드할 수 있다. 여러 사이트가 같은 패키지를 쓰더라도 적용 시점은 사이트마다 따로 정할 수 있다.
막혔을 때 확인할 것
No module named naru: 설치와 실행에 서로 다른 Python을 사용했는지 확인한다. 위 예제처럼 가상환경의 Python으로 통일한다.- 버전을 찾을 수 없음: 패키지 미러나 캐시가 최신 버전을 반영하지 않았을 수 있다. PyPI 게시 여부를 확인한 뒤
.\.venv\Scripts\python.exe -m pip install --no-cache-dir --index-url https://pypi.org/simple -r requirements.txt로 캐시 없이 공식 인덱스를 지정해 볼 수 있다. - 설정 오류: 필수 항목과 들여쓰기,
site_origin주소, 필드 이름을 확인한다. - 글 또는 JSON 오류: 필수 메타데이터, 날짜, slug와 JSON 문법을 확인한다.
- 출력 폴더 관리 오류: 기존 파일을 보존하고 비어 있는 새 출력 폴더를 지정한다.
- Actions 권한 오류: Pages Source, 저장소 정책,
pages와id-token권한을 확인한다. - 배포 후 주소나 화면이 다름: 실제 Pages 주소와
site_origin,base_url, 템플릿의 링크를 확인한다.