astrojs-atom

A library for generating Atom syndication feeds in Astro projects. This is a fork of @astrojs/rss that implements the Atom feed format instead of RSS.

Installation

# Using npm
npm install astrojs-atom

# Using yarn
yarn add astrojs-atom

# Using pnpm
pnpm install astrojs-atom

Usage

Create a new .xml.js or .xml.ts file in your Astro pages directory to generate an Atom feed:

// src/pages/atom.xml.js
import { getAtomResponse } from 'astrojs-atom';

export async function GET(context) {
  return getAtomResponse({
    // Required: Feed metadata
    title: "My Website",
    id: "https://example.com/",
    updated: new Date().toISOString(),
    
    // Required: Array of feed entries
    entry: [
      {
        title: "My First Article",
        id: "https://example.com/blog/first-article",
        updated: "2023-01-01T00:00:00Z",
        // Optional: content, author, link, etc.
        content: "This is my first article.",
        link: [
          { href: "https://example.com/blog/first-article", rel: "alternate" }
        ]
      }
    ],
    
    // Optional: Customize the feed with additional properties
    subtitle: "My Personal Blog",
    lang: "en-US",
    author: [
      { 
        name: "Your Name",
        email: "[e-mail]"
      }
    ],
    // Add custom stylesheet
    stylesheet: "/atom-styles.xsl"
  });
}

API Reference

Main Functions

• getAtomResponse: Returns a Response object with the Atom XML and proper headers
• getAtomString: Returns just the XML string without creating a Response object

Feed Options (AtomFeedOptions)

Required Properties

Property	Type	Description
title	string or object	Title of the feed. Can be a simple string or an object with value and type attributes
id	string	Unique identifier for the feed (typically your site URL)
updated	string	Last updated timestamp (RFC 3339 format)
entry	Array	Array of feed entries

Optional Properties

Property	Type	Description
subtitle	string	Description or subtitle for the feed
author	Array	Feed authors as an array of person objects
link	Array	Links related to the feed
category	Array	Categories for the feed
contributor	Array	Contributors to the feed
generator	object	Information about the generator of the feed
icon	string	URL to an icon for the feed
logo	string	URL to a logo for the feed
rights	string or object	Copyright information
lang	string	Language of the feed (sets xml:lang attribute)
xmlns	object	Custom XML namespaces to include
stylesheet	string	URL to an XSL stylesheet
customData	string	Custom XML to include in the feed

Entry Properties

Each entry in the entry array can have the following properties:

Required Properties

Property	Type	Description
title	string or object	Title of the entry
id	string	Unique identifier for the entry
updated	string	Last updated timestamp (RFC 3339 format)

Optional Properties

Property	Type	Description
author	Array	Entry authors
content	string or object	Full content of the entry. When using an object, you can specify type (like "html") and the value
link	Array	Links related to the entry
summary	string or object	Summary of the entry
category	Array	Categories for the entry
contributor	Array	Contributors to the entry
published	string	Publication date (RFC 3339 format)
rights	string or object	Entry-specific copyright information
source	object	Source feed information for republished entries
customData	string	Custom XML to include in the entry
thumbnail	object	Thumbnail image for the entry

Text Constructs (title, summary, rights)

For properties like title, summary, and rights, you can use either:

• A simple string: title: "My Title"
• An object with attributes: title: { value: "My Title", type: "html" }

Type Attribute Values

Common type attribute values include:

• "text" (default) - Plain text
• "html" - HTML content
• "xhtml" - XHTML content
• "application/xml" or other MIME types

Examples

Entry with HTML Content

{
  title: "My Article",
  id: "https://example.com/blog/my-article",
  updated: "2023-01-01T00:00:00Z",
  content: {
    type: "html",
    value: "<p>This is <strong>formatted</strong> content.</p>"
  }
}

Using Custom XML Namespaces

getAtomResponse({
  // ...feed options
  xmlns: {
    "dc": "http://purl.org/dc/elements/1.1/",
    "georss": "http://www.georss.org/georss"
  },
  entry: [
    {
      // ...entry properties
      customData: '<dc:creator>John Smith</dc:creator><georss:point>45.256 -71.92</georss:point>'
    }
  ]
});

Media Content

The Atom feed generator supports adding media elements to entries using the Yahoo Media RSS extension.

Adding Thumbnails

You can add thumbnail images to entries with the thumbnail property:

{
  // ...other entry properties
  thumbnail: {
    url: "https://example.com/images/thumbnail.jpg",
    medium: "image", // Optional, defaults to "image"
    width: 300,      // Optional
    height: 200      // Optional
  }
}

This will generate both media:thumbnail and media:content elements in your feed:

<media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" 
  url="https://example.com/images/thumbnail.jpg"
  width="300" height="200" />
<media:content medium="image" 
  url="https://example.com/images/thumbnail.jpg"
  width="300" height="200"
  xmlns:media="http://search.yahoo.com/mrss/" />

The Media RSS namespace (xmlns:media="http://search.yahoo.com/mrss/") is automatically added when a thumbnail is included.

Validation

To validate your Atom feed, use the W3C Feed Validation Service.