mdphlex 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df56be38ad404b1762ae330d4f59f21de2ab56ed0248688a8134890f61f407e7
-  data.tar.gz: 4bde2036075332276a3d3882cdabf931c97be472f67612a72c82a7cb513607be
+  metadata.gz: 7df543d1ff68faf2b25ce38d74a767d5957a4322ce83d7ad424190cd7ee0bd7f
+  data.tar.gz: 427fecb092f11651e9f5d463fd544ed6d6bb4891bfdd7a338c0e5312a51d5f35
 SHA512:
-  metadata.gz: c8835c134e433334f033dc01dc8614476dd281c2c2be6223cb5dda92dabebdcad101bb1d2bb6f3806a6c792bd69b8a639410739ce417cf6fee90d81930191ee5
-  data.tar.gz: db3062396e99e68aa12ffbbe3c950fbf83c1e8549a88b6d6e0b289d4b39791975fd5ff7be99f983eb4a9fd2658bcacdcb6095053e3d5420807e1a49a2aef96cb
+  metadata.gz: 1f895e699d4d037f6f3aaf8d33a6ff9e263fb24a1ee07d455fcdd7c8e3fff11b707ba85a17b7f053c33e78fe864dbaf18e8e67a97c62e520aafd3a747af68aef
+  data.tar.gz: dc0f27b7faadd20203f588733b14236b6b1cbdd47db87aae3ec299a767a58534d51a5e1a5088f9b10021ce83f81d41554112e0d67ac1fb94d73a0a4874ee6698

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## 0.2.0 - 2025-09-11
+
+- Add to_markdown for Rails 8.1 support
+
 ## [0.1.0] - 2025-09-03
 
 - Initial release

data/README.md

@@ -1,10 +1,8 @@
 # MDPhlex
 
-> Inversion of Markdown
-
 MDPhlex is a Phlex component for rendering Markdown. No... not rendering markdown into HTML, rendering plain Markdown, programmatically.
 
-MDPhlex is perfect for dynamically creating context for LLMs, generating an llms.txt file from real content, or doing something silly like passing the output to a markdown renderer to create HTML or generating blog posts that look like they were hand-written markdown.
+MDPhlex is perfect for dynamically creating context for LLMs, generating an llms.txt file from real content, or composing markdown out of componentized pieces.
 
 ## Installation
 
@@ -16,7 +14,7 @@ gem 'mdphlex'
 
 ## Creating LLM Prompts with MDPhlex
 
-MDPhlex shines when creating structured prompts for LLMs. Here's a simple example using custom tags:
+MDPhlex shines when creating structured prompts for LLMs allowing comments and organization without cluttering the prompt. Here's a simple example using custom tags:
 
 ~~~ruby
 class LLMPrompt < MDPhlex::MD
@@ -32,17 +30,21 @@ class LLMPrompt < MDPhlex::MD
 
   def view_template
     system do
-      plain "You are an AI assistant specialized in #{@task}."
-      plain "\nUse the available tools to help users effectively."
-    end
+      p "You are an AI assistant specialized in #{@task}."
+      
+      h2 "Goal"
+      # we should define the goal more clearly.
+      p "Use the available tools to help the user."
 
-    plain "\n"
+      # what about guardrails?
+    end
 
     if @tools.any?
       tools do
         @tools.each do |tool_def|
           tool name: tool_def[:name] do
             plain tool_def[:description]
+            # need to add input schemas
           end
         end
       end
@@ -67,8 +69,11 @@ This outputs clean, structured markdown perfect for LLMs:
 ~~~xml
 <system>
 You are an AI assistant specialized in Ruby code analysis.
-Use the available tools to help users effectively.</system>
 
+## Goal
+Use the available tools to help the user.
+
+</system>
 <tools>
 <tool name="analyze_code">
 Analyze Ruby code for improvements</tool>
@@ -77,11 +82,96 @@ Explain Ruby concepts and patterns</tool>
 </tools>
 ~~~
 
-The XML-style tags help LLMs understand different sections of the prompt, while Ruby's dynamic nature lets you generate prompts based on runtime conditions.
-
 ## Traditional Markdown Generation
 
-MDPhlex also works great for generating regular Markdown content:
+MDPhlex also works great for generating regular Markdown content.
+
+### Rails Integration with Markdown Rendering
+
+With Rails 8.1's native markdown support, MDPhlex components integrate seamlessly:
+
+~~~ruby
+# app/components/page_component.rb
+class PageComponent < MDPhlex::MD
+  def initialize(page)
+    @page = page
+  end
+
+  def view_template
+    h1 @page.title
+
+    p do
+      em "Last updated: #{@page.updated_at.strftime('%B %d, %Y')}"
+    end
+
+    hr
+
+    # Render page sections with proper markdown structure
+    @page.sections.each do |section|
+      h2 section.heading
+
+      p section.content
+
+      if section.code_example?
+        pre(language: section.language) { plain section.code }
+      end
+    end
+
+    if @page.references.any?
+      h2 "References"
+      ul do
+        @page.references.each do |ref|
+          li do
+            a(href: ref.url) { ref.title }
+          end
+        end
+      end
+    end
+  end
+end
+
+# app/controllers/pages_controller.rb
+class PagesController < ApplicationController
+  def show
+    @page = Page.find(params[:id])
+
+    respond_to do |format|
+      format.html
+      format.md { render markdown: PageComponent.new(@page) }
+    end
+  end
+end
+~~~
+
+When someone visits `/pages/123.md`, Rails will render:
+
+~~~markdown
+# Getting Started with Ruby
+
+*Last updated: September 12, 2025*
+
+---
+
+## Introduction
+
+Ruby is a dynamic, object-oriented programming language...
+
+## Basic Syntax
+
+Here's how to define a method in Ruby:
+
+```ruby
+def greet(name)
+  puts "Hello, #{name}!"
+end
+```
+
+## References
+- [Official Ruby Documentation](https://ruby-doc.org)
+- [Ruby Style Guide](https://rubystyle.guide)
+~~~
+
+### Dynamic Content Generation
 
 ~~~ruby
 class ArticleContent < MDPhlex::MD
@@ -142,9 +232,9 @@ age = 30
 Learn more in the [documentation](https://docs.example.com).
 ~~~
 
-## Rendering MDPhlex inside Phlex::HTML
+## Rendering MDPhlex inside Phlex::HTML (and vice versa)
 
-MDPhlex components can be seamlessly integrated into your Phlex::HTML views:
+MDPhlex components are Phlex compatible. Integrate them into any Phlex::HTML views or show HTML or other wcomented in Markdown:
 
 ~~~ruby
 class ArticlePage < Phlex::HTML
@@ -191,9 +281,11 @@ end
 
 ## Why MDPhlex?
 
-- **Component-based**: Build reusable Markdown components
+*But markdown is just text!?* Yes, but have you ever tried to render clean markdown from a lot of conditional logic? MDPhlex tames the mess with a simple and familiar API.
+
+- **Component-based**: Build reusable Markdown with simple ruby classes
 - **Dynamic Markdown**: Generate markdown from dynamic data
-- **Composable**: Mix Phlex::HTML and MDPhlex components freely
+- **Composable**: Mix Phlex and MDPhlex components freely
 
 ## License
 

data/examples/html_in_markdown.rb

@@ -37,5 +37,14 @@ class HTMLInMarkdownExample < MDPhlex::MD
 end
 
 if __FILE__ == $0
-  puts HTMLInMarkdownExample.new.call
+  output = HTMLInMarkdownExample.new.call
+  puts output
+
+  File.write(
+    File.join(File.dirname(__FILE__), "html_in_markdown_output.md"),
+    output
+  )
+
+  puts "\n---"
+  puts "Output saved to examples/html_in_markdown_output.md"
 end

data/examples/html_in_markdown_output.md

@@ -0,0 +1,16 @@
+# HTML in Markdown
+Markdown allows inline HTML like <strong>this bold text</strong> and <em>this italic text</em>.
+
+You can use HTML entities directly: &copy; &amp; &lt;div&gt;
+
+## Complex HTML
+You can even include complex HTML structures:
+<div class="alert" style="border: 1px solid red;">
+  <h3>Warning!</h3>
+  <p>This is an alert box created with HTML.</p>
+</div>
+
+
+## Mixing Markdown and HTML
+You can mix **Markdown formatting** with <code>HTML tags</code> seamlessly.
+

data/lib/mdphlex/md.rb

@@ -40,6 +40,11 @@ module MDPhlex
       end
     end
 
+    # Render the markdown to a String using the Rails 8.1 standard to_markdown alias
+    def to_markdown
+      call
+    end
+
     def h1(content = nil, &)
       heading(1, content, &)
     end

data/lib/mdphlex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MDPhlex
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/quickdraw/mdphlex.test.rb

@@ -421,3 +421,21 @@ test "multiple register_block_elements" do
     </aside>
   MD
 end
+
+test "to_markdown works" do
+  example = Class.new(MDPhlex::MD) do
+    register_block_element :note
+
+    def view_template
+      note(type: "info") do
+        h3 "This is a note."
+      end
+    end
+  end
+
+  assert_equal example.new.to_markdown, <<~MD
+    <note type="info">
+    ### This is a note.
+    </note>
+  MD
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mdphlex
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Martin Emde
@@ -52,6 +52,7 @@ files:
 - examples/custom_elements.rb
 - examples/custom_elements_output.md
 - examples/html_in_markdown.rb
+- examples/html_in_markdown_output.md
 - examples/llm_prompt.rb
 - examples/llm_prompt_output.md
 - lib/mdphlex.rb