An Eleventy plugin for generating a JSON Feed using the Nunjucks templating engine.
An Eleventy plugin for generating
a JSON Feed using the Nunjucks templating engine.
Available on npm.
``bash`
npm install --save eleventy-plugin-json-feed
Open up your Eleventy config file, require the plugin, and then useaddPlugin to activate and configure it:
`js`
const pluginJsonFeed = require("eleventy-plugin-json-feed");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(pluginJsonFeed, options);
};
Copy the provided sample feed template into your working directory and
then customize it for your site:
`bash`
cp node_modules/eleventy-plugin-json-feed/sample/json.feed.njk
$EDITOR ./json.feed.njk
Note that you will need to have "njk" listed in thetemplateFormats list in your .eleventy.js.
This plugin makes a jsonFeed shortcode available to the Nunjucks
templater. It expects to be called like this:
`twig`
{% jsonFeed collections.posts, metadata, 10 %}
The third argument is the number of most recent posts to be included
in the feed. If not provided, it defaults to 10. If 0 is provided,
all posts will be included in the generated feed.
The sample template at sample/json.feed.njk should provide a good
starting point for almost every use case.
You can modify the behavior of this plugin by passing an options
object as the second argument to addPlugin. The default options set
by the plugin are:
`js`
const defaultOptions = {
banner_image_metadata_field_name: "banner_image",
content_html: true,
content_text: false,
filter_posts_tag: true,
image_metadata_field_name: "image",
summary_metadata_field_name: "summary",
tags_metadata_field_name: "tags",
};
* banner_image_metadata_field_name: will be used as the name of theitem.banner_image
YAML front matter attribute where the URL of an banner image is
stored. If found, the value of this attribute will be used to set
the value for the corresponding post item in thecontent_html
generated feed. Note that this field, if present, must contain a
string value, or an error will be thrown.
* : boolean indicating if post HTML should be includedcontent_text
in the feed.
* : boolean indicating if a text version of post contentfilter_posts_tag
should be included in the feed.
* : boolean indicating if a tag of posts should betags
filtered out of the metadata if it is present.image_metadata_field_name
* : will be used as the name of the YAMLitem.image
front matter attribute where the URL of an image associated with the
post is stored. If found, the value of this attribute will be used
to set the value for the corresponding post item in thesummary_metadata_field_name
generated feed. Note that this field, if present, must contain a
string value, or an error will be thrown.
* : will be used as the name of the YAMLitem.summary
front matter attribute where the short summary of a post is stored.
If found, the value of this attribute will be used to set the
value for the corresponding post item in thetags_metadata_field_name
generated feed. Note that this field, if present, must contain a
string value, or an error will be thrown.
* : will be used as the name of the YAMLitem.summary** value for the corresponding post item in the
front matter attribute where an array of tags categorizing a post is
stored. If found, the value of this attribute will be used to set
the
generated feed. Note that this field must contain an array of
strings or an error will be thrown.
IMPORTANT NOTE: At least one of content_html and content_text
_MUST_ be true, or an error will be thrown. It is allowed to set them
both to true.
Say you've got a blog and want to generate a JSON feed containing the
HTML representation of your posts. You sometimes use asocial_media_image key in your front matter when you want to feature
an image on social media, and each post has an attribute calledcategories that's an array of category names. You have an attribute
called description that's a short synopsis of your post content.
If that's the case, you'd want to load this plugin like this:
``js`
const pluginJsonFeed = require("eleventy-plugin-json-feed");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(pluginJsonFeed, {
content_html: true,
image_metadata_field_name: "social_media_image",
summary_metadata_field_name: "description",
tags_metadata_field_name: "categories"
});
};
If you'd like to display a JSON Feed icon on your site, I recommend the
one
in openwebicons
The test suite can be run with npm test. An ASCII coverage reportnpm run cover
can be generated with ; an HTML version can benpm run html-cover
generated with .
Feeds generated with this module should correctly validate with
jsonfeed-validator`.
Patches and pull requests welcome.
MIT © John SJ Anderson