feed

README

Feed

Go library to output RSS 2.0 and Atom 1.0 feeds from one shared feed model.

Install

go get github.com/jor-go/feed

Usage

package main

import (
	"log"
	"os"
	"time"

	"github.com/jor-go/feed"
)

func main() {
	f := feed.New("Example Feed", "https://example.com", "Latest posts")
	f.ID = "urn:example:feed"
	f.Updated = time.Now().UTC()
	f.Authors = []feed.Person{{Name: "Jordan"}}

	f.AddItem(feed.Item{
		Title:     "Hello",
		Link:      "https://example.com/hello",
		ID:        "urn:example:hello",
		Updated:   time.Now().UTC(),
		Summary:   "A short post.",
		Content:   feed.Content{Type: feed.ContentTypeHTML, Value: "<p>A short post.</p>"},
		Published: time.Now().UTC(),
	})

	if err := f.WriteRSS(os.Stdout); err != nil {
		log.Fatal(err)
	}

	if err := f.WriteAtom(os.Stdout); err != nil {
		log.Fatal(err)
	}
}

API

• feed.New(title, link, description string) creates a shared feed.
• (*Feed) AddItem(feed.Item) appends an item once for both formats.
• Feed.MarshalRSS and Feed.WriteRSS render RSS 2.0.
• Feed.MarshalAtom and Feed.WriteAtom render Atom 1.0.
• feed.Parse, feed.ParseRSS, feed.ParseAtom, feed.Read, feed.ReadRSS, and feed.ReadAtom parse existing feeds into the shared model.
• Feed.ValidateRSS and Feed.ValidateAtom report format-specific missing fields before rendering.

RSS requires feed Title, Link, and Description. Atom requires feed Title, an ID source (ID or Link), Updated, and either feed-level authors or item-level authors.

Parsing

raw := []byte(`<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>Example Feed</title>
    <link>https://example.com</link>
    <description>Latest posts</description>
  </channel>
</rss>`)

f, format, err := feed.Parse(raw)
if err != nil {
	log.Fatal(err)
}

log.Println(format, f.Title)

Parsing is intentionally practical: recognized RSS and Atom fields are mapped into Feed, unknown extension elements are ignored, and malformed XML, unsupported roots, invalid dates, invalid TTL values, and invalid enclosure lengths return errors.

Specs

• Atom: RFC 4287 and rfc/rfc4287.txt
• RSS 2.0: RSS 2.0 Specification

Documentation

Overview

Package feed creates RSS 2.0 and Atom 1.0 XML feeds from one shared model.

Index

• Constants
• func Parse(data []byte) (*Feed, Format, error)
• func Read(r io.Reader) (*Feed, Format, error)
• type Category
• type Content
• type Enclosure
• type Feed
  • func New(title, link, description string) *Feed
  • func ParseAtom(data []byte) (*Feed, error)
  • func ParseRSS(data []byte) (*Feed, error)
  • func ReadAtom(r io.Reader) (*Feed, error)
  • func ReadRSS(r io.Reader) (*Feed, error)
  • func (f *Feed) AddItem(item Item)
  • func (f Feed) MarshalAtom() ([]byte, error)
  • func (f Feed) MarshalRSS() ([]byte, error)
  • func (f Feed) ValidateAtom() error
  • func (f Feed) ValidateRSS() error
  • func (f Feed) WriteAtom(w io.Writer) error
  • func (f Feed) WriteRSS(w io.Writer) error
• type Format
• type Image
• type Item
• type Person
• type ValidationError
  • func (e *ValidationError) Error() string

Examples

• Feed.MarshalAtom
• Feed.MarshalRSS
• Parse

Constants

const (
	// ContentTypeText renders Atom content as plain text.
	ContentTypeText = "text"
	// ContentTypeHTML renders Atom content as escaped HTML markup.
	ContentTypeHTML = "html"
	// ContentTypeXHTML renders Atom content as raw XHTML markup.
	ContentTypeXHTML = "xhtml"
)

Functions

func Parse

func Parse(data []byte) (*Feed, Format, error)

Parse parses an RSS 2.0 or Atom 1.0 feed and returns the detected format.

Example

package main

import (
	"fmt"

	"github.com/jor-go/feed"
)

func main() {
	raw := []byte(`<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>Example Feed</title>
    <link>https://example.com</link>
    <description>Latest posts</description>
    <item>
      <title>Hello</title>
      <link>https://example.com/hello</link>
      <description>A short post.</description>
    </item>
  </channel>
</rss>`)

	f, format, err := feed.Parse(raw)
	fmt.Println(err == nil)
	fmt.Println(format)
	fmt.Println(f.Items[0].Title)
}

Output:
true
rss
Hello

func Read

func Read(r io.Reader) (*Feed, Format, error)

Read reads and parses an RSS 2.0 or Atom 1.0 feed from r.

Types

type Category

type Category struct {
	Term   string
	Domain string
	Label  string
}

Category describes a category or tag. Domain maps to RSS domain and Atom scheme; Label is Atom-only.

type Content

type Content struct {
	Type  string
	Value string
}

Content describes Atom entry content. Type defaults to "text"; "html" and "xhtml" are also supported.

type Enclosure

type Enclosure struct {
	URL    string
	Length int64
	Type   string
}

Enclosure describes a media attachment. URL, Length, and Type are required by RSS 2.0 and map to Atom enclosure links.

type Feed

type Feed struct {
	Title       string
	Link        string
	Description string
	ID          string

	// Updated is required for Atom and is rendered as RSS lastBuildDate.
	Updated time.Time
	// Published is rendered as RSS pubDate when set.
	Published time.Time

	Language         string
	Copyright        string
	Generator        string
	GeneratorURI     string
	GeneratorVersion string
	Self             string
	TTL              int

	Authors    []Person
	Categories []Category
	Image      *Image
	Items      []Item
}

Feed contains the shared metadata and items that can be rendered as RSS 2.0 or Atom 1.0.

func New

func New(title, link, description string) *Feed

New creates a feed with the RSS-required channel fields.

func ParseAtom

func ParseAtom(data []byte) (*Feed, error)

ParseAtom parses an Atom 1.0 feed into the shared Feed model.

func ParseRSS

func ParseRSS(data []byte) (*Feed, error)

ParseRSS parses an RSS 2.0 feed into the shared Feed model.

func ReadAtom

func ReadAtom(r io.Reader) (*Feed, error)

ReadAtom reads and parses an Atom 1.0 feed from r.

func ReadRSS

func ReadRSS(r io.Reader) (*Feed, error)

ReadRSS reads and parses an RSS 2.0 feed from r.

func (*Feed) AddItem

func (f *Feed) AddItem(item Item)

AddItem appends an item to the feed.

func (Feed) MarshalAtom

func (f Feed) MarshalAtom() ([]byte, error)

MarshalAtom returns the Atom 1.0 XML document.

Example

package main

import (
	"fmt"
	"strings"
	"time"

	"github.com/jor-go/feed"
)

func main() {
	f := feed.New("Example Feed", "https://example.com", "Latest posts")
	f.ID = "urn:example:feed"
	f.Updated = time.Date(2026, 5, 13, 18, 0, 0, 0, time.UTC)
	f.Authors = []feed.Person{{Name: "Jordan"}}
	f.AddItem(feed.Item{
		Title:   "Hello",
		Link:    "https://example.com/hello",
		ID:      "urn:example:hello",
		Updated: time.Date(2026, 5, 13, 18, 0, 0, 0, time.UTC),
		Summary: "A short post.",
	})

	out, err := f.MarshalAtom()
	fmt.Println(err == nil)
	fmt.Println(strings.Contains(string(out), `xmlns="http://www.w3.org/2005/Atom"`))
}

Output:
true
true

func (Feed) MarshalRSS

func (f Feed) MarshalRSS() ([]byte, error)

MarshalRSS returns the RSS 2.0 XML document.

Example

package main

import (
	"fmt"
	"strings"
	"time"

	"github.com/jor-go/feed"
)

func main() {
	f := feed.New("Example Feed", "https://example.com", "Latest posts")
	f.AddItem(feed.Item{
		Title:       "Hello",
		Link:        "https://example.com/hello",
		Description: "A short post.",
		Published:   time.Date(2026, 5, 13, 18, 0, 0, 0, time.UTC),
	})

	out, err := f.MarshalRSS()
	fmt.Println(err == nil)
	fmt.Println(strings.Contains(string(out), `<rss version="2.0">`))
}

Output:
true
true

func (Feed) ValidateAtom

func (f Feed) ValidateAtom() error

ValidateAtom validates the shared feed for Atom 1.0 output.

func (Feed) ValidateRSS

func (f Feed) ValidateRSS() error

ValidateRSS validates the shared feed for RSS 2.0 output.

func (Feed) WriteAtom

func (f Feed) WriteAtom(w io.Writer) error

WriteAtom writes the Atom 1.0 XML document to w.

func (Feed) WriteRSS

func (f Feed) WriteRSS(w io.Writer) error

WriteRSS writes the RSS 2.0 XML document to w.

type Format

type Format string

Format identifies a parsed feed format.

const (
	// FormatRSS identifies an RSS 2.0 feed.
	FormatRSS Format = "rss"
	// FormatAtom identifies an Atom 1.0 feed.
	FormatAtom Format = "atom"
)

type Image

type Image struct {
	URL         string
	Title       string
	Link        string
	Description string
	Width       int
	Height      int
}

Image describes the optional RSS channel image.

type Item

type Item struct {
	Title       string
	Link        string
	Description string
	Summary     string
	ID          string

	Updated   time.Time
	Published time.Time

	Authors    []Person
	Categories []Category
	Comments   string
	Content    Content
	Enclosures []Enclosure
}

Item contains shared entry metadata that can be rendered as an RSS item or Atom entry.

type Person

type Person struct {
	Name  string
	Email string
	URI   string
}

Person describes a feed or item author.

type ValidationError

type ValidationError struct {
	Format   string
	Problems []string
}

ValidationError describes one or more validation problems for a feed format.

func (*ValidationError) Error

func (e *ValidationError) Error() string