Naru
콘텐츠는 각자, 생성기는 함께.
Naru는 여러 사이트가 하나의 정적 사이트 생성 엔진을 공유하면서도 설정, 콘텐츠, 테마와 빌드 결과물은 각 프로젝트 안에서 독립적으로 관리하기 위한 Python 기반 생성기 프로젝트입니다.
0.1 시험판: 현재는 정해진 템플릿과 콘텐츠 구조를 사용합니다. 범용 테마와 자유로운 페이지 구조는 아직 지원하지 않습니다.
기능
naru.yml을 이용한 사이트 설정과 출력 경로 분리- Markdown과 YAML front matter를 이용한 글·페이지 생성
- 카테고리·태그 아카이브, RSS, sitemap, robots.txt 생성
- 정적 파일과 글에 첨부한 이미지 복사
프로젝트 구조
naru/
├── .github/workflows/ci.yml
├── docs/ # 설계 및 사용자 문서
├── examples/basic-site/ # 사이트 설정과 콘텐츠 예시
├── src/naru/ # 설치 가능한 Python 패키지와 CLI
├── tests/ # 자동화 테스트
├── pyproject.toml
└── README.md
설치
Python 3.11 이상과 Git이 필요합니다. GitHub의 고정 태그로 설치할 수 있습니다.
python -m pip install "git+https://github.com/bjnhur/naru.git@v0.1.1"
PyPI에 0.1.2가 게시된 후에는 Git 없이 다음과 같이 버전을 고정해 설치할
수 있습니다.
python -m pip install "naru-sitegen==0.1.2"
배포 패키지 이름은 naru-sitegen이며 Python 모듈과 CLI 이름은 naru입니다.
각 사이트는 검증한 버전을 의존성 파일에 고정하고, 새 버전이 나왔을 때
사이트 빌드를 검증한 후 버전을 갱신합니다.
PyPI 배포
최초 게시 전에 PyPI 계정에서 새 프로젝트 naru-sitegen의 pending trusted
publisher를 등록합니다. 소유자는 bjnhur, 저장소는 naru, 워크플로 파일은
publish.yml, 환경은 pypi입니다. GitHub 저장소에 같은 이름의 환경이
필요하며 필요한 경우 환경 보호 규칙을 설정합니다.
버전을 올릴 때는 pyproject.toml과 src/naru/__init__.py의 버전 및 CLI
테스트를 함께 갱신하고 테스트를 통과시킵니다. 변경을 기본 브랜치에 반영한
후 같은 커밋에 v 접두사가 붙은 버전 태그를 만들고 push합니다. 예를 들어
0.1.2의 태그는 v0.1.2입니다. 태그 push 시 워크플로가 태그와 버전 일치,
테스트 및 배포 파일을 확인한 후 PyPI에
게시합니다. 한 번 업로드한 배포 파일은 동일한 이름으로 다시 업로드할 수
없으므로, 게시 후 변경에는 새 버전이 필요합니다.
개발 환경
Python 3.11 이상이 필요합니다.
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
CLI 기반을 확인합니다.
naru --help
naru --version
사이트 프로젝트에서 빌드를 실행합니다.
naru build --site-root . --output _site
사이트 루트의 naru.yml을 읽습니다. --output을 생략하면
<site-root>/docs를 사용합니다. 출력 폴더는 비어 있거나 같은 사이트의
Naru가 생성한 .naru-output 표식이 있어야 합니다. 기존 폴더를 자동으로
인수하지 않으므로 처음에는 빈 출력 경로를 지정하세요. Naru가 관리하는
출력 폴더의 HTML과 일부 정적 파일은 빌드할 때 정리·교체하므로, 직접 작성한
파일을 그곳에 두지 마세요. 설정 예시는 examples/basic-site/naru.yml입니다.
예제에는 빌드에 필요한 템플릿과 정적 파일이 포함되지 않아 그대로 빌드할 수
없습니다.
사이트 구조
현재 버전은 아래 디렉터리와 템플릿 파일을 사용합니다.
my-site/
├── naru.yml
├── content/
│ ├── posts/ # Markdown 글
│ ├── pages/ # Markdown 페이지 (선택)
│ └── data/ # JSON 카탈로그 (선택)
├── templates/
│ ├── template_index.html, template_post.html
│ ├── template_catalog.html, template_archive.html
│ └── partial_head.html, partial_googletag.html, partial_nav.html, partial_footer.html
├── static/
│ └── tools/index.html
└── assets/
Markdown 콘텐츠의 front matter에는 title, nav_title, slug,
description, published_date, updated_date, tags가 필요합니다.
날짜는 YYYY-MM-DD 형식이며 slug는 소문자 kebab-case를 사용합니다.
현재 HTML 렌더링은 정해진 템플릿과 페이지 구조를 전제로 하므로, 임의의
템플릿이나 테마가 그대로 동작한다고 보장하지 않습니다.
소스 트리에서 직접 실행하려면 다음처럼 할 수 있습니다.
$env:PYTHONPATH = "src"
python -m naru --version
개발 방향
- 템플릿과 페이지 구조의 유연성을 개선합니다.
- 설정과 렌더링의 결합을 줄여 다양한 사이트 구성을 지원합니다.
- 완전하게 빌드할 수 있는 예제와 사용 문서를 보강합니다.
상세한 경계와 모듈 책임은 설계 문서를 참고하세요.
Metadata
Release files for naru-sitegen 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| naru_sitegen-0.1.2.tar.gz | 30.4 kB | With provenance | Details for naru_sitegen-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| naru_sitegen-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for naru_sitegen-0.1.2-py3-none-any.whl |
Total release size: 60.1 kB
Release files / naru_sitegen-0.1.2.tar.gz
| Download URL | naru_sitegen-0.1.2.tar.gz |
|---|---|
| Size | 30.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
18e5f38b7091ac01aed98a1cc1d6b148a1e258175979b47dc213be47e47405a4
|
|
BLAKE2b-256 checksum How to use checksums |
8d7d9e5e8974b50a1b4470cf81727091a07bebea4188661731e65254a9a172a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / naru_sitegen-0.1.2-py3-none-any.whl
| Download URL | naru_sitegen-0.1.2-py3-none-any.whl |
|---|---|
| Size | 29.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e77edd5140ca0d74399b46c73aaa8fdb2656f88eb8ea4987f9de0539b4b34335
|
|
BLAKE2b-256 checksum How to use checksums |
2671935c1411f5f0eae8b85529000af26c0b4020be05d95185a885c007f9eaf5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for naru-sitegen 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for naru_sitegen-0.1.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.