From f0d84679e97d11eede2c4edaeda96b93fcf31671 Mon Sep 17 00:00:00 2001 From: Dylan Greene Date: Sat, 14 Sep 2013 15:57:39 -0400 Subject: [PATCH] improved docs --- readme.md | 128 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 73 insertions(+), 55 deletions(-) diff --git a/readme.md b/readme.md index 06160f6..70da192 100644 --- a/readme.md +++ b/readme.md @@ -10,6 +10,70 @@ ## Usage +### Create a new feed + +```js +var RSS = require('rss'); + +var feed = new RSS(feedOptions); +``` + +#### `feedOptions` + + * `title` **string** Title of your site or feed + * `description` _optional_ **string** A short description of the feed. + * `generator` _optional_ **string** Feed generator. + * `feed_url` **url string** Url to the rss feed. + * `site_url` **url string** Url to the site that the feed is for. + * `image_url` _optional_ **url string* Small image for feed readers to use. + * `docs` _optional_ **url string** Url to documentation on this feed. + * `author` **string** Who owns this feed. + * `managingEditor` _optional_ **string** Who manages content in this feed. + * `webMaster` _optional_ **string** Who manages feed availability and technical support. + * `copyright` _optional_ **string** Copyright information for this feed. + * `language` _optional_ **string** The language of the content of this feed. + * `categories` _optional_ **array of strings** One or more categories this feed belongs to. + * `pubDate` _optional_ **Date object or date string** The publication date for content in the feed + * `ttl` _optional_ **integer** Number of minutes feed can be cached before refreshing from source. + +### Add items to a feed + +An item can be used for a blog entry, project update, log entry, etc. Your RSS feed +an have any number of items. Most feeds use 20 or fewer items. + +```js +feed.item(itemOptions); +``` + +#### itemOptions + + * `title` **string** Title of this particular item. + * `description` **string** Content for the item. Can contain html but link and image urls must be absolute path including hostname. + * `url` **url string** Url to the item. This could be a blog entry. + * `guid` **unique string** A unique string feed readers use to know if an item is new or has already been seen. + If you use a guid never change it. If you don't provide a guid then your item urls must + be unique. + * `categories` _optional_ **array of strings** If provided, each array item will be added as a category element + * `author` _optional_ **string** If included it is the name of the item's creator. + If not provided the item author will be the same as the feed author. This is typical + except on multi-author blogs. + * `date` **Date object or date string** The date and time of when the item was created. Feed + readers use this to determine the sort order. Some readers will also use it to determine + if the content should be presented as unread. + +#### Feed XML + +```js +var xml = feed.xml(indent); +``` + +This returns the XML as a string. + +`indent` _optional_ **string** What to use as a tab. Defaults to no tabs (compressed). + For example you can use `'\t'` for tab character, or `' '` for two-space tabs. + +## Example Usage + ```js var RSS = require('rss'); @@ -43,60 +107,10 @@ feed.item({ enclosure : {url:'...', file:'path-to-file'} // optional }); -// cache the xml +// cache the xml to send to clients var xml = feed.xml(); ``` -### Feed Options - - * `title` **string** Title of your site or feed - * `description` _optional_ **string** A short description of the feed. - * `generator` _optional_ **string** Feed generator. - * `feed_url` **url string** Url to the rss feed. - * `site_url` **url string** Url to the site that the feed is for. - * `image_url` _optional_ **url string* Small image for feed readers to use. - * `docs` _optional_ **url string** Url to documentation on this feed. - * `author` **string** Who owns this feed. - * `managingEditor` _optional_ **string** Who manages content in this feed. - * `webMaster` _optional_ **string** Who manages feed availability and technical support. - * `copyright` _optional_ **string** Copyright information for this feed. - * `language` _optional_ **string** The language of the content of this feed. - * `categories` _optional_ **array of strings** One or more categories this feed belongs to. - * `pubDate` _optional_ **Date object or date string** The publication date for content in the feed - * `ttl` _optional_ **integer** Number of minutes feed can be cached before refreshing from source. - -### Item Options - -In RSS an item can be used for a blog entry, project update, log entry, etc. Your rss feed -an have any number of items. Ten to twenty is usually good. - - * `title` **string** Title of this particular item. - * `description` **string** Content for the item. Can contain html but link and image urls must be absolute path including hostname. - * `url` **url string** Url to the item. This could be a blog entry. - * `guid` **unique string** A unique string feed readers use to know if an item is new or has already been seen. - If you use a guid never change it. If you don't provide a guid then your item urls must - be unique. - * `categories` _optional_ **array of strings** If provided, each array item will be added as a category element - * `author` _optional_ **string** If included it is the name of the item's creator. - If not provided the item author will be the same as the feed author. This is typical - except on multi-author blogs. - * `date` **Date object or date string** The date and time of when the item was created. Feed - readers use this to determine the sort order. Some readers will also use it to determine - if the content should be presented as unread. - -### Methods - -#### `item(item_options)` - -Add an rss item/article. - -#### `xml([indent])` - -Return the xml. - -If you pass in `true` it will use four spaces for indenting. If you prefer - tabs pass in `\t` instead of true, or a two space string for two space tabs. - ## Tests Tests included use Mocha. Use `npm test` to run the tests. @@ -108,13 +122,17 @@ Tests included use Mocha. Use `npm test` to run the tests. * This module is very fast but you might as well cache the output of xml() and serve it until something changes. +# History + +I started this module over two years ago (April 2011) because there weren't any Node modules +for creating RSS. Besides these [25 modules](https://npmjs.org/browse/depended/rss) +I would love to know what other projects are using it. + # Contributing Contributions to the project are welcome. Feel free to fork and improve. -I accept pull requests when tests and updated docs are included. - -I'm not actively adding features to this module. If you would like to take over maintaining it -just let me know. +I do my best accept pull requests in a timely manor, especially when tests and updated docs +are included. # License