Add PublishMarkdown plugin for writing feeds as Markdown documents - #134
Merged
Conversation
Automatic Ruby collects from many sources into one composable pipeline, and what a run leaves behind is the Recipe's choice. Add the exit that needs nothing outside the machine: a Markdown document, readable by a person, processable with ordinary tools, keepable in version control, and usable as input to another program. Requirements and design come first, and the implementation follows them. doc/REQUIREMENTS.md states that publishing a portable document is a primary use, names Markdown as the standard publication format for it, and records that an output format is never a second pipeline representation. doc/BASIC_DESIGN.md places PublishMarkdown at the Publish boundary as a serializer, keeping Markdown out of the framework, out of the pipeline value and out of any implicit step. doc/PLUGINS.md specifies what it writes. Nothing existing changes meaning: the pipeline value keeps its shape, RSS and Atom remain input formats, SubscriptionFeed is untouched, no Recipe gains a plugin it did not name, and framework core is not modified. - plugins/publish/markdown.rb: a level-2 heading per item, a metadata list of the fields the item carries, content_encoded before description, HTML reduced to text with nokogiri rather than translated, deterministic output, and file and mode settings; the pipeline is returned unchanged. - spec/plugins/publish/markdown_spec.rb: 25 examples, no network, no credential, file examples confined to a temporary directory. - config/feed2markdown.yml: collect, filter, de-duplicate, append to a file. - README, DEPLOYMENT and VERSIONS updated, and the plugin counts raised to forty-five, twenty-three of them Supported. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016JMWCNj1qYTpsxJA9t72uA
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces
PublishMarkdown, a new publishing plugin that serializes the feed pipeline as a Markdown document, writing to either a file or standard output. This enables Recipes to produce human-readable, version-control-friendly output without requiring external services or credentials.Key Changes
New plugin:
PublishMarkdown(plugins/publish/markdown.rb)Comprehensive test suite (
spec/plugins/publish/markdown_spec.rb)Documentation updates
doc/PLUGINS.mdsection 6.7 with detailedPublishMarkdownspecificationdoc/BASIC_DESIGN.mdsection explaining the Publish boundary and pipeline serializationdoc/DEPLOYMENT.mdsection on publishing to Markdown with operational guidancedoc/REQUIREMENTS.mdsections 10.1-10.2 on output and publication formatsdoc/POLICY.mdto clarify that format conversion is a Publish plugin responsibilityExample configuration (
config/feed2markdown.yml)README updates
PublishMarkdowninstead ofPublishConsoleImplementation Details
HTML-to-text conversion: Reduces markup to plain text rather than translating to Markdown, avoiding a large library dependency. Scripts are removed, block elements become paragraph breaks,
<br>becomes line breaks, and entities are decoded.Whitespace normalization: Handles line ending conversion, trailing whitespace removal, and blank line collapsing. Text from markup also has indentation stripped to prevent Markdown code block interpretation.
Metadata handling: Supports both string and element-based fields (source.content, enclosure.url) from parsed feeds. URLs are wrapped as autolinks (
<url>) for both rendering and grep compatibility.Deterministic output: Date formatting uses the item's own timezone without conversion, ensuring identical output across machines. Empty pipelines produce no file output.
File handling: Appends by default (suitable for cron jobs building a journal), with optional overwrite mode. Empty runs don't create or modify files.
https://claude.ai/code/session_016JMWCNj1qYTpsxJA9t72uA