021. JeKyll 커스터마이징 - (4) Includes

커스터마이징 - (4) Includes

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

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

참고 Jekyll 공식 사이트

Includes

include 태그를 사용하면 _includes 디렉토리에 저장된 다른 파일의 내용을 포함시킬 수 있다.

아래의 예시를 보자.

1
{% include footer.html %}

위의 예제를 실행하면 해당 태그가 위치한 곳에 footer.html파일의 내용을 추가한다.

_includes 폴더에 속하지 않은 다른 파일 포함

include_relative 태그를 사용하여 _includes 폴더가 아닌 다른 폴더에 존재하는 파일을 포함할 수 있다.

1
{% include_relative somedir/footer.html %}

위와 같이 작성하면 footer.html 파일은 _includes 폴더에 존재할 필요가 없다.

대신 footer.htmlsomedir 폴더내에 존재하고 있어야 한다.

예를 들어 _posts/2014-09-03-my-file.markdowninclude_relative태그를 사용해서 포함시키려면 2014-09-03-my-file.markdown파일은 _posts 폴더나 하위 디렉토리 중 한 곳에 존재해야 한다.

include_relative를 사용하더라도 ../를 통해 상위 디렉토리를 참조할 순 없다.

추가적으로 include 태그에 사용할 수 있는 모든 기능과 변수는 include_relative 태그 에서도 사용할 수 있다.

파일명 대신 변수명 사용

파일을 포함시킬때 무조건 파일명만 사용할 필요는 없다.

포함할 파일명은 YAML 머리말에서 변수로 선언해둔 뒤 이 변수를 통해 포함시킬 수도 있다.

아래의 YAML 머리말 예제를 보자.

1
2
3
4
---
title: My page
my_variable: footer_company_a.html
---

머리말에서 footer_company_a.html 파일명을 my_variable이라는 변수로 선언해 둔 뒤 아래와 같이 참조하면 된다.

1
{% include {{page.my_variable}} %}

위의 예제에서 include_includes/footer_company_a.html 경로에 있는 파일을 포함시킨다.

include에 파라미터 전달

include에도 파라미터를 전달할 수 있다.

예를 들어 _includes 폴더에 note.html이라는 파일이 있고 아래와 같은 코드를 가지고 있다고 가정해보자.

1
2
3
4
5
<!-- _includes/note.html -->
<div markdown="span" class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i> <b>Note:</b>
{{ include.content }}
</div>

{{include.content}}include를 호출하여 include에 있는 파라미터의 값을 지정한다.

1
{% include note.html content="This is my sample note." %}

만약 위와 같이 include 태그를 사용하면 This is my sample note.라는 파라미터의 값이 include.content에 전달된다.

include를 통한 파라미터 전달은 특히 Markdown 기반의 컨텐츠에서 복잡한 형식을 숨기려는 경우에 유용하다.

다시 예를 들어보자.

1
2
3
4
5
6
<figure>
<a href="http://jekyllrb.com">
<img src="logo.png" style="max-width: 200px;"
alt="Jekyll logo" />
<figcaption>This is the Jekyll logo</figcaption>
</figure>

위처럼 복잡한 형식을 가진 이미지를 포함하는 코드가 있고 이를 개발자가 잊어먹었다고 가정한다.

이를 해결하기위해 include에 파라미터를 전달하여 형식을 단순화하기로 하였을 때 아래와 같이 작성할 수 있다.

1
2
3
4
5
6
<figure>
<a href="{{ include.url }}">
<img src="{{ include.file }}" style="max-width: {{ include.max-width }};"
alt="{{ include.alt }}"/>
<figcaption>{{ include.caption }}</figcaption>
</figure>

위의 include에는 5개의 파라미터가 전달된다.

  • url
  • max-width
  • file
  • alt
  • caption

위의 파라미터를 전달하며 include 태그를 작성한다면 아래와 같이 작성할 수 있다.

1
2
3
{% include image.html url="http://jekyllrb.com"
max-width="200px" file="logo.png" alt="Jekyll logo"
caption="This is the Jekyll logo." %}

Liquid 기본 필터

파라미터를 받아야만 하는 코드가 있을 때 include에 파라미터가 전달되지 않는 상황을 방지하지 위해 Liquid의 기본 필터를 사용할 수 있다.

오디오, 비디오, 경고창이나 특수한 형식을 파라미터로 전달하는 include 태그를 사용할 순 있지만 너무 많은 파라미터는 사이트의 빌드 시간을 느리게 만든다.

위의서 이미지에 대한 값을 파라미터로 전달하는 예제를 사용하였지만 모든 이미지를 파라미터 전달을 이용한 include로 작성하게 되면 빌드에 많은 시간이 소요될 것이다.

참고 Liquid 기본 필터

include에 파라미터 변수 전달

여태까지 예로 들었듯 include에 전달할 매개변수가 문자열이 아니라 특정 변수라고 가정해보자.

예를 들어 _config.yml파일에 product_name라는 값을 가지는 키가 있다고 할 때 {{ site.product_name }}를 전달하게 되면 문자열이 아닌 product_name의 모든 인스턴스를 전달하게 될 것이다.

예외
include에 파라미터를 전달할 경우, 파라미터의 문자열에는 중괄호를 포함할 수 없다.

예를 들어 "The latest version of {{ site.product_name }} is now available."라는 변수는 전달할 수 없다.

capture

만약 include에 전달하는 파라미터가 변수를 포함하려면 전달하기 전에 전체 파라미터를 특정 변수로 저장해야 한다.

특정 변수로 저장하기 위해선 capture 태그를 사용하면 된다.

아래의 예시를 보자.

1
2
{% capture download_note %}The latest version of
{{ site.product_name }} is now available.{% endcapture %}

위와 같이 특정 변수로 지정하고 나면 include에 파라미터로 전달할 수 있게 된다.

1
{% include note.html content = download_note %}

더 이상 파라미터가 문자열이 아닌 변수이므로 "를 생략해야 한다.

파라미터로 YAML 파일의 참조 전달

이번엔 include의 파라미터로 _data 폴더에 저장된 YAML 데이터 파일을 전달해보자.

_data 폴더에 아래의 데이터를 가진 profiles.yml이라는 파일이 있다고 가정하자.

1
2
3
4
5
6
7
- name: John Doe
login_age: old
image: johndoe.jpg

- name: Jane Doe
login_age: new
image: janedoe.jpg

그리고 _includes 폴더엔 아래의 코드를 가진 spotlight.html이라는 파일이 있다고 가정한다.

1
2
3
4
5
{% for person in {{ include.participants }} %}
{% if person.login_age == "new" %}
{{ person.name }}
{% endif %}
{% endfor %}

이제 spotlight.html파일을 포함시키고 여기에 YAML 파일을 파라미터로 전달할 수 있다.

아래와 같이 태그를 사용하면 된다.

1
{% include spotlight.html participants=site.data.profiles %}

위의 예제를 실행시키면 site.data.profiles{{include.participants}} 대신 삽입되고 Liquid 논리 프로세스가 동작하여 결과적으로 Jane Doe가 삽입된다.