raindown 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab2295aa7f9468fa67aaf9d8192de859220c37cec922ef558607730a0544a86a
-  data.tar.gz: 0ede0a653f452c0a9f12f9a73c35dce3df85a12e9ff35350d741ae9c7c0e3522
+  metadata.gz: d0e77b47d4bdedcda5ace520aff8dabc470b3d49a9d7f2dac83b43d23d0928c2
+  data.tar.gz: 0e26371c232241abfcfbaec62a09eb89445299fdd5e4d67273a9c0839bb1982a
 SHA512:
-  metadata.gz: f72d0180ff9b4b310c25efa2872e59dc5d31da9dacff67d7d047737cab25e3b6647b2d74fb2a130c9354f0c434cf3a57e5a7c0750a54d762a47121901abcbb83
-  data.tar.gz: 3bcc85d7eb3b2055f374028f2bdcc3e561530ea36739e655d96c0b26f5038d7e83104b7201ee9b2654ecd8ea6e550c96d9733412bb2ff07a7f31f5858630c003
+  metadata.gz: 917089b01769a65e0b96d645613f182fdbd7212760823293ed87dd1581071751f53548bdc84d363c40e5a50d4c4941c10f6a409ded7dd2c5687708581dcd9213
+  data.tar.gz: 1ae3a21d68f7bb6fd7042e371cec3352eb7e1781855dcf3a5c92b80c1024a628481c2a3f159be9ee6fb1769592169640f5d767989aadf29bfbadba76ab610849

data/lib/elements.rb

@@ -6,6 +6,31 @@ module Raindown
   class Elements
     include Plugs
 
+    # Antlers' prop and slot directives, rendered as components in the template pass.
+    plug(:prop_component) do
+      plug(:lexeme) do
+        require 'lexemes/prop_lexeme'
+        Antlers::PropLexeme
+      end
+
+      plug(:node) do
+        require_relative 'nodes/component_nodes'
+        PropComponentNode
+      end
+    end
+
+    plug(:slot_component) do
+      plug(:lexeme) do
+        require 'lexemes/slot_lexeme'
+        Antlers::SlotLexeme
+      end
+
+      plug(:node) do
+        require_relative 'nodes/component_nodes'
+        SlotComponentNode
+      end
+    end
+
     plug(:endpoint) do
       plug(:lexeme) do
         require_relative 'lexemes/endpoint_lexeme'

data/lib/nodes/component_nodes.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'antlers/api'
+require 'nodes/html_node'
+require 'nodes/prop_node'
+require 'nodes/slot_node'
+require_relative '../raindown/fragments'
+
+module Raindown
+  # <{ Card name=p.name }>, rendered by Antlers where it is in the template, so its props see loop variables.
+  # Its HTML is kept as a fragment, so Commonmarker doesn't read it as Markdown.
+  class PropComponentNode < Antlers::PropNode
+    def render(**)
+      Fragments.add(super)
+    end
+  end
+
+  # <{ Card: }>...<{ :Card }>, whose slot is its own Markdown, rendered to HTML in its scope first.
+  #
+  # Markdown children -> rendered to a Markdown string -> Commonmarker -> HTML
+  #   -> wrapped as a single Antlers::HTMLNode (replaces @children for the super call)
+  #   -> Antlers::SlotNode#render's "without a template" branch -> slot: receives that HTML
+  #   -> Card#render(slot:, **props)
+  #
+  # This only reaches Card#render directly when Card has no class-level template (see SlotNode#render);
+  # otherwise Antlers renders Card's own template instead, with this HTML passed to it as the slot_node.
+  class SlotComponentNode < Antlers::SlotNode
+    def render(current_binding: nil, parent_binding: nil, slot_node: nil, metadata: {})
+      markdown = @children.map { |child| child.render(current_binding:, parent_binding:, slot_node:, metadata:) || '' }.join
+      children = @children
+      @children = [Antlers::HTMLNode.new(html: Raindown.commonmark(markdown))]
+
+      Fragments.add(super)
+    ensure
+      @children = children if children
+    end
+  end
+end

data/lib/nodes/endpoint_node.rb

@@ -2,10 +2,11 @@
 
 require 'antlers/api'
 require_relative '../raindown/directives'
+require_relative '../raindown/fragments'
 
 module Raindown
   # Holds an endpoint's curl snippet and response, which render as the code blocks they are,
-  # between Directives markers for its directive and end tag.
+  # between Directives markers for its directive and end tag, kept as a fragment.
   class EndpointNode < Antlers::BranchNode
     DEF_KEY = :endpoint_def
     END_KEY = :endpoint_end
@@ -17,7 +18,8 @@ module Raindown
     end
 
     def render(**)
-      "#{Directives.marker(@directive)}\n#{super.sub(/\A\n+/, '')}#{Directives.marker(':endpoint')}"
+      html = Raindown.commonmark(super)
+      Fragments.add("#{Directives.marker(@directive)}\n#{html}#{Directives.marker(':endpoint')}")
     end
 
     class << self

data/lib/raindown/fragments.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Raindown
+  # The HTML of components rendered while a document renders, kept out of its Markdown as placeholders
+  # so Commonmarker doesn't read it as Markdown, then filled in once the document is HTML.
+  module Fragments
+    PLACEHOLDER = /<!-- raindown:fragment (\d+) -->/
+
+    module_function
+
+    # Collects the fragments added while the block runs, like one document's render.
+    def collect
+      outer = Thread.current[:raindown_fragments]
+      Thread.current[:raindown_fragments] = []
+      yield
+    ensure
+      Thread.current[:raindown_fragments] = outer
+    end
+
+    def add(html)
+      list << html
+      "<!-- raindown:fragment #{list.length - 1} -->"
+    end
+
+    # Fills each placeholder, again and again, since a fragment can hold others, like a component in a slot.
+    def fill(html)
+      html = html.gsub(PLACEHOLDER) { list[::Regexp.last_match(1).to_i] } while html.match?(PLACEHOLDER)
+      html
+    end
+
+    def list
+      Thread.current[:raindown_fragments] ||= []
+    end
+  end
+end

data/lib/raindown/heading_ids.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Raindown
+  # Commonmarker gives each heading a unique id within what it renders, but a document's components render
+  # on their own, so two can have a heading with the same id. Later ones get -1, -2 and so on, like Commonmarker.
+  module HeadingIds
+    HEADING = %r{<h([1-6]) id="([^"]*)"(.*?)</h\1>}m
+
+    module_function
+
+    def unique(html)
+      seen = Hash.new(0)
+
+      html.gsub(HEADING) do
+        level, id, rest = ::Regexp.last_match.captures
+        count = seen[id]
+        seen[id] += 1
+        next ::Regexp.last_match(0) if count.zero?
+
+        unique_id = "#{id}-#{count}"
+        "<h#{level} id=\"#{unique_id}\"#{rest.gsub("href=\"##{id}\"", "href=\"##{unique_id}\"")}</h#{level}>"
+      end
+    end
+  end
+end

data/lib/raindown/page.rb

@@ -6,16 +6,21 @@ module Raindown
   class Page
     attr_reader :file_path, :metadata
 
-    def initialize(file_path:, metadata:)
+    def initialize(file_path:, metadata:, render_options: {})
       @file_path = file_path
       @metadata = metadata
+      @render_options = render_options
     end
 
     # Rendered when asked for, so a file that lists itself doesn't render forever.
+    # The front matter is rendered with it, so its variables work, and a Raindown file's bare directives too.
     def content
       @content ||= begin
-        markdown = FrontMatter.parse(File.read(file_path)).last.strip
-        markdown.empty? ? '' : Raindown.render(markdown:)
+        markdown = File.read(file_path, encoding: Encoding::UTF_8)
+
+        if FrontMatter.parse(markdown).last.strip.empty? then ''
+        else Raindown.render(markdown:, bare: BareDirectives.file?(file_path), **@render_options)
+        end
       end
     end
 

data/lib/raindown/pages.rb

@@ -31,8 +31,10 @@ module Raindown
       end
     end
 
-    def initialize(metadata:, root:)
+    # Render options, like hide_directives: true, are for rendering each listed file's content.
+    def initialize(metadata:, root:, render_options: {})
       @root = root
+      @render_options = render_options
       @file_paths = metadata.file_types.values_at(*EXTENSIONS).flatten.compact
       @metadata = {}
       @tags = {}
@@ -44,7 +46,7 @@ module Raindown
     # Without tags, every file.
     def list(**tags)
       file_paths = tags.empty? ? @file_paths : tagged(**tags)
-      file_paths.sort_by { |file_path| sort_key(file_path) }.map { |file_path| Page.new(file_path:, metadata: @metadata[file_path]) }
+      file_paths.sort_by { |file_path| sort_key(file_path) }.map { |file_path| listed_page(file_path) }
     end
 
     def tagged(**tags)
@@ -53,8 +55,12 @@ module Raindown
 
     private
 
+    def listed_page(file_path)
+      Page.new(file_path:, metadata: @metadata[file_path], render_options: @render_options)
+    end
+
     def process(file_path:)
-      metadata = implicit_metadata(file_path:).merge(FrontMatter.parse(File.read(file_path)).first)
+      metadata = implicit_metadata(file_path:).merge(FrontMatter.parse(File.read(file_path, encoding: Encoding::UTF_8)).first)
       @metadata[file_path] = metadata
       metadata.each { |type, tag| Array(tag).each { |item| tag(type:, tag: item, file_path:) } }
     end

data/lib/raindown/pre_renderer.rb

@@ -10,14 +10,12 @@ module Raindown
   # Renders the directives whose output is Markdown, before Commonmarker reads it: variables, loops, conditions and lists.
   # So a loop's items become one Markdown list or table, and a heading's id and its entry in a table of contents
   # come from its text, like "# Notes for {name}" becoming "Notes for Mark" with the id "notes-for-mark".
-  # Nodes like toc: and files: render before this, and directives whose output is HTML render in the HTML afterwards.
+  # Nodes like toc: and files: render before this. Components and endpoints render here too, as fragments of HTML
+  # that Raindown puts back once the document is HTML.
   module PreRenderer
     BLOCK_DIRECTIVES = %w[for if list].freeze
-    # A variable like <{ title }> or a for, if or list directive, which render here.
-    DIRECTIVE = /<\{\s*(?:(?:#{BLOCK_DIRECTIVES.join('|')}):[^}]*|:(?:#{BLOCK_DIRECTIVES.join('|')})|[@\w.]+)\s*\}>/
     # A for, if or list directive alone on its line, which leaves no line behind, so a loop's list items stay together.
     BLOCK_LINE = /^[ \t]*(<\{\s*:?(?:#{BLOCK_DIRECTIVES.join('|')})\b[^}]*\}>)[ \t]*\n/
-    HIDDEN = /\u{E002}(\d+)\u{E003}/
 
     module_function
 
@@ -31,24 +29,17 @@ module Raindown
     end
 
     def render_body(body, variables, metadata)
-      hidden = []
-      # Other directives are hidden, but not the Markdown between their tags.
-      template = body.gsub(/<\{.*?\}>|<\{/) { |directive| directive.match?(/\A#{DIRECTIVE}\z/) ? directive : hide(directive, hidden) }
-      template = template.gsub(BLOCK_LINE, '\1')
+      template = body.gsub(BLOCK_LINE, '\1')
       return body unless template.include?('{')
 
       # Antlers strips the whitespace around a template, which can be Markdown, like an indented code block.
       leading = template[/\A\s*/]
       trailing = template[/\s*\z/]
-      ast = Antlers.ast(template:, elements: Antlers::Elements[:html, :var, :if, :for] + Elements[:list])
-      rendered = Antlers.render(ast:, current_binding: variables.binding, metadata:)
+      # Components and endpoints render here too, where loop variables are in scope, and keep their HTML as fragments.
+      elements = Antlers::Elements[:html, :var, :if, :for] + Elements[:list, :endpoint, :prop_component, :slot_component]
+      rendered = Antlers.render(ast: Antlers.ast(template:, elements:), current_binding: variables.binding, metadata:)
 
-      "#{leading}#{rendered}#{trailing}".gsub(HIDDEN) { hidden[::Regexp.last_match(1).to_i] }
-    end
-
-    def hide(directive, hidden)
-      hidden << directive
-      "\u{E002}#{hidden.length - 1}\u{E003}"
+      "#{leading}#{rendered}#{trailing}"
     end
   end
 end

data/lib/raindown/rewriter.rb

@@ -21,7 +21,7 @@ module Raindown
 
     # Returns true when the file changed.
     def update(path:, bare: false, execute: false, metadata: NoMetadata)
-      content = File.read(path)
+      content = File.read(path, encoding: Encoding::UTF_8)
       rewritten = rewrite(content:, path:, bare:, execute:, metadata:)
       return false if rewritten == content
 

data/lib/raindown/toc.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
 require 'erb'
+require 'nokogiri'
+
 require_relative 'node'
 
 module Raindown
   # The node behind toc: and :toc, a table of contents of the document's headings.
   # A project can replace it with its own TOC node in .raindown, like "class TOC < Raindown::TOC".
   class TOC < Node
-    def replace(document:, metadata: NoMetadata, bare: false)
-      headings = Raindown.headings(markdown: document, metadata:, bare:)
+    def replace(document:, metadata: nil, bare: false)
+      headings = headings(markdown: document, metadata:, bare:)
       return '' if headings.empty?
 
       min_level = headings.map { |heading| heading[:level] }.min
@@ -18,8 +20,9 @@ module Raindown
       end.join("\n")
     end
 
-    def render(document:, metadata: NoMetadata, bare: false)
-      items = Raindown.headings(markdown: document, metadata:, bare:).map do |heading|
+    # With the document's final HTML, the headings include ones its components render.
+    def render(document:, html: nil, metadata: nil, bare: false)
+      items = headings(markdown: document, html:, metadata:, bare:).map do |heading|
         "<li class='h#{heading[:level]}'><a href='##{heading[:id]}'>#{ERB::Util.html_escape(heading[:text])}</a></li>"
       end
 
@@ -34,5 +37,14 @@ module Raindown
         </div>
       HTML
     end
+
+    # The document's headings, from its final HTML, or else by rendering it with its components.
+    def headings(markdown:, html: nil, metadata: nil, bare: false)
+      html ||= Fragments.collect { Raindown.assembled(markdown:, metadata: metadata || NoMetadata, bare:) }
+
+      Nokogiri::HTML(html).css(HEADINGS).map do |heading|
+        { level: heading.name[1].to_i, text: heading.text.strip, id: heading['id'] }
+      end
+    end
   end
 end

data/lib/raindown.rb

@@ -3,13 +3,15 @@
 require 'commonmarker'
 require 'antlers'
 require 'antlers/api'
-require 'nokogiri'
+
 require_relative 'elements'
 require_relative 'raindown/bare_directives'
 require_relative 'raindown/code'
 require_relative 'raindown/config'
 require_relative 'raindown/directives'
+require_relative 'raindown/fragments'
 require_relative 'raindown/front_matter'
+require_relative 'raindown/heading_ids'
 require_relative 'raindown/node_blocks'
 require_relative 'raindown/pages'
 require_relative 'raindown/pre_renderer'
@@ -36,40 +38,36 @@ module Raindown
 
   module_function
 
-  def headings(markdown:, metadata: NoMetadata, bare: false)
-    html = html(markdown:, variables: variables(markdown:), metadata:, bare:)
-
-    Nokogiri::HTML(html).css(HEADINGS).map do |heading|
-      { level: heading.name[1].to_i, text: heading.text.strip, id: heading['id'] }
-    end
-  end
-
   # Directives show in bold, unless the file's project hides them in .raindown/config.yml.
   def render_file(path:, metadata: NoMetadata, bare: false, hide_directives: Config.for(path)[:hide_directives])
-    render(markdown: File.read(path), metadata:, bare: bare || BareDirectives.file?(path), hide_directives:)
+    render(markdown: File.read(path, encoding: Encoding::UTF_8), metadata:, bare: bare || BareDirectives.file?(path), hide_directives:)
   end
 
   # Front matter keys are variables, like {title} or <{ title }>.
-  # Directives like a node's show in bold, or as HTML comments with hide_directives.
+  # Directives like "toc:" export to HTML as bold or comments depending on hide_directives config.
   def render(markdown:, metadata: NoMetadata, bare: false, hide_directives: false)
-    variables = variables(markdown:)
-    template = html(markdown:, variables:, metadata:, bare:)
-    context = { document: markdown, metadata:, bare: }
-
-    if template.include?('<{')
-      # Directives whose output is HTML. The rest rendered before Commonmarker, in PreRenderer.
-      ast = Antlers.ast(template:, elements: Antlers::Elements[:html, :prop, :slot] + Elements[:endpoint])
-      template = "#{Antlers.render(ast:, current_binding: variables.binding, metadata:).chomp}\n"
+    Fragments.collect do
+      # Components' HTML goes back in, then their headings get unique ids, before nodes like the TOC see it.
+      html = assembled(markdown:, metadata:, bare:)
+      html = Nodes.render_placeholders(html, document: markdown, metadata:, bare:, html:)
+
+      Directives.render("#{html.chomp}\n", hide: hide_directives)
     end
+  end
 
-    # Nodes and directives render last, so their HTML isn't read as Markdown or directives.
-    Directives.render(Nodes.render_placeholders(template, **context), hide: hide_directives)
+  # The document's HTML with its components' HTML put back, and unique heading ids.
+  def assembled(markdown:, metadata: NoMetadata, bare: false)
+    HeadingIds.unique(Fragments.fill(html(markdown:, variables: variables(markdown:), metadata:, bare:)))
   end
 
-  # The HTML from Commonmarker, after PreRenderer and before the directives whose output is HTML.
-  def html(markdown:, variables:, metadata:, bare:)
+  # The document's HTML from Commonmarker, after nodes and the template pass, with components as fragments.
+  def html(markdown:, variables:, metadata: NoMetadata, bare: false)
     markdown = NodeBlocks.to_rendered(markdown.dup.force_encoding('UTF-8'), metadata:, bare:)
-    markdown = PreRenderer.render(markdown, variables:, metadata:, bare:)
+    commonmark(PreRenderer.render(markdown, variables:, metadata:, bare:))
+  end
+
+  # Markdown to HTML, like a document's or a component's slot.
+  def commonmark(markdown)
     doc = Commonmarker.parse(hide_directives(markdown:), options: MARKDOWN_OPTIONS)
     preserve_code(doc:)
 

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Raindown
-  VERSION = '0.2.0'
+  VERSION = '0.2.2'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: antlers
@@ -149,6 +149,7 @@ files:
 - lib/elements.rb
 - lib/lexemes/endpoint_lexeme.rb
 - lib/lexemes/list_lexeme.rb
+- lib/nodes/component_nodes.rb
 - lib/nodes/endpoint_node.rb
 - lib/nodes/list_node.rb
 - lib/raindown.rb
@@ -161,7 +162,9 @@ files:
 - lib/raindown/endpoint/curl.rb
 - lib/raindown/endpoint/endpoint_runner.rb
 - lib/raindown/files.rb
+- lib/raindown/fragments.rb
 - lib/raindown/front_matter.rb
+- lib/raindown/heading_ids.rb
 - lib/raindown/node.rb
 - lib/raindown/node_blocks.rb
 - lib/raindown/node_injector.rb