jekyll-collection-pages 0.1.0

data/demo/_articles/jekyll-for-documentation.md

@@ -0,0 +1,399 @@
+---
+title: "Using Jekyll for documentation"
+date: 2024-08-02
+author: Allison Thackston
+image: /assets/img/post-img-2.png
+tags: [jekyll, documentation, collections]
+---
+
+In the realm of technical documentation, content is king—but structure is the kingdom. A well-organized documentation site can make the difference between a frustrating user experience and an enlightening one. When users can easily find what they're looking for, whether through intuitive navigation or efficient search, they're more likely to engage with and benefit from your documentation.
+
+Jekyll, with its flexibility and power, has long been a favorite tool for creating documentation sites. But when it comes to organizing complex documentation structures, especially those with multiple sections, nested categories, and interrelated content, even Jekyll can use a boost. This is where the `jekyll-collection-pages` plugin shines, offering enhanced capabilities for structuring and organizing your content.
+
+## Structuring Your Documentation Site
+
+The foundation of a great documentation site is its structure. A well-planned structure makes navigation intuitive and helps users quickly find the information they need.
+
+### Planning Your Content Hierarchy
+
+Before diving into Jekyll configurations, take some time to plan your content hierarchy. Consider the following:
+
+1. What are the main sections of your documentation?
+2. Are there logical subsections within these main sections?
+3. How might users expect to navigate through your content?
+
+For example, a software documentation site might have a structure like this:
+
+```
+- Getting Started
+  - Installation
+  - Quick Start Guide
+- User Guide
+  - Basic Features
+  - Advanced Features
+- API Reference
+- Troubleshooting
+- FAQs
+```
+
+### Setting Up Collections
+
+With your content hierarchy in mind, it's time to set up Jekyll collections. Collections in Jekyll allow you to group related content, which is perfect for documentation sites.
+
+In your `_config.yml` file, define your collections:
+
+```yaml
+collections:
+  getting_started:
+    output: true
+    permalink: /docs/getting-started/:path/
+  user_guide:
+    output: true
+    permalink: /docs/user-guide/:path/
+  api_reference:
+    output: true
+    permalink: /docs/api/:path/
+  troubleshooting:
+    output: true
+    permalink: /docs/troubleshooting/:path/
+```
+
+### Utilizing Jekyll Collection Pages
+
+Now, let's configure the Jekyll Collection Pages plugin to work with our structure. Add this to your `_config.yml`:
+
+```yaml
+collection_pages:
+  - collection: getting_started
+    field: category
+    path: docs/getting-started/categories
+    layout: category_page.html
+  - collection: user_guide
+    field: category
+    path: docs/user-guide/categories
+    layout: category_page.html
+  - collection: api_reference
+    field: category
+    path: docs/api/categories
+    layout: category_page.html
+  - collection: troubleshooting
+    field: category
+    path: docs/troubleshooting/categories
+    layout: category_page.html
+```
+
+This configuration tells the plugin to create category pages for each of our documentation sections.
+
+### Example Structure
+
+Let's look at how to implement this structure. Create directories for each collection in your Jekyll project:
+
+```
+_getting_started/
+_user_guide/
+_api_reference/
+_troubleshooting/
+```
+
+Then, create Markdown files in these directories. For example, in `_getting_started/`:
+
+```markdown
+---
+title: Installation
+category: Setup
+---
+
+# Installation Guide
+
+Here's how to install the software...
+```
+
+The `jekyll-collection-pages` plugin will automatically create a category page at `/docs/getting-started/categories/setup/index.html` listing all documents in the "Setup" category.
+
+## Implementing Effective Search
+
+Even with the best structure, users often rely on search to find specific information quickly. Let's implement a search function using Lunr.js, a lightweight, full-text search library for client-side applications.
+
+### Setting Up Lunr.js
+
+First, add Lunr.js to your project. You can do this by adding the following to your default layout's `<head>` section:
+
+```html
+<script src="https://unpkg.com/lunr/lunr.js"></script>
+```
+
+Next, create a JSON file that Lunr.js will use as its search index. Add this to your `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-collection-pages
+  - jekyll-lunr-js-search
+```
+
+Create a `search.json` file in your root directory:
+
+```liquid
+{% raw %}
+---
+layout: null
+---
+[
+  {% for collection in site.collections %}
+    {% for doc in collection.docs %}
+      {
+        "title": {{ doc.title | jsonify }},
+        "content": {{ doc.content | strip_html | jsonify }},
+        "url": {{ doc.url | jsonify }}
+      }{% unless forloop.last %},{% endunless %}
+    {% endfor %}
+  {% endfor %}
+]
+{% endraw %}
+```
+
+### Implementing the Search Interface
+
+Create a search page (`search.html` in your root directory):
+
+```html
+{% raw %}
+---
+layout: default
+title: Search
+---
+
+<h1>Search</h1>
+
+<input type="text" id="search-input" placeholder="Search...">
+
+<ul id="search-results"></ul>
+
+<script>
+  window.store = {
+    {% for collection in site.collections %}
+      {% for doc in collection.docs %}
+        "{{ doc.url | slugify }}": {
+          "title": "{{ doc.title | xml_escape }}",
+          "content": {{ doc.content | strip_html | strip_newlines | jsonify }},
+          "url": "{{ doc.url | xml_escape }}"
+        }
+        {% unless forloop.last %},{% endunless %}
+      {% endfor %}
+    {% endfor %}
+  };
+</script>
+<script src="/path/to/lunr.min.js"></script>
+<script src="/path/to/search.js"></script>
+```
+
+Create `search.js` in your JavaScript directory:
+
+```javascript
+(function() {
+  function displaySearchResults(results, store) {
+    var searchResults = document.getElementById('search-results');
+
+    if (results.length) {
+      var appendString = '';
+
+      for (var i = 0; i < results.length; i++) {
+        var item = store[results[i].ref];
+        appendString += '<li><a href="' + item.url + '"><h3>' + item.title + '</h3></a>';
+        appendString += '<p>' + item.content.substring(0, 150) + '...</p></li>';
+      }
+
+      searchResults.innerHTML = appendString;
+    } else {
+      searchResults.innerHTML = '<li>No results found</li>';
+    }
+  }
+
+  function getQueryVariable(variable) {
+    var query = window.location.search.substring(1);
+    var vars = query.split('&');
+
+    for (var i = 0; i < vars.length; i++) {
+      var pair = vars[i].split('=');
+
+      if (pair[0] === variable) {
+        return decodeURIComponent(pair[1].replace(/\+/g, '%20'));
+      }
+    }
+  }
+
+  var searchTerm = getQueryVariable('query');
+
+  if (searchTerm) {
+    document.getElementById('search-box').setAttribute("value", searchTerm);
+
+    var idx = lunr(function () {
+      this.field('id');
+      this.field('title', { boost: 10 });
+      this.field('content');
+    });
+
+    for (var key in window.store) {
+      idx.add({
+        'id': key,
+        'title': window.store[key].title,
+        'content': window.store[key].content
+      });
+    }
+
+    var results = idx.search(searchTerm);
+    displaySearchResults(results, window.store);
+  }
+})();
+{% endraw %}
+```
+
+## Leveraging jekyll-collection-pages for an Organization
+
+The Jekyll Collection Pages plugin really shines when it comes to organizing your content. Let's explore some advanced uses.
+
+### Automatic Category and Tag Pages
+
+We've already set up basic category pages. Let's customize their layout. Create `_layouts/category_page.html`:
+
+```html
+{% raw %}
+---
+layout: default
+---
+<h1>{{ page.tag }}</h1>
+
+<ul>
+{% for post in page.posts %}
+  <li><a href="{{ post.url | relative_url }}">{{ post.title }}</a></li>
+{% endfor %}
+</ul>
+{% endraw %}
+```
+
+### Creating a Dynamic Sidebar
+
+Use collection data to generate a dynamic sidebar. Add this to your default layout:
+
+```html
+{% raw %}
+<nav class="sidebar">
+  {% for collection in site.collections %}
+    {% if collection.label != "posts" %}
+      <h3>{{ collection.label | capitalize | replace: "_", " " }}</h3>
+      <ul>
+        {% for doc in collection.docs %}
+          <li><a href="{{ doc.url | relative_url }}">{{ doc.title }}</a></li>
+        {% endfor %}
+      </ul>
+    {% endif %}
+  {% endfor %}
+{% endraw %}
+</nav>
+```
+
+### Implementing Breadcrumbs
+
+Add breadcrumbs to your document layout for easy navigation:
+
+```html
+{% raw %}
+<div class="breadcrumbs">
+  <a href="{{ '/' | relative_url }}">Home</a> &raquo;
+  {% assign crumbs = page.url | split: '/' %}
+  {% for crumb in crumbs offset: 1 %}
+    {% if forloop.last %}
+      {{ page.title }}
+    {% else %}
+      <a href="{{ site.baseurl }}{% assign crumb_limit = forloop.index | plus: 1 %}{% for crumb in crumbs limit: crumb_limit %}{{ crumb | append: '/' }}{% endfor %}">{{ crumb | replace: '-', ' ' | capitalize }}</a> &raquo;
+    {% endif %}
+  {% endfor %}
+  {% endraw %}
+</div>
+```
+
+### Cross-linking and Related Content
+
+Utilize tags for suggesting related documents. In your document layout:
+
+```html
+{% raw %}
+{% if page.tags %}
+  <h3>Related Documents</h3>
+  <ul>
+    {% assign maxRelated = 4 %}
+    {% assign minCommonTags =  1 %}
+    {% assign maxRelatedCounter = 0 %}
+
+    {% for doc in site.documents %}
+      {% assign sameTagCount = 0 %}
+      {% for tag in doc.tags %}
+        {% if page.tags contains tag %}
+          {% assign sameTagCount = sameTagCount | plus: 1 %}
+        {% endif %}
+      {% endfor %}
+      {% if sameTagCount >= minCommonTags %}
+        <li><a href="{{ doc.url | relative_url }}">{{ doc.title }}</a></li>
+        {% assign maxRelatedCounter = maxRelatedCounter | plus: 1 %}
+        {% if maxRelatedCounter >= maxRelated %}
+          {% break %}
+        {% endif %}
+      {% endif %}
+    {% endfor %}
+  </ul>
+{% endif %}
+{% endraw %}
+```
+
+## Best Practices and Tips
+
+1. **Consistent Front Matter**: Establish a template for front matter across your documents. This ensures consistency and makes it easier to implement site-wide features.
+
+2. **Versioning Documentation**: For software documentation, consider using Git branches for different versions. You can then build separate sites for each version.
+
+3. **Handling Images and Assets**: Store images in an `assets` folder within each collection. This keeps your content organized and makes it easy to move or refactor sections.
+
+## Case Study: Refactoring an Existing Documentation Site
+
+Let's say we have an existing documentation site with a flat structure, where all documents are in the `_posts` folder. Here's how we might refactor it:
+
+Before:
+```
+_posts/
+  2023-01-01-installation.md
+  2023-01-02-quick-start.md
+  2023-01-03-advanced-features.md
+  2023-01-04-api-reference.md
+  2023-01-05-troubleshooting.md
+```
+
+After:
+```
+_getting_started/
+  installation.md
+  quick-start.md
+_user_guide/
+  advanced-features.md
+_api_reference/
+  index.md
+_troubleshooting/
+  common-issues.md
+```
+
+This refactoring, combined with the Jekyll Collection Pages plugin configuration we discussed earlier, results in:
+
+- Clearer content organization
+- Automatically generated category pages
+- Easier navigation with breadcrumbs and dynamic sidebar
+- Improved search functionality
+
+## Conclusion
+
+By leveraging Jekyll's collection feature and the power of the Jekyll Collection Pages plugin, you can create a documentation site that's not only comprehensive but also user-friendly and easy to maintain. The key takeaways are:
+
+1. Plan your content structure carefully
+2. Use collections to organize your content logically
+3. Implement search to help users find information quickly
+4. Utilize the Jekyll Collection Pages plugin to automate category page creation and enhance organization
+5. Implement features like breadcrumbs and related content to improve navigation
+
+With these strategies in place, your Jekyll documentation site will be well-structured, easily navigable, and primed for growth. Happy documenting!

data/demo/_articles/linking-obsidian-and-jekyll.md

@@ -0,0 +1,89 @@
+---
+title: "Linking Obsidian and Jekyll"
+date: 2024-08-02
+author: Allison Thackston
+image: /assets/img/post-img-1.png
+tags: [jekyll, obsidian, collections, symlinks, drafts]
+---
+
+As a long-time Obsidian user, I've fallen in love with its flexibility, linking capabilities, and the sheer joy of connecting ideas across my personal knowledge base. The way Obsidian allows me to create, organize, and interlink my thoughts is nothing short of revolutionary for my workflow. But there's been one persistent itch I've wanted to scratch: how can I easily share select parts of my Obsidian vault with the world?
+
+Enter Jekyll, the static site generator that's been a staple for developers and bloggers alike. Jekyll's power in creating fast, efficient websites is undeniable. However, the traditional Jekyll setup, with its focus on the _posts directory and specific naming conventions, always felt at odds with my Obsidian workflow. The thought of manually renaming files, adjusting front matter, and maintaining two separate systems for my notes was, frankly, exhausting.
+
+What I needed was a bridge between these two worlds - a way to harness Obsidian's note-taking prowess and Jekyll's publishing capabilities without compromising either. I wanted to write in Obsidian as I always have, with my preferred file names and organization, and then seamlessly publish select notes to my Jekyll site without any file juggling or renaming gymnastics.
+
+That's where this setup comes in. By leveraging Jekyll collections, smart use of symlinks, and the power of the `jekyll-collection-pages` plugin, we can create a harmonious workflow that respects the Obsidian structure while unlocking Jekyll's publishing potential.
+
+
+## Creating the Symlink
+
+1. Open your terminal.
+2. Navigate to your Jekyll site's root directory.
+3. Create a symlink from your Obsidian vault to a Jekyll collection:
+
+   ```bash
+   ln -s /path/to/your/obsidian/vault /path/to/your/jekyll/_articles
+   ```
+
+   Replace `/path/to/your/obsidian/vault` with the actual path to your Obsidian vault, and `/path/to/your/jekyll/_articles` with the path where you want the collection in your Jekyll site.
+
+## Setting Up the Collection
+
+1. In your Jekyll `_config.yml`, add:
+
+   ```yaml
+   collections:
+     articles:
+       output: true
+   ```
+
+2. Create a default layout for articles in `_layouts/article.html`.
+
+## Enabling Tags
+
+1. In `_config.yml`, add:
+
+   ```yaml
+collection_pages:
+  - collection: articles
+    field: tags
+    path: tags
+    layout: tag_layout.html
+   ```
+
+2. Create `_layouts/tag_layout.html` for your tag pages.
+
+## Managing Drafts
+
+1. In `_config.yml`, add a default front matter for articles:
+
+   ```yaml
+   defaults:
+     - scope:
+         path: ""
+         type: "articles"
+       values:
+         layout: "article"
+         published: false
+   ```
+
+2. In Obsidian, add to your note's front matter to publish:
+
+   ```yaml
+   ---
+   published: true
+   ---
+   ```
+
+## Usage
+
+1. Write your notes in Obsidian as usual.
+2. Add tags in Obsidian using `#tag` syntax or in the front matter.
+3. When ready to publish, add `published: true` to the note's front matter.
+4. Build your Jekyll site – only published articles will appear.
+
+This setup allows you to seamlessly use Obsidian for note-taking while leveraging Jekyll's powerful publishing features. The Jekyll Collection Pages plugin handles tag organization, making your content easily navigable.
+
+Remember to gitignore the symlinked directory to avoid committing your entire Obsidian vault!
+
+Happy writing and publishing!

data/demo/_config.yml

@@ -0,0 +1,83 @@
+theme: jekyll-theme-profile
+style: topbar
+title: Jekyll Collection Pages plugin
+repository: PrimerPages/jekyll-collection-pages
+author: PrimerPages
+description: "A plugin for creating index pages for a collection."
+image: /assets/img/jekyll-collection-pages-preview.png
+
+#profile info
+repo_info: false
+user_metadata: false
+user_image: /assets/img/jekyll-collection-pages.png
+profile_link: false
+
+collections:
+  docs:
+    output: true
+    sort_by: order
+  articles:
+    output: true
+
+defaults:
+  - scope:
+      path: "" # an empty string here means all files in the project
+      type: "articles"
+    values:
+      layout: "post"
+      image: /assets/img/default.png # The default image used for social and posts.
+      permalink: /articles/:path:output_ext
+  - scope:
+      path: "" # an empty string here means all files in the project
+      type: "docs"
+    values:
+      layout: "docs"
+      image: /assets/img/default.png # The default image used for social and posts.
+      permalink: /docs/:path:output_ext
+      toc: true
+
+links:
+  - name: Docs
+    url: /docs
+    thumbnail: /assets/img/docs.png
+  - name: Articles
+    url: /articles
+    thumbnail: /assets/img/articles.png
+
+collection_pages:
+  - collection: docs
+    field: category
+    path: /docs
+    layout: collection_layout.html
+    paginate: 6
+  - collection: articles
+    field: tags
+    path: /tags
+    layout: tags.html
+    paginate: 3
+
+####################
+# jekyll-paginate settings
+paginate: 6 # The number of posts to show per page of pagination of blog posts
+paginate_path: "/blog/page:num"
+
+###################
+# Theme tag settings related
+tag_page_dir: tags
+related_by: "tags or categories"
+
+###################
+# jekyll-relative-links settings
+relative_links:
+  enabled:     true
+  collections: true
+
+plugins:
+  - jekyll-paginate
+  - jekyll-collection-pages
+  - jekyll-github-metadata
+  - jekyll-octicons
+  - jekyll-relative-links
+  - jekyll-seo-tag
+  - jekyll-toc
+  - jemoji

data/demo/_docs/configuration-guide.md

@@ -0,0 +1,113 @@
+---
+title: "Configuration guide"
+category: "Reference"
+description: "Reference for every collection_pages option, defaults, and validation tips."
+order: 3
+---
+
+This guide describes the configuration options available in `jekyll-collection-pages` and how they interact. Use it as the single reference while wiring the plugin into your site.
+
+## Overview
+
+Add a `collection_pages` entry to `_config.yml`. Each entry targets one collection and one front-matter field:
+
+```yaml
+collection_pages:
+  - collection: docs
+    field: category
+    path: docs/category
+    layout: category_layout.html
+    paginate: 6
+```
+
+You can declare multiple collections or multiple fields for the same collection by adding more entries to the array:
+
+```yaml
+collections:
+  docs:
+    output: true
+  articles:
+    output: true
+
+collection_pages:
+  - collection: docs
+    field: category
+    path: docs/category
+    layout: category_layout.html
+    paginate: 6
+  - collection: articles
+    field: tags
+    path: articles/tags
+    layout: tags_layout.html
+    paginate: 10
+```
+
+If you only need a single entry, `collection_pages` can also be a hash (the plugin normalises it internally). The array form keeps things consistent once you add more targets.
+
+Each `path` above is treated as a template—directory values automatically expand to `docs/<section>/categories/:field/page:num/index.html`. To switch to file-style permalinks, include the placeholders yourself, e.g. `docs/getting-started/categories/:field-page:num.html`.
+
+## Configuration options
+
+### `collection`
+
+- Type: `String`  
+- Required: ✔ 
+- Description: Collection label from your `collections` configuration.
+
+### `field`
+
+- Type: `String`  
+- Required: ✔  
+- Description: Front-matter key used to group documents. Supports scalar values (e.g. `"category"`) and array values (e.g. `"tags"`).
+
+Make sure every document you expect to index sets this field. When the field holds an array, the plugin creates one page per value.
+
+### `path`
+
+- Type: `String`  
+- Required: ✔  
+- Description: Path template relative to the site source. It must contain exactly one `:field` placeholder (replaced with the slugified field value) and one `:num` placeholder (replaced with the page number). When you omit placeholders in a directory-style path, the plugin automatically appends them as `<path>/:field/page:num/index.html`. When you provide a filename (ends in `.html`/`.htm`), you must include both placeholders yourself. Leading/trailing slashes are stripped either way.
+
+Rules enforced by the generator:
+
+- `:field` must appear before `:num`, and they cannot be in the same path segment.
+- Paths ending in `.html`/`.htm` must include both placeholders already.
+- Leaving `path` blank defaults to `<collection>/:field/page:num/index.html`.
+
+### `layout`
+
+- Type: `String`  
+- Required: ✖ (default: `collection_layout.html`)  
+- Description: Layout file in `_layouts/` to render the generated page.
+
+The plugin copies `page.posts`, `page.tag`, and optional `page.paginator` into the layout context.
+
+### `paginate`
+
+- Type: `Integer`  
+- Required: ✖  
+- Description: When present and positive, splits the documents into pages of the given size. Pagination behaves like Jekyll’s built-in paginator (`page.paginator` exposes `page`, `total_pages`, `previous_page_path`, `next_page_path`, etc.) and the generated paths already include the tag directory (e.g. `docs/category/getting-started/`, `docs/category/getting-started/page2.html`), so piping them through `relative_url` yields working links.
+
+Set `paginate` to `nil`, omit the key, or use a non-positive number to render a single page per label. Non-numeric values raise an error during the build, so typos like `"ten"` fail fast.
+
+## Generated data
+
+At build time the plugin exports `site.data.collection_pages[collection_name][field]`, which contains:
+
+- `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
+
+Use `pages` to feed existing includes, and `labels[label].index.url` when you need the generated index URL.
+
+See the [Generated data reference](generated-data.md) for usage patterns and Liquid snippets.
+
+## Validation tips
+
+- Ensure the target collection has `output: true`, otherwise links from index pages may 404.
+- Double-check that the `field` exists in every document; documents missing the field are skipped.
+- Use `bundle exec jekyll build --trace` with `JEKYLL_LOG_LEVEL=debug` to see the plugin’s log output (e.g. total pages generated).
+- Inspect `site.data.collection_pages` in a rendered page (`{% raw %}{{ site.data.collection_pages | jsonify }}{% endraw %}`) when debugging Liquid loops.
+
+Ready to dive deeper? Explore the [examples](examples.md) for real-world configurations and the [layout recipes](layout-recipes.md) to customise the rendered pages.