jekyll-documents

Turn files in assets/documents/ into browsable document pages.

Requirements: Ruby 3.3+ • Jekyll 4.4+

Features: Auto-collection • File icons • Categories • Search

Quick Start

# Gemfile
gem "jekyll-documents"

# _config.yml
plugins:
  - jekyll-documents

documents:
  icon_set: "color"  # color, lines, minimal, ultra-minimal

# Add files
assets/documents/reports/2026-03-01_Annual_Report.pdf
assets/documents/minutes/2026-02-15_Board_Meeting.docx

<!-- Use in templates -->
{% include latest_documents.html %}
{% include documents_list.html %}
{% include category_list.html %}

File Naming

Format: YYYY-MM-DD_Title.ext

assets/documents/reports/2026-03-01_Annual_Report.pdf

Date → YYYY-MM-DD • Title → underscores to spaces • Category → folder name

Icons

4 icon sets: color (default), lines, minimal, ultra-minimal

documents:
  icon_set: "color"

Render a document icon in templates with the context-aware tag:

{% document_icon page %}

The tag applies the configured icon set and site baseurl automatically. The file_type_icon and file_type_icon_tag filters remain available for lower-level or Ruby-side use.

Usage

{% include latest_documents.html count=5 %}
{% include documents_list.html %}
{% include documents_search.html %}

Configuration

documents:
  root: "assets/documents"
  icon_set: "color"
  strict_filename: true

See configuration.rb for all options.

Development

rake              # Ruby quality checks
rake test         # Rebuild/install gem + Ruby and browser tests
rake browser_test # Browser search tests (Node.js + Chromium required)
rake quick        # Fast Ruby check
rake help         # Show commands

Quality: 100% coverage • 0 vulnerabilities • 0 offenses • 0 warnings

See README.Development.md for details.

DeepWiki: https://deepwiki.com/gundestrup/jekyll-documents

Release

./bump_version.sh patch
./release.sh

License

AGPL-3.0-only • Icons by SVG Repo