Troubleshooting & FAQ

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.

Dump the data registry in a draft page:
```
  
<pre>{{ site.data.collection_pages | jsonify }}</pre>
  
```
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).

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:

  
<a href="{{ page.dir | append: '/' | relative_url }}">Back to first page</a>
  

path values must resolve to exactly one :field placeholder. Add a single :num placeholder only when the configuration sets a positive paginate value. Directory-style paths (no .html/.htm) automatically become <path>/:field/index.html, but Explicit filenames must include the required placeholders.
Whenever :num is present it must appear after :field, 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.

Pass the plugin’s document map directly:

  
{% include post-index.html collection=site.data.collection_pages.docs.category %}
  

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).

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.

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.