Skip to main content

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에서 0.1.1을 설치한 환경이라면 두 배포 패키지가 같은 모듈을 사용하므로 설치하기 전에 python -m pip uninstall naru로 제거하세요.

python -m pip install "naru-sitegen==0.1.3"

배포 패키지 이름은 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입니다.

최소 사이트

0.1.3에서는 사이트 폴더의 naru.yml에 이름과 공개 주소만 지정해도 기본 템플릿으로 빌드할 수 있습니다.

site_name: My Journal
site_origin: https://example.com

site_origin은 경로가 없는 HTTP(S) 주소입니다. 게시할 주소로 바꾼 뒤 사이트 폴더에서 다음을 실행합니다.

python -m naru build --site-root . --output dist

글은 content/posts/ 아래 Markdown 파일로 추가합니다. 폴더나 글이 없어도 빈 사이트를 빌드할 수 있습니다. 템플릿, 스타일, 정적 파일은 필요할 때만 사이트에서 제공합니다.

my-site/
├── naru.yml
├── requirements.txt          # 사이트의 Naru 버전 고정
├── content/
│   ├── posts/                # Markdown 글
│   ├── pages/                # Markdown 페이지 (선택)
│   └── data/                 # JSON 카탈로그 (선택)
├── templates/                # 기본 템플릿 덮어쓰기 (선택)
├── static/                   # 정적 파일 (선택)
└── assets/                   # 스타일과 이미지 (선택)

카테고리, 광고, URL 경로 등을 생략하면 기본값을 사용합니다. 생략 가능한 필드라도 값을 지정했다면 유효해야 하며, 알 수 없는 필드는 오류입니다. 사용 가능한 전체 설정은 examples/basic-site/naru.yml을 참고하세요. 작성자 이름을 생략하면 사이트 이름을 사용합니다. 현재 일부 카테고리 설명과 화면 문구는 기존 기술 블로그와 한국어를 전제로 하므로 범용 사이트에 사용하기 전 결과물을 확인하세요.

템플릿과 스타일

별도 템플릿이 없으면 패키지에 포함된 기본 템플릿을 사용합니다. 사이트의 templates/에 같은 이름의 파일이 있으면 그 파일을 우선하고, 없는 파일은 기본 템플릿을 사용합니다. 템플릿 자리 표시자와 페이지 구조는 아직 고정되어 있으므로 다른 생성기의 테마를 그대로 사용할 수는 없습니다.

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

기본 헤더는 패키지의 naru.css를 사용합니다. 스타일을 변경하려면 사이트의 assets/naru.css 또는 static/assets/naru.css를 제공하거나 partial_head.html을 직접 작성하세요. static/tools/를 제공한다면 index.html도 필요합니다.

Markdown 콘텐츠의 front matter에는 title, nav_title, slug, description, published_date, updated_date, tags가 필요합니다. 날짜는 YYYY-MM-DD 형식이며 slug는 소문자 kebab-case를 사용합니다. 소스 트리에서 직접 실행하려면 다음처럼 할 수 있습니다.

$env:PYTHONPATH = "src"
python -m naru --version

개발 방향

  • 템플릿과 페이지 구조의 유연성을 개선합니다.
  • 설정과 렌더링의 결합을 줄여 다양한 사이트 구성을 지원합니다.
  • 기본 템플릿과 사용 문서를 보강합니다.

상세한 경계와 모듈 책임은 설계 문서를 참고하세요.

Metadata

Release files for naru-sitegen 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for naru-sitegen 0.1.3
File Size Uploaded Provenance Actions
naru_sitegen-0.1.3.tar.gz 33.5 kB With provenance Details for naru_sitegen-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for naru-sitegen 0.1.3
File Interpreter ABI Platform Actions
naru_sitegen-0.1.3-py3-none-any.whl Python 3 none any Details for naru_sitegen-0.1.3-py3-none-any.whl

Total release size: 67.7 kB

Release files / naru_sitegen-0.1.3.tar.gz

Download URL naru_sitegen-0.1.3.tar.gz
Size 33.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1ab104b5de28cb33df1dcc5ecf0a2ecf9803371711e4da86e02f09bdd8f8b641
BLAKE2b-256 checksum
How to use checksums
69658aa611814096d55af03d312a1ae224cf87ad506b091a2cee0c90729c64be
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 log

Release files / naru_sitegen-0.1.3-py3-none-any.whl

Download URL naru_sitegen-0.1.3-py3-none-any.whl
Size 34.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
84f7f48ad0c653b6c2ed3f47864077873660ca2016e4c19b48d151755e4e3600
BLAKE2b-256 checksum
How to use checksums
44a97482a62a63b7d90591f7f61b2d5f8d736997ee472f1a82eaa2daf793eb83
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 log

Security for naru-sitegen 0.1.3

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.

Select from 2 files

Attestation for naru_sitegen-0.1.3.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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page