Deployment to GitHub Pages

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• scripts/build-website.js
• scripts/build-rss.js
• utils/index.js
• index.html
• config.json

This project utilizes GitHub Pages to host a publicly accessible news website and its corresponding RSS feed. The content is automatically generated and updated through a series of scripts and a GitHub Actions workflow. The final outputs are static files (index.html and feed.xml) served directly from the repository.

The live website can be accessed at https://nodejs.github.io/nodejs-news-feeder/, and the RSS feed is available at https://nodejs.github.io/nodejs-news-feeder/feed.xml. The deployment process is designed to be automated, ensuring that once new content is curated and merged into the main branch, it is reflected on the live site.

Sources: README.md:21-27

Architecture Overview

The deployment architecture is centered around a GitHub Action that automates content aggregation and prepares it for publication. The process can be triggered either by a cron job or manually. This action executes various scripts to collect news from different sources, formats the data into feed items, and proposes the changes in a pull request.

After curators review and approve the pull request, it is merged into the main branch. GitHub Pages is configured to serve files from this branch, so any changes merged are automatically deployed to the live site.

Sources: README.md:31-41

The following diagram illustrates the end-to-end workflow from content creation to deployment.

Content Generation Process

The static files served by GitHub Pages (index.html and feed.xml) are generated by a set of Node.js scripts.

RSS Feed (feed.xml) Generation

The core of the content is the feed.xml file. It is populated by a series of collection scripts and finalized by a build script.

1. Content Collection: Scripts like collect-releases.js, collect-issues.js, and collect-retrospective.js are run to fetch new data from various sources. These scripts use the lastCheckTimestamp from config.json to only gather new items. Each new item is formatted into an XML <item> block using the composeFeedItem utility function and inserted into feed.xml.
   Sources: scripts/collect-releases.js, scripts/collect-issues.js, scripts/collect-retrospective.js, config.json:2, utils/index.js:140-155

2. Feed Finalization: The npm run rss:build command executes scripts/build-rss.js. This script updates the <lastBuildDate> tag in feed.xml to the current time. It also updates the lastCheckTimestamp in config.json to ensure future runs only pick up newer content.
   Sources: package.json:10, scripts/build-rss.js:14-22

Website (index.html) Generation

The index.html file is a user-friendly web page that displays the news from the RSS feed. It is generated by the scripts/build-website.js script, which is executed via the npm run website:build command.

The script performs the following steps:

1. Reads the content of feed.xml using the getFeedContent utility.
2. Parses the XML content into structured data (metadata and items) using the @ulisesgascon/rss-feed-parser library.
3. Reads an EJS template from templates/index.html.ejs using the getWebsiteTemplate utility.
4. Renders the final HTML by passing the parsed feed data to the EJS template.
5. Writes the generated HTML to the index.html file in the project root using overwriteWebsiteContent.

Sources: package.json:12, scripts/build-website.js:1-12, utils/index.js:163-165, 171-173

The following sequence diagram shows the interaction for building the website.

Key Files and Scripts

The deployment process relies on a specific set of files and scripts within the repository.

Key Files

File Path	Description
index.html	The main HTML file for the GitHub Pages website, generated by the website:build script.
feed.xml	The RSS feed file, populated by collect:* scripts and finalized by rss:build.
scripts/build-website.js	The Node.js script responsible for generating index.html from the feed data.
scripts/build-rss.js	The Node.js script that updates timestamps in feed.xml and config.json.
utils/index.js	Provides utility functions for reading and writing files, including feed.xml, index.html, and config.json.
config.json	Stores configuration, including the lastCheckTimestamp used by collection scripts to fetch new content.

Sources: index.html, config.json, scripts/build-website.js, scripts/build-rss.js, utils/index.js

Relevant NPM Scripts

The following scripts defined in package.json are central to building the content for deployment.

Script	Command	Description
website:build	node scripts/build-website.js	Generates the index.html website from the feed.xml content.
rss:build	node scripts/build-rss.js	Finalizes the feed.xml by updating its lastBuildDate and updates the lastCheckTimestamp in config.json.
collect:releases	node scripts/collect-releases.js	Collects new GitHub releases and adds them to the feed.
collect:issues	node scripts/collect-issues.js	Collects new comments from specific GitHub issues and adds them to the feed.
collect:discussions	node scripts/collect-discussions.js	Collects new comments from specific GitHub discussions and adds them to the feed.
collect:retrospective	node scripts/collect-retrospective.js	Collects content from external RSS feeds and websites to add to the feed.

Sources: package.json:6-12

Summary

The deployment to GitHub Pages is a streamlined, automated process that transforms collected data into a static website and RSS feed. It begins with data collection via scripts, followed by a human-in-the-loop curation step using pull requests. Once changes are merged into the main branch, GitHub Pages handles the final step of publishing the updated index.html and feed.xml files, making the latest news available to the public. This system ensures content is timely, reviewed, and consistently formatted.

Sources: README.md:31-41