Example configurations

Use this cookbook to copy working collection_pages configurations and accompanying Liquid snippets.

Blog categories

collection_pages:
  - collection: posts
    field: category
    path: blog/category
    layout: category_page.html
    paginate: 10

This configuration uses folder-style pagination such as /blog/category/reference/ and /blog/category/reference/page2/. Stick with this pattern for the most compatible URLs.

Render a category listing with the exported data registry:

{% assign categories = site.data.collection_pages.posts.category.pages %}
{% for entry in categories %}
  {% assign name = entry[0] %}
  {% assign docs = entry[1] %}
  <h2>{{ name }}</h2>
  <p>{{ docs.size }} posts</p>
{% endfor %}

Documentation + tutorials

collection_pages:
  - collection: docs
    field: section
    path: documentation/sections
    layout: doc_section.html
  - collection: tutorials
    field: difficulty
    path: tutorials/level
    layout: tutorial_level.html
    paginate: 6

This setup produces unpaginated doc sections and paginated tutorial difficulty indexes. Use the metadata map for quick links and pagination helpers:

{% assign tutorials_info = site.data.collection_pages.tutorials.difficulty %}
{% for entry in tutorials_info.pages %}
  {% assign label = entry | first %}
  {% assign meta = tutorials_info.labels[label] %}
  <a href="{{ meta.index.url | relative_url }}">View all tutorials for {{ label }}</a>
{% endfor %}

Project tags

collection_pages:
  - collection: projects
    field: tags
    path: portfolio/tags
    layout: project_tag.html

In your tag overview page:

{% assign projects_info = site.data.collection_pages.projects.tags %}
{% for entry in projects_info.pages %}
  {% assign label = entry | first %}
  {% assign items = entry | last %}
  {% assign meta = projects_info.labels[label] %}
  <a href="{{ meta.index.url | relative_url }}">{{ label }} ({{ items.size }})</a>
{% endfor %}

One collection, multiple views

You can create pages based on multiple fields for the same collection:

collection_pages:
  - collection: books
    field: genre
    path: books/genre
    layout: book_genre.html
  - collection: books
    field: author
    path: books/author
    layout: book_author.html

Use site.data.collection_pages.books.genre.pages and site.data.collection_pages.books.author.pages to populate dashboards, and site.data.collection_pages.books.genre.labels[label].index.url when you need the generated index URL.

Image gallery collections

collection_pages:
  - collection: gallery
    field: tags
    path: gallery/tags
    layout: gallery_tag.html
    paginate: 12

Overview pages can link to tag indexes via the metadata map, and each generated page exposes page.paginator for navigation:

{% assign gallery_info = site.data.collection_pages.gallery.tags %}
{% for entry in gallery_info.pages %}
  {% assign label = entry | first %}
  {% assign meta = gallery_info.labels[label] %}
  <a href="{{ meta.index.url | relative_url }}">View all in {{ label }}</a>
{% endfor %}

{% if page.paginator %}
  <nav class="pager">
    {% if page.paginator.previous_page_path %}
      <a href="{{ page.paginator.previous_page_path | relative_url }}">Prev</a>
    {% endif %}
    <span>Page {{ page.paginator.page }} of {{ page.paginator.total_pages }}</span>
    {% if page.paginator.next_page_path %}
      <a href="{{ page.paginator.next_page_path | relative_url }}">Next</a>
    {% endif %}
  </nav>
{% endif %}

Because those pagination paths already include the tag directory (gallery/tags/<label>/…), you can safely pipe them through relative_url without additional string concatenation.

Troubleshooting

Ensure every collection lists output: true if you expect to link to its documents.
Verify each document sets the field you configured (use site.collections[collection].docs | map: "path" to inspect).
Confirm the layout file exists and uses or as required.
When debugging, dump site.data.collection_pages | jsonify in a temporary page to inspect the computed groups, metadata, and generated paths.

Docs