feed-generator
v1.0.6
Published
Generate RSS feeds with support for a variety of extensions
Downloads
218
Readme
feed-generator
Easy RSS feed generation in Node.js, supports most used RSS extensions like itunes
for podcast generation.
Installation
Install from npm:
npm install feed-generator --save
TL;DR
Example script for generating a minimal RSS feed:
var feedster = require('feed-generator');
// create feed with required elements
var feed = feedster.createFeed({
title: 'My Awesome Blog'
description: 'The best blog you have ever seen'
link: 'http://path/to/blog'
});
// add new item to the feed
feed.addItem({
// an item needs to contain either title or description, all other fields are optional
title: 'My first blog post',
// pubDate is not required but really useful
pubDate: '2011-01-01 11:12:34 +0000'
});
// generate a RSS string and print to console
var rss = feed.render();
console.log(rss);
Usage
Require feedster module
var feedster = require('feed-generator');
Create new feed object
var feed = feedster.createFeed(headers)
Where
- headers is an object with channel headers (see possible options below)
- feed is the feed object
Example
var feedster = require('feed-generator');
var feed = feedster.createFeed({
title: 'My Awesome Blog'
});
Add items to feed
Add additional item to the feed with
feed.addItem(item)
Where
- item is a feed item (see possible options below)
Example
var feedster = require('feed-generator');
var feed = feedster.createFeed();
feed.addItem({
title: 'My first blog post',
pubDate: '2011-01-01 14:34:00'
})
Generate RSS feed
Generate feed object into a rss feed string with
var rss = feed.render([options])
Where
- options is an optional options object
- options.indent defines the look of the generated file. If false, then the XML is not indented. Use 2 spaces
" "
for 2-spaces indentation etc.
- options.indent defines the look of the generated file. If false, then the XML is not indented. Use 2 spaces
Example
var feedster = require('feed-generator');
var feed = feedster.createFeed({
title: 'My Awesome Blog'
});
feed.addItem({
title: 'My first blog post',
// thats badly formatted date (no timezone etc.) but it works
pubDate: '2011-01-01 14:34:00'
})
var rss = feed.render({indent: ' '});
console.log(rss);
Output:
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
<channel>
<title>My Awesome Blog</title>
<lastBuildDate>Sat, 1 Jan 2011 14:34:00 +0200</lastBuildDate>
<item>
<title>My first blog post</title>
<pubDate>Sat, 1 Jan 2011 14:34:00 +0200</pubDate>
</item>
</channel>
</rss>
Channel options
category
Defines a category or a tag to which the feed belongs. The value is either a string, or an object or an array of mixed strings and objects for multiple categories. Category object has two properties:
- value - category title
- domain - identifies the category's taxonomy
Domain is rarely used, so just using strings with category names is sufficient for most cases
var headers = {
category: [
// first category as a plain string
'Category1',
// second category as an object
{
value: 'Category2/Subcategory/SubSub',
domain: 'dmoz'
}
]
};
cloud
Indicates that updates to the feed can be monitored using a web service. Defined by an object with the following properties:
- domain - identifies the host name or IP address of the web service that monitors updates to the feed
- path - provides the web service's path
- port - identifies the web service's TCP port
- protocol - "xml-rpc" if the service employs XML-RPC or "soap" if it employs SOAP
- registerProcedure - names the remote procedure to call when requesting notification of updates
var headers = {
cloud: {
domain: "server.example.com",
path: "/rpc",
port: "80",
protocol: "xml-rpc",
registerProcedure: "cloud.notify"
}
};
copyright
A string about the copyright holder.
var headers = {
copyright: '© 2015 My Name'
};
description
Required value
Summary of the feed.
var headers = {
description: 'Latest posts from my awesome blog'
};
docs
URL to RSS format specification.
var headers = {
docs: 'http://www.rssboard.org/rss-specification'
};
generator
Software that created the feed.
var headers = {
generator: 'My Awesome Feed Generator v1.0'
};
image
Graphical logo for the feed. Either an url to the image or an object with the following properties:
- url - image location
- link - url to the website. If not set the value from
headers.link
is used - title - title of the image. If not set the value from
headers.title
is used - description - image description
- width - image width in pixels
- height - image height in pixels
var headers = {
image: 'http://image/location'
};
var headers = {
image: {
url: 'http://image/location',
link: 'http://link/to/blog',
title: 'My Blog Logo'
}
};
language
Language code.
var headers = {
language: 'en-us'
};
lastBuildDate
Last modification date. If not set defaults to the time of the newest post in the feed. Recommended option is to not set it manually.
var headers = {
lastBuildDate: '2011-01-01 13:34:11'
};
link
Required value
URL of the website.
var headers = {
link: 'http://path/to/my/blog'
};
managingEditor
E-mail address and name of the person to contact regarding the editorial content of the feed. Has the following properties:
- name is the name of the editor
- email is the e-mail address of the editor
var headers = {
managingEditor: {
name: 'Editor Name',
email: '[email protected]'
}
};
pubDate
Publication date and time of the feed's content. Recommended option is to skip it and rely only on auto-generated lastBuildDate
.
The value can either be a Date object or a datetime string (any valid format is ok, the value is converted to RSS date format automatically).
var headers = {
pubDate: new Date()
};
rating
Advisory label for the content in a feed.
var headers = {
rating: '(PICS-1.1 "http://www.rsac.org/ratingsv01.html" l by "[email protected]" on "2007.01.29T10:09-0800" r (n 0 s 0 v 0 l 0))'
};
textInput
Defines a form to submit a text query to the feed's publisher. Nobody uses it, seems pretty strange but it is supported by feedster nevertheless. An object with the following properties:
- description
- link
- name
- title
var headers = {
textInput: {
description: 'Your aggregator supports the textInput element. What software are you using?',
link: 'http://www.cadenhead.org/textinput.php',
name: 'query',
title: 'TextInput Inquiry'
}
};
title
Required value
The name of the feed.
var headers = {
title: 'My Awesome Blog'
};
webMaster
E-mail address and name of the person to contact regarding technical issues about the feed. Has the following properties:
- name is the name of the web master
- email is the e-mail address of the web master
var headers = {
webMaster: {
name: 'Webmaster Name',
email: '[email protected]'
}
};
Channel Extensions
atomLink
atomLink
maps to atom:link
from the Atom specification that defines a relationship between a web resource (such as a page) and an RSS channel. For multiple link elements, use an array for the values.
An object with the following properties:
- hreflang - language code of the related resource
- length - resource's size in bytes
- title - description of the resource
- type - mime-type of the resource
- rel - keyword that identifies the nature of the relationship between the linked resouce and the element
- "alternate" - alternate representation of the same resource
- "enclosure" - media object, usually an audio or video file
- "related" - related resource
- "self - the feed itself
- "via" - the original source of the entry
var headers = {
atomLink: {
href: 'http://path/to/feed',
rel: 'self' // type is automatically for "self"
}
};
hub
hub
maps to atom:link
with rel="hub"
. Takes a string value which is an URL pointing to the PubSubHubbub hub.
var headers = {
hub: 'http://path/to/hub'
};
itunes
itunes
is an object that maps to the itunes specification and is used for podcasting. Channel level itunes element supports the following properties:
- author - string, artist column in iTunes
- block - boolean, if true then the entire podcast is removed from the iTunes Store podcast directory
- category - category element, see below for formatting
- image - string, url to the logo of the podcast
- explicit - boolean, if true then parental advisory graphic is shown under podcast details
- complete - boolean, if true then indicates that no more episodes will be posted in the future
- new-feed-url - string, reports new feed url for this podcast to iTunes
- owner - feed owner object with properties
name
andemail
- subtitle - string, description column
- summary - string, displayed when the circled i icon in the Description column in iTunes is clicked
Category format
- Plain string for a single top level category:
"Business"
- Array of categories for multiple:
["Business", "Technology"]
- Sub-categories:
{name: "Business", sub: ["Careers"]}
You can't use random values as categories, see available categories from the iTunes Categories for Podcasting section in itunes module documentation.
var headers = {
itunes: {
author: 'Your\'s truly',
block: true, // hide this podcast from the directory
explicit: true, // show parental advisory graphic
owner: {
name: 'My Name',
email: '[email protected]'
},
category: {
value: 'Business', // main category
sub: ['Careers', 'Football'] // sub categories
}
}
};
updatePeriod
updatePeriod
maps to sy:updatePeriod
from the Syndication module. Describes a period over which the channel format is updated. Acceptable values are: hourly, daily, weekly, monthly, yearly. Defaults to daily.
var headers = {
updatePeriod: 'hourly'
};
updateFrequency
updateFrequency
maps to sy:updateFrequency
from the Syndication module. A positive integer that describes how many times the channel is updated in selected update period.
var headers = {
// updated once in a hour
updatePeriod: 'hourly',
updateFrequency: 1
};
Item options
author
The person who wrote the item. Has the following properties:
- name is the name of the author
- email is the e-mail address of the author
feed.additem({
author: {
name: 'Author Name',
email: '[email protected]'
}
});
Recommended action is to use
creator
instead ofauthor
ascreator
does not require an e-mail address value
category
Defines a category or tag for the item. A string or an object. For multiple categories, use an array for the values. Category object has the following properties:
- value is the category name
- domain identifies the category's taxonomy
Domain is rarely used, so just using strings with category names is sufficient for most cases
feed.additem({
category: [
// first category as a plain string
'Category1',
// second category as an object
{
value: 'Category2/Subcategory/SubSub',
domain: 'dmoz'
}
]
});
comments
Points to an URL where comments for the item can be found.
feed.additem({
comments: 'http://path/to/comments'
});
description
Item's full content or a summary of its contents. Either title
or description
has to be set for the item, using both is optional. Usually description
is used for a summary and the content
extension element (see below) is used for the full contents.
feed.additem({
description: 'Just another rant about my awesomness'
});
enclosure
Associates a media object, usually an audio or video file. The value can be an URL pointing to the media object or an object value with the following properties:
- url - points to the URL of the file
- length - the size of the file in bytes. Required, but can be set to "0" if the size not known
- type - defines the mime-type of the resource
If length
is not defined, a default value of "0"
is used. If type
is missing, it is detected from the file extension of the url.
feed.additem({
enclosure: 'http://path/to/assets/podcast.mp3'
});
feed.additem({
enclosure: {
url: 'http://path/to/assets/podcast.mp3',
type: 'audio/mpeg',
length: 12345
}
});
guid
A string value that uniquely identifies the item. Recommended action would be to use the permalink to the item as guid, this is also the default if isPermaLink
option is not used.
If the value is permalink, then you can use the URL as the value, otherwise use an object with the following properties:
- value - guid value
- isPermaLink - boolean, if set to true or is missing then the value must be permalink to the item
feed.additem({
guid: 'http://path/to/posts/1'
});
feed.additem({
guid: {
value: 'some-unique-identifier',
isPermaLink: false
}
});
link
The URL pointing to a web page associated with the item.
feed.additem({
link: 'http://path/to/posts/1'
});
pubDate
Publication date and time of the item. The value can either be a Date object or a datetime string (any valid format is ok, the value is converted to RSS date format automatically).
feed.additem({
pubDate: new Date()
});
source
Indicates the original source RSS of the entry. An object with the following properties:
- title - the title of the original RSS feed
- url - the URL to the original RSS feed
feed.additem({
source: {
title: 'Some Other Publication',
url: 'http://path/to/publication.rss'
}
});
title
Item's headline. Either title
or description
has to be set for the item, using both is optional.
feed.additem({
title:
});
Item Extensions
commentCount
commentCount
maps to slash:comments
from the Slashdot module and contains a positive integer as the count of comments for the item.
feed.additem({
commentCount: 123
});
commentRss
commentRss
maps to wfw:commentRss
from the Well Formed Web Comments module and includes an URL to the comments RSS feed for the item.
feed.additem({
commentRss: 'http://path/to/post/1/comments/feed'
});
content
content
maps to content:encoded
from the content module and contains the full contents for the item. Mostly used together with the description
element where description
holds the summary.
feed.additem({
content: '<p>Full text contents</p>',
description: 'Summary of the post'
});
creator
creator
maps to dc:creator
from Dublin Core and is a string with the name of the person who created the item.
feed.additem({
creator: 'My name'
});
itunes
itunes
is an object that maps to the itunes specification and is used for podcasting. Item level itunes element goes together with enclosure
element that defines the actual podcast show, itunes
only adds metadata to it. The object supports the following properties:
- author - string, artist column in iTunes
- block - boolean, if true then the this episode is removed from the iTunes Store
- duration - string, formatted as hh:mm:ss or mm:ss
- explicit - boolean, if true then parental advisory graphic is shown under podcast details
- image - string, url to the logo of the podcast
- isClosedCaptioned - boolean, if true shows Closed Caption graphic in Name column
- order - number, if used overrides the ordering in itunes listing, for example, "1" sets this as the first item
- subtitle - string, description column
- summary - string, displayed when the circled i icon in the Description column in iTunes is clicked
var headers = {
enclosure: 'http://path/to/assets/podcast.mp3',
itunes: {
author: 'Your\'s truly',
duration: '13:34'
}
};
lat and long
lat
and long
map to geo:lat
and geo:long
from the Basic Geo module. The values indicate a geographical point related to the item.
feed.additem({
lat: 55.701,
long: 12.552
});
media
media
is an object that maps to media:content
of the Media RSS module. For multiple media elements, use an array for the values.
Media object supports the following properties:
- url
- fileSize
- type
- medium
- duration
- height
- width
- title
- description
- keywords
- thumbnails
- category
- player
- credit
- ... and many more, only values that require sub-elements are not supported
feed.additem({
media: {
url: 'http://path/to/assets/1.jpg',
medium: 'image',
title: 'Attached image',
restriction: {
type: 'sharing',
relationship: 'deny'
}
}
});
License
MIT