예제
KO

콘텐츠 파일

content/ 디렉터리에 놓인 마크다운 이외 파일을 출력 디렉터리로 자동 게시할 수 있습니다. 이미지, PDF처럼 콘텐츠 옆에 함께 두는 에셋을 다룰 때 유용합니다.

설정

config.toml에서 콘텐츠 파일 게시를 활성화합니다:

[content.files]
allow_extensions = ["jpg", "jpeg", "png", "gif", "svg", "webp", "pdf"]
disallow_extensions = ["psd", "ai"]
disallow_paths = ["drafts/**", "**/_*"]
키 타입 기본값 설명
allow_extensions array [] 게시할 파일 확장자
disallow_extensions array [] 제외할 파일 확장자
disallow_paths array [] 제외할 경로의 글롭(glob) 패턴

동작 방식

콘텐츠 파일 게시가 활성화되면 Hwaro는 content/의 마크다운 이외 파일을 디렉터리 구조를 유지한 채 출력 디렉터리로 복사합니다.

예시

content/
├── about/
│   ├── index.md          → /about/index.html
│   ├── team-photo.jpg    → /about/team-photo.jpg
│   └── resume.pdf        → /about/resume.pdf
├── blog/
│   ├── _index.md         → /blog/index.html
│   └── my-post/
│       ├── index.md      → /blog/my-post/index.html
│       ├── diagram.svg   → /blog/my-post/diagram.svg
│       └── screenshot.png → /blog/my-post/screenshot.png
└── index.md              → /index.html

파일은 대응하는 출력 경로로 그대로 복사되며, content/ 접두사는 자동으로 제거됩니다.

게시되지 않는 번들

게시되지 않는 페이지의 페이지 번들 안에 있는 파일도 복사되지 않습니다. 초안(--drafts로 빌드하지 않은 경우), 날짜가 미래인 페이지(--include-future 없이), 만료된 페이지(--include-expired 없이)가 해당합니다. 위 예시에서 blog/my-post/index.md에 draft = true를 설정하면 diagram.svg와 screenshot.png도 게시되지 않습니다. 게시되지 않는 번들 안에 중첩된, 게시되는 번들은 자신의 파일을 그대로 게시합니다.

JSON과 XML 파일

content/ 아래의 .json과 .xml 파일은 allow_extensions에 없어도 원본 파일로 게시됩니다(--minify 시 축소). 다만 아래의 차단 규칙(disallow_extensions, disallow_paths)과 위의 게시되지 않는 번들 규칙은 그대로 적용됩니다.

출력 경로 충돌

콘텐츠 파일은 페이지나 생성된 파일을 덮어쓰지 않습니다. 렌더링된 페이지(content/about.md 옆의 content/about/index.html), 별칭 리다이렉트, 피드, 사이트맵, robots.txt 등 생성된 파일과 같은 출력 경로에 놓이게 되면 생성된 출력이 유지되고, 빌드는 Not publishing content/… 경고를 출력합니다. static/의 파일도 같은 규칙을 따릅니다.

확장자 매칭

허용 목록

allow_extensions에 있는 확장자의 파일만 게시됩니다:

[content.files]
allow_extensions = ["jpg", "jpeg", "png", "gif", "svg", "webp"]

확장자는 정규화되므로 "jpg"와 ".jpg" 둘 다 쓸 수 있습니다.

차단 목록

disallow_extensions로 특정 확장자를 제외합니다:

[content.files]
allow_extensions = ["jpg", "png", "gif", "svg"]
disallow_extensions = ["psd", "ai", "sketch"]

차단 목록이 허용 목록보다 우선합니다.

경로 제외

글롭 문법으로 경로 패턴에 맞는 파일을 제외합니다:

[content.files]
disallow_paths = ["drafts/**", "**/_*", "private/**"]
패턴 매칭 대상
drafts/** content/drafts/ 아래 모든 파일
**/_* 밑줄로 시작하는 모든 파일
private/** content/private/ 아래 모든 파일

경로는 content/ 디렉터리 기준 상대 경로로 매칭됩니다. 거부 규칙(disallow_extensions, disallow_paths)은 allow_extensions 설정 여부와 관계없이 페이지 번들 안의 파일에도 적용됩니다.

콘텐츠 파일 참조

마크다운에서

같은 위치에 둔 파일은 상대 경로로 참조합니다:

![Team Photo](team-photo.jpg)

[Download Resume](resume.pdf)

![Diagram](diagram.svg)

템플릿에서

페이지 번들에서는 함께 둔 에셋을 page.assets로도 쓸 수 있습니다:

{% for asset in page.assets %}
  {% if asset is matching("[.](jpg|png|gif)$") %}
    <img src="{{ get_url(path=asset) }}" alt="Asset">
  {% endif %}
{% endfor %}

콘텐츠 파일 vs 정적 파일

항목 콘텐츠 파일 (content/) 정적 파일 (static/)
콘텐츠와 같은 위치에 배치 ✅ 가능 ❌ 불가
설정 필요 ✅ 필요 ❌ 불필요 (기본으로 복사, 불필요 파일은 필터링)
확장자 필터링 ✅ 지원 ❌ 미지원
경로 필터링 ✅ 지원 (disallow_paths) ✅ 지원 ([static] exclude)
적합한 용도 페이지별 에셋 사이트 전역 에셋

특정 페이지에 속한 에셋(스크린샷, 다이어그램, 첨부 파일)에는 콘텐츠 파일을, 사이트 전역 에셋(CSS, JS, 로고, 파비콘)에는 정적 파일을 사용합니다. 불필요한 파일이나 특정 경로를 제외하는 방법은 설정의 [static] 섹션을 참고하면 됩니다.

팁

함께 보기