014. JeKyll 컨텐츠 - (7) 컬렉션(Collections) - 사용법과 변수

컨텐츠 - (7) 컬렉션(Collections) - 사용법과 변수

본 카테고리는 정적 블로그 생성도구인 Jekyll에 관하여 작성하는 곳이다.

공식 사이트의 내용을 좀 더 풀어쓰고 스크린샷을 첨부하여 좀 더 상세히 기록하고자 한다.

참고 Jekyll 공식 사이트

컬렉션(Collections) - 사용법과 변수

Jekyll에서 생성하는 컨텐츠가 모두 페이지나 포스트는 아닐 것이다.

자신의 오픈 소스 프로젝트나 팀원들 목록, 또는 컨퍼런스에서 오고 간 대화 내용을 문서화하는 경우도 있을 것이다.

Jekyll에서 제공하는 컬렉션 기능을 사용하면 페이지 혹은 포스트와 유사하게 동작하지만 고유한 속성와 네임스페이스를 가진 새로운 유형의 문서를 정의할 수 있다.

컬렉션 사용하기

컬렉션을 사용하려면 아래의 3단계를 따라 진행하면 된다.

단 3번째는 선택사항으로 꼭 수행할 필요는 없다.

1단계 : Jekyll이 컬렉션을 읽어들이게 하기
2단계 : 컨텐츠 추가
3단계 : 컬렉션 문서의 독립적 렌더링(Option)

1단계 : Jekyll이 컬렉션을 읽어들이게 하기

_config.yml 파일에 아래와 같은 속성을 추가한다.

collections:
- my_collection # 컬렉션 이름

위의 my_collection은 임의의 컬렉션명을 자신이 원하는 이름으로 교체하면 된다.

_config.yml 파일에서 컬렉션에 대한 메타 데이터를 정의할 수 있다.

collections:
  my_collection:
    foo: bar

또한 컬렉션의 기본적인 속성값들을 설정할 수도 있다.

defaults:
  - scope:
      path: ""
      type: my_collection
    values:
      layout: page

2단계 : 컨텐츠 추가

다음으로 _config.yml에 설정한 컬렉션 명으로 된 폴더를 만들어야 한다.

위에 예제대로라면 _my_collection이름의 폴더를 생성하면 된다.

폴더를 생성한 뒤 해당 폴더에 문서를 추가하면 된다.

Jekyll이 관리하는 모든 파일이 그렇듯이 YAML 머리말을 추가하면 Jekyll이 처리해준다.

YAML 머리말 이후의 영역은 문서의 content 속성으로 설정되며, YAML 머리말이 없으면 Jekyll에선 해당 컬렉션에 파일을 생성하지 않는다.

주의 컬렉션 디렉토리의 이름을 명확히 해야한다.
_config.yml에 설정한 컬렉션명과 접두사로 _를 추가하면 된다.

3단계 : 컬렉션 문서의 독립적 렌더링(Option)

위의 1단계, 2단계를 컬렉션을 사용하기 위해 필수적인 사항이며, 3단계는 선택사항이다.

Jekyll이 컬렉션에 속한 각각의 문서가 독립적인 버전으로 렌더링하게 하려면 아래와 같이 output 키를 추가하고 true로 설정하여 활성화한다.

collections:
  my_collection:
    output: true

위와 같이 _config.yml파일을 설정하면 컬렉션 내 모든 문서가 각각의 파일로 생성된다.

예를 들어 _my_collection/some_subdir/some_doc.md라는 파일이 있다고 가정하자.

이 파일은 Liquid와 Markdown 변환기와 거쳐 렌더링되고 _config.yml에 설정된 <destination> 경로에 맞춰 파일을 생성할 것이다.

즉 <destination>/my_collection/some_subdir/some_doc.html이라는 파일이 생성된다.

참고 컬렉션에는 꼭 YAML 머리말을 추가해야 한다.
머리말이 존재하지않으면 정적파일로 취급되어 출력 경로에 단순 복사되는 작업만 수행한다.

컬렉션에 대한 permalink 구성

위의 컬렉션 생성 예제 코드를 다시 보자.

collections:
  my_collection:
    output: true

위와 같은 상황일 때 _my_collection/some_subdir/some_doc.md파일은 <destination>/my_collection/some_subdir/some_doc.html로 변환된다.

이처럼 생성되는 컬렉션에 속한 문서는 포스트와 마찬가지로 permalinks를 활용하여 고유 주소를 부여할 수 있다.

collections:
  my_collection:
    output: true
    permalink: /awesome/:path/:title.:output_ext

위의 환경설정에 의해 awesome으로 시작하는 URL과 문서 이름 그리고 파일의 확장명을 가진다.

즉 아래와 같은 경로에 생성된다.

<destination>/awesome/some_subdir/some_doc.html

위의 permalinks에 사용할 수 있는 템플릿 변수는 아래와 같다.

변수	설명
collection	콜렉션의 제목
path	컬렉션의 디렉토리를 기준으로한 문서들의 경로
name	문서의 기본 파일 이름 공백과 문자나 숫자가 아닌 문자는 -으로 치환
title	문서의 소문자 제목 공백과 문자나 숫자가 아닌 문자는 -으로 치환
output_ext	출력되는 파일의 확장자

컬렉션에 대한 permalink 예제

_config.yml에서 permalink를 설정하는 방법에 따라 고유 주소와 경로는 _site 폴더에 다르게 작성된다.

예시를 통해 좀 더 빠르게 학습해보자.

본 예시에 들어가기전에 먼저 예시에 쓸 디렉토리 구조에 대해서 정의하자.

├── \_apidocs
│   └── mydocs
│       └── doc1.md

위의 디렉토리 구조를 해석하면 apidocs라는 컬렉션이 있고, doc1.md 문서는 mydocs라는 폴더 안에 그룹화되어있다.

이 상황에서 예시를 하나씩 확인해보자.

예시에서 나오는 디렉토리 구조는 생성된 결과물이다.

permalink 구성 [1] 설정된 값이 없을 때

├── apidocs
│   └── mydocs
│       └── doc1.html

permalink 구성 [2]: /:collection/:path/:title:output_ext

├── apidocs
│   └── mydocs
│       └── doc1.html

permalink 구성 [3]: 컬렉션의 permalink가 설정되지 않았지만 페이지나 포스트에 구성된 경우

├── apidocs
│   └── mydocs
│       └── doc1
│           └── index.html

permalink 구성 [4]: /awesome/:path/:title.html

├── awesome
│   └── mydocs
│       └── doc1.html

permalink 구성 [5]: /awesome/:path/:title

├── awesome
│   └── mydocs
│       └── doc1
│           └── index.html

permalink 구성 [6]: /awesome/:title.html

├── awesome
│   └── doc1.html

permalink 구성 [7]: :title.html

├── doc1.html