Adding Manual Posts

Relevant source files

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

• add-post.html
• server.js
• scripts/collect-manual-posts.js
• package.json
• utils/index.js

The "Adding Manual Posts" feature provides a mechanism for manually inserting news items into the project's RSS feed. This is distinct from the automated processes that collect news from GitHub issues, discussions, and releases. The system consists of a simple web interface for content entry, a lightweight Node.js/Express backend to handle data persistence, and a dedicated script to integrate the manual posts into the final feed.xml file.

This feature allows curators to add timely or specific content that doesn't originate from the standard automated sources, providing greater flexibility for the news feed. The entire process is managed locally through a web form and a command-line script.

Architecture Overview

The manual post feature is composed of three main components: a web UI, a backend server, and a collection script. The user interacts with the web form to add a post, which is saved to a JSON file by the server. Later, a separate script reads this JSON file and injects the posts into the main RSS feed.

The following diagram illustrates the high-level data flow for adding and processing manual posts.

Web Interface and Backend API

A local development server, started with npm run start, provides the user interface and API for managing manual posts.

Sources: package.json:11, server.js

User Interface (add-post.html)

The add-post.html file provides a simple web form for creating new posts and a list to display existing manual posts.

Sources: add-post.html:1-100

Form Fields

The form contains the following fields for creating a new post:

Field	ID	Type	Description	Required
Title	title	text	The title of the news item.	Yes
Description	description	textarea	The main content of the news item.	Yes
Link	link	text	The URL for the news item.	Yes
Publication Date	published_at	datetime-local	The date and time the post was published. If left blank, the server defaults to the current time.	No

Sources: add-post.html:20-35, server.js:61-62

Client-Side Logic

The page includes JavaScript to handle two main functions:

1. Displaying Posts: On page load, it sends a GET request to /api/posts to fetch all entries from manual-posts.json and renders them on the page.
2. Submitting New Posts: When the form is submitted, it sends a POST request to /api/posts with the form data as a JSON payload. On a successful response, it resets the form and refreshes the list of posts.

Sources: add-post.html:43-89

The sequence diagram below shows the interaction between the user's browser and the local server when adding a new post.

Backend API (server.js)

The server.js file sets up an Express server to handle the client-side requests. It defines the file path for the data store and creates two API endpoints.

Sources: server.js:5-10

API Endpoints

Method	Path	Description
GET	/api/posts	Reads the manual-posts.json file and returns its content as a JSON array. If the file doesn't exist, it returns an empty array.
POST	/api/posts	Receives a new post object. It reads the existing posts, appends the new one with a generated id and published_at timestamp, and writes the entire array back to manual-posts.json.

Sources: server.js:16-71

Data Storage (manual-posts.json)

Manual posts are stored in a simple JSON file named manual-posts.json at the root of the project. This file contains a JSON array of post objects.

The structure of a post object within the array is defined by the server when it processes a POST request.

An example of a post object in manual-posts.json would look like this:

[
  {
    "title": "Example Manual Post",
    "description": "This is a description for a manually added post.",
    "link": "https://example.com/news-item",
    "published_at": "2023-10-27T10:00:00.000Z",
    "id": 1698397200000
  }
]

Sources: server.js:59-63

Feed Integration Script

After posts have been added to manual-posts.json, they must be integrated into the main feed.xml. This is done by running the collect:manual script.

npm run collect:manual

Sources: package.json:10

collect-manual-posts.js

This script is responsible for reading the manual posts and injecting them into the RSS feed.

The process is as follows:

1. Read Manual Posts: The getManualPosts function reads and parses manual-posts.json.
2. Compose Feed Items: Each post object is transformed into an XML <item> block using the composeFeedItem utility function. The description is converted from Markdown to HTML, and the date is formatted to RFC 822.
3. Inject into Feed: The script reads the existing feed.xml, splits it at the breakDelimiter (which is </image>), and inserts the newly generated <item> blocks.
4. Overwrite Feed: The modified XML content is written back to feed.xml.

Sources: scripts/collect-manual-posts.js:1-31, utils/index.js:120-138, 15-17, config.json:12

The following flowchart visualizes the logic of the collect-manual-posts.js script.

Summary

The manual post feature is a straightforward yet powerful addition to the news feeder. It decouples content entry from the feed generation process by using a simple web UI and a local server to persist data in a manual-posts.json file. A separate build script, collect-manual-posts.js, is then used to integrate this curated content into the final feed.xml, ensuring that manually added items are correctly formatted and included alongside automatically sourced news.

Sources: add-post.html, server.js, scripts/collect-manual-posts.js