jekyll-collection-pages 0.1.0

data/demo/_docs/examples.md

@@ -0,0 +1,159 @@
+---
+title: "Example configurations"
+category: "Usage"
+description: "Copy-ready YAML and Liquid snippets for common collection setups."
+order: 5
+---
+
+Use this cookbook to copy working `collection_pages` configurations and accompanying Liquid snippets.
+
+## Blog categories
+
+```yaml
+collection_pages:
+  - collection: posts
+    field: category
+    path: blog/category
+    layout: category_page.html
+    paginate: 10
+  - collection: posts
+    field: category
+    path: blog/category/:field-page:num.html
+    layout: category_page.html
+    paginate: 10
+```
+
+The first entry produces folder-style pagination such as `/blog/category/reference/` and `/blog/category/reference/page2/`. The second entry demonstrates file-style pagination (e.g. `/blog/category/reference.html`, `/blog/category/reference-page2.html`). Both obey the same placeholder rules; pick the style that fits your permalink scheme.
+
+Render a category listing with the exported data registry:
+
+```liquid
+{%raw %}
+{% 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 %}
+{% endraw %}
+```
+
+## Documentation + tutorials
+
+```yaml
+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:
+
+```liquid
+{% raw %}
+{% 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 %}
+{% endraw %}
+```
+
+## Project tags
+
+```yaml
+collection_pages:
+  - collection: projects
+    field: tags
+    path: portfolio/tags
+    layout: project_tag.html
+```
+
+In your tag overview page:
+
+```liquid
+{% raw %}
+{% 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 %}
+{% endraw %}
+```
+
+## One collection, multiple views
+
+You can create pages based on multiple fields for the same collection:
+
+```yaml
+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
+
+```yaml
+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:
+
+```liquid
+{% raw %}
+{% 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 %}
+{% endraw %}
+```
+
+```liquid
+{% raw %}
+{% 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 %}
+{% endraw %}
+```
+
+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 `{{ page.posts }}` or `{{ page.paginator }}` as required.
+- When debugging, dump `site.data.collection_pages | jsonify` in a temporary page to inspect the computed groups, metadata, and generated paths.

data/demo/_docs/generated-data.md

@@ -0,0 +1,76 @@
+---
+title: "Generated data reference"
+category: "Reference"
+description: "Learn the structure of site.data.collection_pages and use it to build custom indexes."
+order: 4
+---
+
+The plugin exports data that mirrors Jekyll’s built-in `site.tags` and `site.categories` helpers, organized under a single hash. Use it to build dashboards, custom index pages, and sidebar navigation without re-walking `site.pages`.
+
+## collection_pages
+
+`site.data.collection_pages[collection][field]` returns a hash with:
+
+- `template` → the full sanitized template used for creating pages with placeholders intact.  Directory-style values from `_config.yml` are auto-appended with `:field/page:num/index.html`. (e.g. `/docs/category/:field/page:num/index.html`)
+- `permalink` → the sanitized template for the index with placeholders intact (e.g. `/docs/category/:field/`)
+- `pages` → documents grouped by label (`{ label => [documents...] }`)
+- `labels`: metadata describing the generated index pages
+
+### pages
+
+`pages` generates a list of documents grouped by label (`{ label => [documents...] }`)
+
+Example:
+
+```liquid
+{% raw %}
+{% assign info = site.data.collection_pages.articles.tags %}
+{% for entry in info.pages %}
+  {% assign label = entry | first %}
+  {% assign documents = entry | last %}
+  <h2>{{ label }} ({{ documents.size }})</h2>
+  <ul>
+    {% for doc in documents %}
+      <li><a href="{{ doc.url | relative_url }}">{{ doc.data.title }}</a></li>
+    {% endfor %}
+  </ul>
+{% endfor %}
+{% endraw %}
+```
+
+The structure is intentionally compatible with existing theme includes that expect `site.tags`.
+
+### labels
+
+`labels` exposes metadata about each generated index:
+
+- `index`: the first generated index page (`index.html`)
+- `pages`: array of all `TagIndexPage` objects
+
+Example:
+
+```liquid
+{% raw %}
+## Index of generated pages
+{%- assign index_by_label = site.data.collection_pages.docs.category.labels %}
+
+{% for entry in index_by_label %}
+  {% assign label = entry | first %}
+  {% assign info = entry | last %}
+  <h2> <a href="{{ info.index.url | relative_url }}">{{ label }}</a> ( {{ info.pages.size }})</h2>
+  <ul>
+  {% for entry in info.pages %}
+    <li><a href="{{ entry.url }}">Page {{ entry.page_num }}</a></li>
+  {% endfor %}
+  </ul>
+{% endfor %}
+{% endraw %}
+```
+
+## Debugging tips
+
+- Dump `site.data.collection_pages | jsonify` in a draft page to inspect the data structure during development (paths, permalinks, labels, and documents).  
+- Enable debug logging (`JEKYLL_LOG_LEVEL=debug bundle exec jekyll build`) to see the list of generated labels.  
+- When a label is missing, check the source documents for the configured field (case-sensitive).
+
+Ready to render the maps? Jump to the [layout recipes](layout-recipes.md) for practical includes and UI patterns.

data/demo/_docs/layout-recipes.md

@@ -0,0 +1,122 @@
+---
+title: Layout recipes
+category: "Usage"
+description: "Practical Liquid patterns for rendering collection indexes, pagination, and integrations."
+order: 6
+---
+
+Use these recipes to tailor the generated pages, hook into pagination, or integrate with other plugins.
+
+## Category/tag layout template
+
+```html
+{% raw %}
+---
+layout: default
+---
+<header class="collection-header">
+  <h1>{{ page.tag }}</h1>
+  <p>{{ page.posts | size }} items</p>
+</header>
+
+<section class="collection-grid">
+  {% for doc in page.posts %}
+    <article class="collection-card">
+      <h2><a href="{{ doc.url | relative_url }}">{{ doc.data.title }}</a></h2>
+      <p>{{ doc.data.excerpt }}</p>
+    </article>
+  {% endfor %}
+</section>
+
+{% if page.paginator %}
+  <nav class="collection-pagination">
+    {% if page.paginator.previous_page_path %}
+      <a href="{{ page.paginator.previous_page_path | relative_url }}">Previous</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 %}
+{% endraw %}
+```
+
+`previous_page_path` and `next_page_path` already include the generated tag directory, so `| relative_url` expands to the correct absolute link no matter how deeply nested the index lives.
+
+## “View all” links from an overview page
+
+```liquid
+{% raw %}
+{% assign info = site.data.collection_pages.docs.category %}
+
+{% for entry in info.pages %}
+  {% assign label = entry | first %}
+  {% assign documents = entry | last %}
+  {% assign meta = info.labels[label] %}
+  <div class="category-summary">
+    <h2>{{ label }}</h2>
+    <p>{{ documents.size }} docs</p>
+    <a href="{{ meta.index.url | relative_url }}">View all</a>
+  </div>
+{% endfor %}
+{% endraw %}
+```
+
+## Dynamic includes
+
+If you already have a `post-index.html` include that expects `site.tags`-style input, the plugin’s data map just works. Pass the metadata map when you want each section to know its generated URL:
+
+```liquid
+{% raw %}
+{% include post-index.html
+   collection=site.data.collection_pages.articles.tags.pages
+   collection_permalink=site.data.collection_pages.articles.tags.permalink
+   replace_value=":field"
+   meta=site.data.collection_pages.articles.tags.labels %}
+{% endraw %}
+```
+
+## SEO & sitemap integration
+
+`jekyll-seo-tag` reads `page.title`, so set it for nicer previews:
+
+```html
+{% raw %}
+---
+layout: default
+title: "{{ page.tag }} – {{ site.title }}"
+---
+{% seo title=false %}
+{% endraw %}
+```
+
+`jekyll-sitemap` includes generated pages automatically. To exclude a path:
+
+```yaml
+defaults:
+  - scope:
+      path: "docs/category"
+    values:
+      sitemap: false
+```
+
+## Multilingual layouts
+
+When you maintain per-language collections, add a language code to your layouts:
+
+```liquid
+{% raw %}
+{% assign fr_info = site.data.collection_pages.docs_fr.category %}
+{% assign fr_page = fr_info.labels[page.tag] %}
+{% if fr_page %}
+  <link rel="alternate" hreflang="fr" href="{{ fr_page.index.url | relative_url }}">
+{% endif %}
+{% endraw %}
+```
+
+## Performance hints
+
+- Use the exported data maps instead of iterating over `site.pages` to find generated pages.
+- When rendering large grids, pre-sort with Liquid filters.
+- Cache expensive loops in includes using capture if they are reused in multiple sections.

data/demo/_docs/quick-start.md

@@ -0,0 +1 @@
+../../README.md

data/demo/_docs/troubleshooting.md

@@ -0,0 +1,68 @@
+---
+title: Troubleshooting & FAQ
+category: "Reference"
+description: "Diagnose common issues and learn how to inspect the plugin’s output."
+order: 7
+---
+
+Having trouble seeing generated pages or data? Start here.
+
+## Pages not created
+
+- Ensure the target collection is defined with `output: true`.
+- Confirm the `collection_pages` entry uses the correct collection name and field spelling.
+- Run `JEKYLL_LOG_LEVEL=debug bundle exec jekyll build` to view the plugin’s log lines. They list each collection processed and how many pages were generated.
+
+## Missing tags or categories
+
+- Dump the data registry in a draft page:
+
+  ```liquid
+  {% raw %}
+  <pre>{{ site.data.collection_pages | jsonify }}</pre>
+  {% endraw %}
+  ```
+
+  If the label is missing, double-check the source document’s front matter.
+
+- Remember that string fields are case-sensitive (`"Docs"` and `"docs"` create different pages).
+
+## Pagination navigation broken
+
+- When using `paginate`, render pagination links with `page.paginator.previous_page_path` and `page.paginator.next_page_path`. The plugin now emits paths that already include the generated tag/category directory (e.g. `docs/category/reference/`), so piping them through `relative_url` produces working absolute URLs.
+- Verify the configured `paginate` value is a positive integer. Non-numeric values raise an error and zero/negative values fall back to single-page generation.
+- To link back to the first page, use the page directory:
+
+  ```liquid
+  {% raw %}
+  <a href="{{ page.dir | append: '/' | relative_url }}">Back to first page</a>
+  {% endraw %}
+  ```
+
+## Path template errors
+
+- `path` values must resolve to exactly one `:field` placeholder and one `:num` placeholder. Directory-style paths (no `.html`/`.htm`) automatically become `<path>/:field/page:num/index.html`, but explicit filenames must include both placeholders.
+- `:field` must appear before `:num`, and they cannot live in the same path segment.
+- When the build fails with an error referencing these placeholders, trim any trailing slashes and adjust the order. The generator logs the sanitized template in debug mode so you can confirm the final value.
+
+## Liquid include expects `site.tags`
+
+- Pass the plugin’s document map directly:
+
+  ```liquid
+  {% raw %}
+  {% include post-index.html collection=site.data.collection_pages.docs.category %}
+  {% endraw %}
+  ```
+
+- If the include also needs the generated page URL, read `site.data.collection_pages[collection][field].labels[label].index.url` (or build it from the configured `path` plus the slugified label).
+
+## Layout doesn’t see `page.posts`
+
+- Make sure the layout file starts with front matter (`---` lines). Without it, Jekyll treats it as a static file and skips Liquid rendering.
+- The variable is `page.posts` (not `page.documents`). When pagination is enabled, it shows only the current page’s slice; use `page.paginator.total_posts` for the total count.
+
+## Still stuck?
+
+- Open an issue with your `_config.yml` snippet and the relevant front matter.
+- Compare your site with the demo in this repository (`demo/` directory) to spot structural differences.

data/demo/_layouts/collection_layout.html

@@ -0,0 +1,27 @@
+---
+layout: docs
+---
+<ul>
+  {% for post in page.posts %}
+    <li><a href="{{ post.url | relative_url }}">{{ post.title }}</a></li>
+  {% endfor %}
+</ul>
+
+{% if page.paginator %}
+<!-- Pagination is active -->
+{% assign paginator = page.paginator %}
+{% endif %}
+<!-- Show navigation next/previous page links if applicable -->
+{% if paginator.total_pages > 1 %}
+<div class="paginate-container">
+    <div role="navigation" aria-label="Pagination" class="d-flex d-md-inline-block pagination">
+        {% if paginator.previous_page_path %}
+        <a class="previous_page" rel="prev" href="{{ paginator.previous_page_path | relative_url }}"
+            aria-disabled="false">Previous</a>
+        {% endif %}
+        {% if paginator.next_page_path %}
+        <a class="next_page" rel="next" href="{{ paginator.next_page_path | relative_url }}">Next</a>
+        {% endif %}
+    </div>
+</div>
+{% endif %}

data/demo/_layouts/tags.html

@@ -0,0 +1,31 @@
+---
+layout: page
+---
+<div class="d-flex flex-wrap gutter border-top">
+    {% for post in page.posts %}
+    {%- if post.feature or forloop.first %}
+    {%- include post-feature-card.html %}
+    {%- else %}
+    {%- include post-card.html border="border-top" %}
+    {%- endif %}
+    {% endfor %}
+</div>
+
+{% if page.paginator %}
+<!-- Pagination is active -->
+{% assign paginator = page.paginator %}
+{% endif %}
+<!-- Show navigation next/previous page links if applicable -->
+{% if paginator.total_pages > 1 %}
+<div class="paginate-container">
+    <div role="navigation" aria-label="Pagination" class="d-flex d-md-inline-block pagination">
+        {% if paginator.previous_page_path %}
+        <a class="previous_page" rel="prev" href="{{ paginator.previous_page_path | relative_url }}"
+            aria-disabled="false">Previous</a>
+        {% endif %}
+        {% if paginator.next_page_path %}
+        <a class="next_page" rel="next" href="{{ paginator.next_page_path | relative_url }}">Next</a>
+        {% endif %}
+    </div>
+</div>
+{% endif %}

data/demo/articles.md

@@ -0,0 +1,18 @@
+---
+title: Articles
+layout: page
+style: topbar
+permalink: /articles/
+---
+<h1>Articles</h1>
+
+<div class="d-flex flex-wrap gutter-spacious">
+<!-- This loops through the articles -->
+{%- for post in site.articles %}
+  {%- if post.feature or post == site.posts[0] %}
+  {%- include post-feature-card.html %}
+  {%- else %}
+  {%- include post-card.html border="border-top" %}
+  {%- endif %}
+{% endfor %}
+</div>>

data/demo/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

data/demo/directory.md

@@ -0,0 +1,36 @@
+---
+title: Directory
+layout: page
+permalink: /directory/
+---
+
+## Index of generated pages
+{%- assign index_by_tag = site.data.collection_pages.articles.tags.labels %}
+
+{% for entry in index_by_tag %}
+  {% assign label = entry | first %}
+  {% assign info = entry | last %}
+  <h2> <a href="{{ info.index.url | relative_url }}">{{ label }}</a> ({{ info.pages.size}} )</h2>
+  <p>
+  {% for entry in info.pages %}
+    <a href="{{ entry.url }}"> Page {{ entry.page_num }} </a>
+  {% endfor %}
+  </p>
+{% endfor %}
+
+## Pages by tag
+
+{%- assign articles_by_tag = site.data.collection_pages.articles.tags %}
+{%- assign index_permalink = site.data.collection_pages.articles.tags.permalink %}
+
+{% for entry in articles_by_tag.pages %}
+  {% assign label = entry | first %}
+  {% assign documents = entry | last %}
+  {% assign tag_url = index_permalink | replace: ':field', label %}
+  <h2> <a href="{{ tag_url | relative_url }}">{{ label }}</a> ({{ documents.size }})</h2>
+  <ul>
+  {% for entry in documents %}
+    <li><a href="{{ entry.url }}">{{ entry.title }}</a></li>
+  {% endfor %}
+  </ul>
+{% endfor %}

data/demo/docs.md

@@ -0,0 +1,24 @@
+---
+title: Docs
+layout: docs
+toc: false
+order: 1
+permalink: /docs/
+---
+{% assign docs_info = site.data.collection_pages.docs.category %}
+
+{% for category in docs_info.pages %}
+  {% assign label = category | first %}
+  {% assign documents = category | last | sort: "order" %}
+  {% assign info = docs_info.labels[label] %}
+  <h3><a href="{{ info.index.url | relative_url }}">{{ label | default: "Uncategorized" }}</a></h3>
+  <ul>
+  {% for entry in documents %}
+    <li><a href="{{ entry.url }}">{{ entry.title }}</a>
+        {% if entry.description %}
+          <p>{{ entry.description }}</p>
+        {% endif %}
+    </li>
+  {% endfor %}
+  </ul>
+{% endfor %}

data/demo/gallery.md

@@ -0,0 +1,14 @@
+---
+title: Gallery
+layout: page
+permalink: /gallery/
+---
+{%- assign tags_info = site.data.collection_pages.articles.tags %}
+{%- assign tag_permalink = site.data.collection_pages.articles.tags.permalink %}
+
+{% include post-gallery.html
+  collection=tags_info.pages
+  collection_permalink=tag_permalink
+  replace_value=":field"
+  per_section=3
+%}

data/demo/index.md

@@ -0,0 +1,63 @@
+---
+layout: page
+style: stacked
+title: jekyll-collection-pages demo
+---
+
+# Welcome to the jekyll-collection-pages Demo
+
+Discover how jekyll-collection-pages can transform your site's organization and navigation.
+
+## What is jekyll-collection-pages?
+
+`jekyll-collection-pages` is a powerful plugin that enhances Jekyll's built-in collections feature. It allows you to:
+
+- Automatically generate category and tag pages for your collections
+- Create custom layouts for different types of content
+- Implement pagination for your collection pages
+- Organize your content with unprecedented flexibility
+
+## Explore
+
+### Documentation
+
+See how `jekyll-collection-pages` organizes technical documentation:
+- [Browse Documentation](docs.md)
+
+### Articles
+
+See how `jekyll-collection-pages` can organize collections like posts:
+
+- [Tag directory](directory.md)
+- [Tag index](tags.md)
+- [Tag gallery](gallery.md)
+
+## Get Started
+
+Ready to use `jekyll-collection-pages` in your own project?
+
+1. [Quick Start Tutorial](_docs/quick-start.md)
+2. [Configuration Guide](_docs/configuration-guide.md)
+3. [Troubleshooting and Tips](_docs/troubleshooting.md)
+
+## News
+
+<div class="d-flex flex-wrap gutter-spacious">
+{%- assign latest_posts = site.articles | sort: "date" | reverse %}
+<!-- This loops through the articles -->
+{%- for post in latest_posts limit: 3 %}
+  {%- if post.feature or post == site.posts[0] %}
+  {%- include post-feature-card.html %}
+  {%- else %}
+  {%- include post-card.html border="border-top" %}
+  {%- endif %}
+{% endfor %}
+</div>>
+
+
+
+## Community and Support
+
+- [GitHub Repository](https://github.com/PrimerPages/jekyll-collection-pages)
+- [Report an Issue](https://github.com/PrimerPages/jekyll-collection-pages/issues)
+- [Contribution Guidelines](contributing.md)