Jekyll::StaticComments is a Ruby plugin for Jekyll that replaces JavaScript-based comment systems with a static, file-based comment store that is rendered into each post at build time.
What is Jekyll::StaticComments?
Jekyll::StaticComments is a plugin for the Jekyll static site generator that associates a _comments directory of YAML files with blog posts and exposes them to templates as page.comments. It takes YAML comment files, each containing a post_id field, and produces a list of Comment objects that pages can render. The plugin is open-source and licensed under the GNU General Public License version 3.
Key Features
- File-based comment storage — Comments are plain YAML files in a
_commentsdirectory, so there is no database and no JavaScript. - Flexible comment placement — The
_commentsdirectory can live anywhere in the site tree, including post-specific subdirectories. - YAML to object mapping — Each YAML field becomes a property on the Comment object, accessible in Liquid templates.
- Lexical filename ordering — Comments are ordered by filename, so naming files with timestamps preserves submission order.
- Email-based submission workflow — The included
commentsubmit.phpencodes form fields into YAML and emails them to the site owner for manual approval and placement. - Arbitrary metadata — YAML files may contain any fields beyond the required
post_id, letting sites store nicknames, links, or custom data. - No moderation plugin needed — Because comments are manually added to the filesystem, moderation is inherent to the workflow.
Who should use Jekyll::StaticComments?
This plugin is for Jekyll site owners who want comments without outsourcing them to Disqus or similar services. It suits developers who already manage their site as a git repository and are comfortable editing YAML files. It also works for bloggers who prefer an email-based moderation queue and do not need real-time discussion.
What can you do with Jekyll::StaticComments?
- Static site bloggers: Add a comments section to Jekyll posts that renders server-side at build time, so pages remain fast and free of third-party scripts.
- Privacy-conscious publishers: Avoid sending readers to third-party comment platforms; all comment data resides in the site's own repository.
- Developers who want offline-friendly sites: Use the plugin in Jekyll builds that generate fully static output with no runtime dependencies.
How does Jekyll::StaticComments work?
Install the static_comments.rb file into the _plugins directory, then add a comment form to your post template that points to commentsubmit.php. Place the PHP script and a thank-you page on your server; when a visitor submits a comment, the script emails the YAML-encoded fields to you. You then save that YAML into the _comments directory and regenerate the site, and the plugin exposes the comments to Liquid as page.comments at build time.
Pros and cons
- Pros: Static output with no client-side JavaScript; spam is deterred because comments are not auto-published; full control over comment data; natural moderation because you manually add YAML files.
- Cons: No real-time discussion; comment publication requires manual steps; Liquid templates that include standalone
commentidentifiers can be misinterpreted by Jekyll's parser and silently dropped.
Alternatives
- Disqus: the dominant JavaScript-based third-party comment service for blogs.
- even-more-static-comments: Tomas Carnecky's companion approach that accepts comments via a special per-post e-mail address using a
mailto:URL, taking static comments one step further by removing the PHP form.
FAQ
What is the _comments directory?
It is a directory of YAML files that the plugin reads. Every file inside it is parsed as one comment; the directory can be placed anywhere in the Jekyll site and can have nested subdirectories.
How are comments ordered?
The order of page.comments follows the lexical order of the comment filenames, so naming files by date and time preserves submission sequence.
Can I use any YAML fields for a comment?
Yes, only post_id is required. All other fields are mapped onto the Comment object and can be accessed in your Liquid templates.
Does Jekyll::StaticComments support real-time commenting?
No, it is a static workflow with email-based moderation. Comments appear only after the owner saves the YAML file into the _comments directory and rebuilds the site.
Is Jekyll::StaticComments free?
Yes, the plugin is licensed under the GNU General Public License version 3, so it is free to use and modify under the terms of that license.
