023. JeKyll 커스터마이징 - (6) 페이지 매기기(Pagination)

커스터마이징 - (6) 페이지 매기기(Pagination)

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

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

참고 Jekyll 공식 사이트

페이지 매기기(Pagination)

블로그를 포함한 많은 웹사이트에서는 전체 포스트 리스트를 다시 또 작은 리스트로 나누고 여러 페이지에 나누어 표시한다.

Jekyll은 이를 위한 페이지 처리 플러그인을 제공하므로 포스트를 여러 리스트로 나눌 때 필요한 파일과 폴더를 자동으로 생성할 수 있다.

Jekyll 2
Jekyll 2 버전의 경우 jekyll-paginate 플러그인이 표준으로 설정되어 있다.

Jekyll 3
Jekyll 3 버전의 경우 gemfile에 jekyll-paginate 플러그인을 추가한 뒤 gems에 _config.yml을 추가해야 한다.

참고 Pagination은 HTML에서만 동작한다.
Jekyll 사이트의 Markdown이나 Textile에서는 pagination 동작하지 않는다.
pagination은 paginate_path의 구성 값을 통해 지정된 하위 디렉토리 내의 index.html 파일에서 호출되어 동작한다.

페이지 매기기 활성화

블로그에서 pagination을 사용하려면 페이지당 몇 개의 항목을 표시할 건지 설정해야 한다.

아래와 같은 옵션을 _config.yml 환경설정 파일에 추가하면 된다.

paginate : 5

위에서 입력하는 숫자는 생성된 사이트에서 표시할 페이지당 포스트의 최대 개수이다.

위에서 분할한 페이지의 생성 위치는 paginate_path로 지정한다.

paginate_path: "/blog/page:num/"

위의 설정을 적용하면 blog/index.html 페이지에서 읽어들이게 되고, 나뉘어진 각각의 페이지를 Liquid 변수인 paginator로 받게 된다. 읽어들인 페이지를 통해 생성한 결과는 paginate_path에 지정한대로 /blog/page:num/에 작성된다.

예제에서 :num은 2부터 시작하는 페이지 번호로 동적으로 호출될 것이다.

만약 12 개의 포스트가 있고 paginate를 5 로 지정했다면 Jekyll에서 생성한 결과는 다음과 같다.

blog/index.html 에는 처음부터 5개의 게시물을 렌더링한다.
blog/page2/index.html 에는 다음 5개의 포스트 즉, 6번째부터 10번째 게시물을 렌더링한다.
blog/page3/index.html 에는 마지막 2개의 포스트를 렌더링한다.

이는 _site에 생성된 결과물에서 더 정확히 확인할 수 있다.

주의 고유 주소 설정에 관하여
블로그 페이지의 YAML 머리말에 고유 주소를 설정하면 pagination는 동작하지 않는다.

사용 가능한 Liquid 속성

paginator 플러그인에서 사용할 수 있는 Liquid 속성은 아래와 같다.

속성	설명
page	현재 페이지 번호
per_page	페이지 당 포스트 수
posts	현재 페이지의 포스트 목록
total_posts	전체 포스트 수
total_pages	전체 페이지 수
previous_page	이전 페이지 번호, 첫 페이지일 땐 nil
previous_page_path	이전 페이지 경로, 경로가 존재하지 않으면 nil
next_page	다음 페이지 번호, 맨 끝 페이지일 땐 nil
next_page_path	다음 페이지 경로, 경로가 존재하지 않으면 nil

참고 Pagination의 태그와 카테고리 미지원
Pagination은 포스트의 YAML 머리말에 hidden: true 설정이 있지 않은 이상 모든 포스트를 페이지로 매길 수 있다.
하지만 Pagination은 태그와 카테고리를 지원하지 않고 포스트에 한정되기 때문에 문서들의 컬렉션에는 적용할 수 없다.

페이지가 매겨진 게시물 렌더링

다음으로 paginator 변수를 이용하여 실제로 포스트 목록을 표시하는 방법을 소개한다.

paginator는 사이트의 메인 페이지에서 사용하는 것이 좋다.

아래의 예제를 보자.

---
layout: default
title: My Blog
---

<!-- paginator 변수에서 포스트 목록을 불러와 렌더링한다 -->
{% for post in paginator.posts %}
  <h1><a href="{{ post.url }}">{{ post.title }}</a></h1>
  <p class="author">
    <span class="date">{{ post.date }}</span>
  </p>
  <div class="content">
    {{ post.content }}
  </div>
{% endfor %}

<!-- Pagination links -->
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}" class="previous">Previous</a>
  {% else %}
    <span class="previous">Previous</span>
  {% endif %}
  <span class="page_number ">Page: {{ paginator.page }} of {{ paginator.total_pages }}</span>
  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}" class="next">Next</a>
  {% else %}
    <span class="next ">Next</span>
  {% endif %}
</div>

주의 첫 페이지의 주의사항
Jekyll은 :num 변수를 통해 page1 폴더를 생성하진 않는다. page2, page3… 순으로 생성함을 유의하자.

첫 페이지와 함께 나머지 페이지에 대한 링크를 렌더링하는 예제는 아래와 같다.

{% if paginator.total_pages > 1 %}
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">&laquo; Prev</a>
  {% else %}
    <span>&laquo; Prev</span>
  {% endif %}

  {% for page in (1..paginator.total_pages) %}
    {% if page == paginator.page %}
      <em>{{ page }}</em>
    {% elsif page == 1 %}
      <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">{{ page }}</a>
    {% else %}
      <a href="{{ site.paginate_path | prepend: site.baseurl | replace: '//', '/' | replace: ':num', page }}">{{ page }}</a>
    {% endif %}
  {% endfor %}

  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path | prepend: site.baseurl | replace: '//', '/' }}">Next &raquo;</a>
  {% else %}
    <span>Next &raquo;</span>
  {% endif %}
</div>
{% endif %}