raindown 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f795c35070ab8ae4f6b40e5a32595ab9ba6099b99f42aada8d0faafe2f56121d
-  data.tar.gz: a01426b3aab916e21b0e68f66fddd7f6b55d7e9c34ceb9665118a60b3ceae4b5
+  metadata.gz: be9fc3af39c4d6f20b00b691a14582626448ac903a01aa129a2f33911553a76f
+  data.tar.gz: d0bf1eea7f8996adb29d97eeeaeda1c38ad16739df7724704ab1402b1bd2c723
 SHA512:
-  metadata.gz: 052231532f48cc3a575388ebe95fa62b70bc3eba2121742142071c2ab256ced437de1f4c80f2e439599d579c2b5eea2d793b7cb05439601523bc72ff9c252dd6
-  data.tar.gz: 98ff7b646f8e380817bbf69efc06a0bf67b4945a233349c9702d3140458bb27e387ecd010498c80dbfa4a9d2e64872b4f7af75bcd12b28b992e8b82ac66f56c9
+  metadata.gz: b6b4305e373de95235142d2e030849aac517d724232194bd68eb2c16cef7c81dd9594ccc8a80b2cd7d8042af045818773d1059c8d30caef634f0722ed35cd6d4
+  data.tar.gz: 593a219070643268ddd2c52a25aa34d0fe76d62f1074c2a3a263dddf72407d4b03c3a13113100e684ee19c6168a15525e059bf26c118ea6bca680c7112c3ee62

data/lib/elements.rb

@@ -6,28 +6,27 @@ module Raindown
   class Elements
     include Plugs
 
-    # Antlers' prop and slot directives, rendered as components in the template pass.
-    plug(:prop_component) do
+    # Write-in nodes, in <{ }>, like <{ Card }>, <{ :toc }> or <{ Card: }>...<{ :Card }>, rendered in the template pass.
+    plug(:write_in) do
       plug(:lexeme) do
-        require 'lexemes/prop_lexeme'
-        Antlers::PropLexeme
+        require_relative 'lexemes/node_lexeme'
+        NodeLexeme
       end
 
+      # A list: block loops over its files, so it comes before other nodes' blocks.
       plug(:node) do
-        require_relative 'nodes/component_nodes'
-        PropComponentNode
+        require_relative 'nodes/list_node'
+        ListNode
       end
-    end
 
-    plug(:slot_component) do
-      plug(:lexeme) do
-        require 'lexemes/slot_lexeme'
-        Antlers::SlotLexeme
+      plug(:node) do
+        require_relative 'nodes/write_in_node'
+        WriteInNode
       end
 
       plug(:node) do
-        require_relative 'nodes/component_nodes'
-        SlotComponentNode
+        require_relative 'nodes/write_in_node'
+        SoloWriteInNode
       end
     end
 
@@ -42,17 +41,5 @@ module Raindown
         EndpointNode
       end
     end
-
-    plug(:list) do
-      plug(:lexeme) do
-        require_relative 'lexemes/list_lexeme'
-        ListLexeme
-      end
-
-      plug(:node) do
-        require_relative 'nodes/list_node'
-        ListNode
-      end
-    end
   end
 end

data/lib/lexemes/node_lexeme.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'antlers/api'
+require_relative '../raindown/node_blocks'
+
+module Raindown
+  # A write-in node, in Antlers' delimiters, read with its props as Raindown reads them, like
+  # <{ :list folder: 'notes' }>. It opens a block with <{ Name: }>, and <{ :Name }> ends one, or else it's self-closing,
+  # as is <{ Card title='Hi' }>. Template directives, like if: and for:, aren't nodes, so they're left to their lexemes.
+  module NodeLexeme
+    include Antlers::Lexeme
+
+    module_function
+
+    DIRECTIVE = /\A(:)?([A-Za-z]\w*(?:::[A-Z]\w*)*)(:)?(?:\s+(.*))?\z/m
+
+    # A name with a colon is a node, like <{ :toc }> or <{ :app_name }>, while {:app_name} is a translation. One without
+    # is a node when it's capitalized, so <{ title }> is still a variable. The lexer gives no name to a directive that
+    # starts with another lexeme's keyword, like <{ if: draft }> or <{ :list }>, which it leaves to that lexeme.
+    def match?(segment:, name: nil, **)
+      _, close, node_name, open = segment.to_s.match(DIRECTIVE).to_a
+      return false if name.nil? || node_name.nil? || (close && open)
+      return true if close || open
+
+      node_name.match?(/\A[A-Z]/)
+    end
+
+    # <{ :Name }> ends a block of the name, or else is self-closing, while <{ Name }> is always self-closing.
+    def lexeme(segment:, **)
+      _, close, name, open, args = segment.match(DIRECTIVE).to_a
+      return { node_def: name, args: args.to_s } if open
+      return { node_end: name, args: args.to_s } if close
+
+      { node_solo: name, args: args.to_s }
+    end
+  end
+end

data/lib/nodes/list_node.rb

@@ -1,46 +1,43 @@
 # frozen_string_literal: true
 
 require 'antlers/api'
+require_relative '../raindown/context'
+require_relative '../raindown/node_blocks'
+require_relative '../raindown/nodes'
+require_relative 'write_in_node'
 
 module Raindown
+  # <{ list: page folder: 'notes' }> ... <{ :list }>, which renders its template for each file the list: node lists,
+  # with the file as page. Without a block, <{ :list folder: 'notes' }> renders the node's links, as a WriteInNode.
   class ListNode < Antlers::BranchNode
-    include Antlers::Props
-    include Antlers::Variables
+    DEF_KEY = :node_def
+    END_KEY = :node_end
 
-    DEF_KEY = :list_def
-    END_KEY = :list_end
+    def initialize(name:, args:)
+      super(name:)
 
-    def initialize(value:, folder:, props: [], children: [])
-      super(name: :toc, props:, children:)
-
-      @value = value.delete("'").delete('"')
-      @folder = folder.delete("'").delete('"')
+      @variable, @tags = args.split(/\s+/, 2)
     end
 
-    def render(current_binding: nil, parent_binding: nil, slot_node: nil, metadata: {})
-      output = ''
-
-      list = metadata.list(folder: @folder)
-
-      list.each do |value|
-        # TODO: Parallelize by creating new bindings and ensuring children have any args they need via RenderEvent.
-        current_binding.local_variable_set(@value, value)
-
-        @children.each do |child|
-          output += child.render(current_binding:, parent_binding:, slot_node:, metadata:) || ''
-        end
-      end
+    def render(current_binding: nil, context: Context.new, **)
+      tags = NodeBlocks.props(@tags.to_s, BoundVariables.new(current_binding))
+      Nodes.instance(Nodes.node_class('list'), tags).files(metadata: context.metadata).map do |file|
+        current_binding.local_variable_set(@variable, file)
+        super
+      end.join
+    end
 
-      output
+    def end_name
+      'list'
     end
 
     class << self
       def match?(segment:)
-        segment[DEF_KEY]
+        segment[DEF_KEY] == 'list'
       end
 
       def build(segment:, **)
-        new(value: segment[:list_def], folder: segment[:folder])
+        new(name: :list, args: segment[:args])
       end
     end
   end

data/lib/nodes/write_in_node.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'antlers/api'
+require 'nodes/html_node'
+require_relative '../raindown/context'
+require_relative '../raindown/fragments'
+require_relative '../raindown/node_blocks'
+require_relative '../raindown/nodes'
+
+module Raindown
+  # A write-in node, in <{ }>, which Antlers renders where it is in the template, so its props see loop variables, like
+  # <{ Card name=p.name }> in a for: loop. It only renders, with its render, never its rewrite, and the Markdown
+  # between its tags, <{ Card: }> to <{ :Card }>, is its slot, rendered to HTML in its scope first.
+  # One with a class template, like Raindeer's .rbx components, renders its template, with that HTML as its slot.
+  class WriteInNode < Antlers::BranchNode
+    DEF_KEY = :node_def
+    END_KEY = :node_end
+
+    def initialize(name:, args: '', **)
+      super(name:)
+
+      @args = args
+    end
+
+    def render(current_binding: nil, context: Context.new, **)
+      slot = Raindown.commonmark(super) unless @children.empty?
+      props, args = NodeBlocks.args(@args, BoundVariables.new(current_binding))
+      node = Nodes.instance(node_class, props, args || [])
+      return Fragments.add(template_html(node, props, slot.to_s, current_binding)) if Nodes.template?(node.class)
+
+      Nodes.rendered(node, context, slot: slot.to_s)
+    end
+
+    def end_name
+      @name
+    end
+
+    private
+
+    # A render-only component, like Card, isn't a node Nodes finds, as it has no rewrite, so it's any class of the name.
+    def node_class
+      klass = Nodes.node_class(@name)
+      return klass if klass
+      raise NameError, "No node is named #{@name}, for <{ :#{@name} }>" unless @name.match?(/\A[A-Z]/)
+
+      Object.const_get(@name)
+    end
+
+    # The node's class template, whose slot is the HTML in place of its children.
+    def template_html(node, props, slot, parent_binding)
+      children = @children
+      @children = [Antlers::HTMLNode.new(html: slot)]
+      node.render_template(parent_binding:, slot_node: self, props:)
+    ensure
+      @children = children
+    end
+
+    class << self
+      def match?(segment:)
+        segment[DEF_KEY]
+      end
+
+      def build(segment:, **)
+        new(name: segment[DEF_KEY], args: segment[:args])
+      end
+    end
+  end
+
+  # <{ Card }>, or <{ :Card }> when it doesn't end a block, which a lowercase name needs, like <{ :toc }>.
+  class SoloWriteInNode < WriteInNode
+    END_KEY = nil
+
+    def self.match?(segment:)
+      segment[:node_solo] || segment[:node_end]
+    end
+
+    def self.build(segment:, **)
+      new(name: segment[:node_solo] || segment[:node_end], args: segment[:args])
+    end
+  end
+
+  # The variables where Antlers renders a node, like a loop's, and then the front matter's, as its props read them.
+  class BoundVariables < BasicObject
+    def initialize(binding)
+      @binding = binding
+    end
+
+    # A name that can't be a local, like a-b, is only looked for in the front matter.
+    def send(name)
+      return @binding.local_variable_get(name) if name.match?(/\A[a-z_]\w*\z/) && @binding.local_variable_defined?(name)
+
+      @binding.receiver.send(name)
+    end
+  end
+end

data/lib/raindown/bare_directives.rb

@@ -8,7 +8,7 @@ require_relative 'front_matter'
 module Raindown
   # Raindown files (.rd/.raindown) can write a content directive, which writes its output back, bare on its own line,
   # like endpoint: or toc:, which shows in bold in the HTML. Markdown files opt in with "raindown: true" in their front
-  # matter, or with the --bare flag. Nodes like toc: and files: are handled by NodeBlocks, before the rest.
+  # matter, or with the --bare flag. Nodes like toc: and list: are handled by NodeBlocks, before the rest.
   # Template directives, like if: and for:, are always in Antlers' delimiters, so they're never bare.
   #
   # A bare schema: shows in bold, with its fields in a code block below it.

data/lib/raindown/chart/chart.rb

@@ -32,7 +32,7 @@ module Raindown
     end
 
     # The data is read every time, so the chart follows changes to its file.
-    def replace(metadata: NoMetadata)
+    def rewrite(metadata: NoMetadata)
       points = points(metadata:)
       return '' if points.empty?
 

data/lib/raindown/context.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'front_matter'
+require_relative 'variables'
+
+module Raindown
+  # The document being rendered, its metadata, like a site's pages, and whether its directives can be bare: the keywords
+  # a node's rewrite and render can take. Antlers passes it down to Raindown's own Antlers nodes.
+  Context = Data.define(:document, :metadata, :bare) do
+    def initialize(document: '', metadata: NoMetadata, bare: false)
+      super
+    end
+
+    # The document's front matter, as variables, like {title}.
+    def variables
+      Variables.new(FrontMatter.parse(document).first)
+    end
+  end
+end

data/lib/raindown/directives.rb

@@ -19,7 +19,7 @@ module Raindown
 
     module_function
 
-    # A directive's line without its delimiters, like "files: folder: 'notes'" for <!-- files: folder: 'notes' -->.
+    # A directive's line without its delimiters, like "list: folder: 'notes'" for <!-- list: folder: 'notes' -->.
     def text(line)
       line = line.strip
       [COMMENT, DELIMITERS].each do |open, close|

data/lib/raindown/fragments.rb

@@ -18,8 +18,13 @@ module Raindown
     end
 
     def add(html)
+      "<!-- raindown:fragment #{store(html)} -->"
+    end
+
+    # Keeps the HTML for this render, returning its index in the list.
+    def store(html)
       list << html
-      "<!-- raindown:fragment #{list.length - 1} -->"
+      list.length - 1
     end
 
     # Fills each placeholder, again and again, since a fragment can hold others, like a component in a slot.

data/lib/raindown/js/host.mjs

@@ -16,13 +16,13 @@ const classes = {}
 const nodes = {}
 
 const requests = {
-  // Every exported class with replace is a node, named by its export, or by its class for a default export.
+  // Every exported class with rewrite is a node, named by its export, or by its class for a default export.
   async load({ folder }) {
     for (const file of readdirSync(folder).filter((file) => /\.m?js$/.test(file))) {
       const exports = await import(pathToFileURL(join(folder, file)).href)
 
       for (const [name, value] of Object.entries(exports)) {
-        if (typeof value?.prototype?.replace === 'function') classes[name === 'default' ? value.name : name] = value
+        if (typeof value?.prototype?.rewrite === 'function') classes[name === 'default' ? value.name : name] = value
       }
     }
 

data/lib/raindown/js/js_nodes.rb

@@ -6,7 +6,7 @@ require 'open3'
 require_relative '../node'
 
 module Raindown
-  # JavaScript Components, the .js and .mjs files in a project's .raindown folder, which export classes with replace and
+  # JavaScript Components, the .js and .mjs files in a project's .raindown folder, which export classes with rewrite and
   # optionally render, like Ruby nodes. They run in a NodeJS process of Raindown's own, started when a folder has them,
   # so only projects with JavaScript Components need NodeJS.
   module JSNodes
@@ -57,7 +57,7 @@ module Raindown
     end
   end
 
-  # A JavaScript Component, made in the NodeJS process with its props, where its replace and render are sent.
+  # A JavaScript Component, made in the NodeJS process with its props, where its rewrite and render are sent.
   class JSNode < Node
     # A class for each JavaScript Component, which renders its own HTML when the component has render.
     def self.for(name:, render:)
@@ -72,8 +72,8 @@ module Raindown
       JSNodes.host.request(op: 'new', id: object_id, name: self.class.name, args:, props:)
     end
 
-    def replace(**context)
-      js_output(:replace, context)
+    def rewrite(**context)
+      js_output(:rewrite, context)
     end
 
     private

data/lib/raindown/list.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'node'
+
+module Raindown
+  # The node behind list:, the files the metadata has for its props, like list: folder: 'notes'. Bare or in comments it
+  # writes a link to each, and in <{ list: page folder: 'notes' }> ... <{ :list }> it renders its template for each,
+  # with the file as page, the name before its props, which is its argument. A project can change how files are listed
+  # with its own List node in .raindown, like "class List < Raindown::List".
+  class List < Node
+    # Order is the metadata to sort by, like order: :created_at, rather than a tag to list by.
+    def initialize(_name = nil, order: nil, **tags)
+      @order = order
+      @tags = tags
+    end
+
+    # Each file has its front matter, its path and its content. Sorted by an order, files without it come last, and ones
+    # with the same value stay in the order they're listed.
+    def files(metadata: NoMetadata)
+      files = metadata.list(**@tags)
+      return files unless @order
+
+      sorted, unsorted = files.partition { it[@order] }
+      sorted.sort_by.with_index { |file, index| [file[@order], index] } + unsorted
+    end
+
+    def rewrite(metadata: NoMetadata)
+      files(metadata:).map { |file| "- [#{file.title || file.path}](#{file.path})" }.join("\n")
+    end
+  end
+end

data/lib/raindown/markdown_nodes.rb

@@ -57,10 +57,11 @@ module Raindown
 
     # Braces that the template pass hid, in its code or its props' values, are written back as braces.
     # The template pass loads here, as it loads nodes itself.
-    def replace(metadata: NoMetadata, bare: false)
+    def rewrite(document: '', metadata: NoMetadata, bare: false)
       require_relative 'pre_renderer'
       defaults, template = FrontMatter.parse(File.read(self.class.path))
-      markdown = PreRenderer.render(template, variables: Variables.new(defaults.merge(@props)), metadata:, bare:)
+      context = Context.new(document:, metadata:, bare:)
+      markdown = PreRenderer.render(template, variables: Variables.new(defaults.merge(@props)), context:)
       Variables.unwrap(markdown.sub(/\A(?:[ \t]*\n)+/, '').rstrip)
     end
   end

data/lib/raindown/node.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
 module Raindown
-  # The base class of Raindown's own nodes, like TOC and Files.
+  # The base class of Raindown's own nodes, like TOC and List.
   # A project's nodes are LowNodes, or subclasses of these.
-  class Node; end
+  class Node
+    # Write-in, in <{ }>, a node renders its Markdown as HTML. One whose rewrite takes written:, what it wrote last
+    # time, can write edits back to its source, like Table to its file, so it needs its own render, which never does.
+    def render(**context)
+      raise Nodes::NoRender, "#{self.class.name} writes edits back, so it needs a render" if Nodes.takes?(self, :rewrite, :written)
+
+      Raindown.commonmark(Nodes.call(self, :rewrite, **context).to_s)
+    end
+  end
 end

data/lib/raindown/node_blocks.rb

@@ -16,9 +16,10 @@ module Raindown
   #   - **1.2.0** Bare directives
   #
   #   <!-- :Changelog -->
-  # In Antlers' delimiters, <{ Changelog: }> to <{ :Changelog }>, or a self-closing <{ :Changelog }> or bare
-  # :Changelog, it renders the node without writing it. toc: and files: are Raindown's own nodes. A name only starts
-  # a block when it's a loaded node, so other text like "Note:" is left alone.
+  # A bare :Changelog is write-in: it only renders, with its render, never its rewrite. In Antlers' delimiters, like
+  # <{ Changelog }>, it's write-in too, and the template pass renders it, as a WriteInNode, so it's only found here
+  # for a document's outline. toc: and list: are Raindown's own nodes. A name only starts a block when it's a loaded
+  # node, so other text like "Note:" is left alone.
   module NodeBlocks
     class MissingEndTag < StandardError; end
     class BrokenText < StandardError; end
@@ -27,7 +28,8 @@ module Raindown
     OPEN = /\A( {0,3})<\{\s*(#{NAME}):(?:\s+(.*?))?\s*\}>[ \t]*$/
     COMMENT_OPEN = /\A( {0,3})<!--\s*(#{NAME}):(?:\s+(.*?))?\s*-->[ \t]*$/
     BARE_OPEN = /\A( {0,3})(#{NAME}):(?:[ \t]+(.*?))?[ \t]*$/
-    SELF_CLOSING = /\A( {0,3})<\{\s*:(#{NAME})(?:\s+(.*?))?\s*\}>[ \t]*$/
+    # <{ Card }>, or <{ :Card }>, which a lowercase name like toc needs, as <{ toc }> is a variable.
+    SELF_CLOSING = /\A( {0,3})<\{\s*(?::|(?=[A-Z]))(#{NAME})(?:\s+(.*?))?\s*\}>[ \t]*$/
     BARE_SELF_CLOSING = /\A( {0,3}):(#{NAME})(?:[ \t]+(.*?))?[ \t]*$/
     # Unquoted text after name:, like YAML's, runs up to the next prop, so title: Hello world limit: 3 has two.
     UNQUOTED = /.+?(?=[ \t]+\w+(?:=|:[ \t])|[ \t]*\z)/
@@ -40,12 +42,15 @@ module Raindown
     module_function
 
     # Each block outside code and front matter as { open:, close:, last:, writes:, node: }, where close is nil for a
-    # bare block, and writes is whether its output's written into the file. A self-closing node is a block of one line
-    # with self_closing: true.
+    # bare block, and writes is whether its output's written into the file. A self-closing node is a block of one line.
     def find(lines, front_matter: {}, bare: false)
+      with_nodes(spans(lines, bare:), front_matter)
+    end
+
+    def with_nodes(spans, front_matter)
       variables = Variables.new(front_matter)
 
-      spans(lines, bare:).map do |span|
+      spans.map do |span|
         node = Nodes.instance(span[:class], *args(span[:args], variables, antlers: span[:antlers]))
         span.except(:name, :class, :args, :antlers).merge(node:)
       end
@@ -71,28 +76,29 @@ module Raindown
       spans
     end
 
-    # Swaps each block for its node's HTML, through a placeholder, or for its Markdown when it has no HTML of its own.
-    # The directive and end tag become Directives markers, which also keep the node's output from joining
-    # the Markdown around it, like two lists becoming one.
-    def to_rendered(markdown, metadata: NoMetadata, bare: false)
-      lines = markdown.lines
-      find(lines, front_matter: FrontMatter.parse(markdown).first, bare:).reverse_each do |block|
-        lines[block[:open]..block[:last]] = rendered_lines(lines, block, markdown:, metadata:, bare:)
+    # Swaps each bare block or block in comments for its node's Markdown, or its HTML when it has its own, or only renders,
+    # as a fragment or a placeholder. The directive and end tag become Directives markers, which also keep the node's
+    # output from joining the Markdown around it, like two lists becoming one. Ones in <{ }> are left to Antlers.
+    def to_rendered(context)
+      lines = context.document.dup.force_encoding('UTF-8').lines
+      spans = spans(lines, bare: context.bare).reject { it[:antlers] }
+      with_nodes(spans, FrontMatter.parse(context.document).first).reverse_each do |block|
+        lines[block[:open]..block[:last]] = rendered_lines(lines, block, context)
       end
       lines.join
     end
 
-    def rendered_lines(lines, block, markdown:, metadata:, bare:)
-      output = node_markdown(block[:node], markdown:, metadata:, bare:).chomp
+    def rendered_lines(lines, block, context)
+      output = node_markdown(block, context).chomp
       close = marker(lines[block[:close]]) if block[:close]
 
       [marker(lines[block[:open]]), *("#{output}\n".lines unless output.empty?), *close]
     end
 
-    def node_markdown(node, markdown:, metadata:, bare:)
-      return Nodes.placeholder(node) if Nodes.html?(node)
+    def node_markdown(block, context)
+      return Nodes.rendered(block[:node], context) if !block[:writes] || Nodes.html?(block[:node])
 
-      Nodes.call(node, :replace, document: markdown, metadata:, bare:).to_s
+      Nodes.call(block[:node], :rewrite, **context.to_h).to_s
     end
 
     def marker(line)
@@ -109,7 +115,7 @@ module Raindown
         end_tag(lines, index, found[2], comment: pattern == :comment_open)
           .then { |close| { open: index, close:, last: close, writes: pattern == :comment_open, **span } }
       when :bare_open then { **bare_block(lines, index), writes: true, **span }
-      else { open: index, close: nil, last: index, writes: false, self_closing: true, **span }
+      else { open: index, close: nil, last: index, writes: false, **span }
       end
     end
 
@@ -156,7 +162,7 @@ module Raindown
     end
 
     # A value, like 'text', 3, true, nil or :draft, or else a variable. In Antlers' delimiters a word is a variable, like
-    # author.name, while bare or in a comment, which read like Markdown, it's text, like notes in files: folder: notes,
+    # author.name, while bare or in a comment, which read like Markdown, it's text, like notes in list: folder: notes,
     # and only one in braces is a variable, like {author.name}.
     def value(value, variables, antlers: true)
       Lowkey::ValueParser.parse(value) do

data/lib/raindown/node_injector.rb

@@ -36,7 +36,7 @@ module Raindown
 
     def block_lines(lines, block)
       context = { document: @content, metadata: @metadata, bare: @bare, written: written_lines(lines, block) }
-      markdown = Nodes.call(block[:node], :replace, **context).to_s.chomp
+      markdown = Nodes.call(block[:node], :rewrite, **context).to_s.chomp
       written = markdown.empty? ? [] : "#{markdown}\n".lines
       return [line(lines[block[:open]]), *bare(written, block)] unless block[:close]
 

data/lib/raindown/nodes.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 require_relative 'chart/chart'
-require_relative 'files'
+require_relative 'fragments'
 require_relative 'js/js_nodes'
+require_relative 'list'
 require_relative 'markdown_nodes'
 require_relative 'node'
 require_relative 'stat'
@@ -13,15 +14,20 @@ module Raindown
   # Nodes are LowNodes that a node block writes into the Markdown and renders into the HTML.
   # A project keeps them in a .raindown folder, which is loaded with Dirload, beside its JavaScript and Markdown
   # Components, if any.
-  # A node writes Markdown with #replace, and HTML with #render if it has one. Either can take the keywords
-  # document: (the Markdown being rendered), metadata:, bare: and written: (the lines it wrote last time), and gets the
-  # ones it asks for.
+  # Bare or in comments, a node writes back: its Markdown, from #rewrite, is written into the file, and its HTML is from
+  # #render if it has one. In <{ }> it's write-in: it only renders, with #render, which takes the Markdown between its
+  # tags as slot:, in HTML. Either can take the keywords document: (the Markdown being rendered), metadata:, bare: and
+  # written: (the lines it wrote last time), and gets the ones it asks for.
   module Nodes
+    # A write-in node that has no render.
+    class NoRender < StandardError; end
+
     FOLDER = '.raindown'
-    # Lowercase directives for Raindown's own nodes. A project's own TOC, Files, Chart or Table node replaces Raindown's.
-    BUILT_INS = { 'toc' => 'TOC', 'files' => 'Files', 'chart' => 'Chart', 'table' => 'Table' }.freeze
-    # A placeholder for a node's HTML, which stays as it is through Commonmarker and Antlers.
-    PLACEHOLDER = /<!-- raindown:node (\d+) -->/
+    # Lowercase directives for Raindown's own nodes. A project's own TOC, List, Chart or Table node replaces Raindown's.
+    BUILT_INS = { 'toc' => 'TOC', 'list' => 'List', 'chart' => 'Chart', 'table' => 'Table' }.freeze
+    # A placeholder for a node's HTML, which stays as it is through Commonmarker and Antlers, with its slot's HTML, as a
+    # fragment, when it has one.
+    PLACEHOLDER = /<!-- raindown:node (\d+)(?: slot (\d+))? -->/
 
     module_function
 
@@ -63,21 +69,21 @@ module Raindown
 
     # A Ruby node of the name, or else a JavaScript one, or else a Markdown one.
     def loaded_class(name)
-      klass = Object.const_get(name) if Object.const_defined?(name)
+      klass = Object.const_get(name) if name.match?(/\A[A-Z]/) && Object.const_defined?(name)
       return klass if node?(klass)
 
       JSNodes.node_class(name) || MarkdownNodes.node_class(name)
     end
 
     # A LowNode, or one of Raindown's own nodes, that writes Markdown. In an app, LowNodes are also routes and pages,
-    # which don't have replace, so text like "Note:" only starts a block when the Note node writes something.
+    # which don't have rewrite, so text like "Note:" only starts a block when the Note node writes something.
     def node?(klass)
-      return false unless klass.is_a?(Class) && klass.method_defined?(:replace)
+      return false unless klass.is_a?(Class) && klass.method_defined?(:rewrite)
 
       klass < Node || (defined?(::LowNode) && klass < ::LowNode) || false
     end
 
-    # Calls a node's replace or render with the context keywords it takes.
+    # Calls a node's rewrite or render with the context keywords it takes.
     def call(node, name, **context)
       parameters = node.method(name).parameters
       return node.public_send(name, **context) if parameters.any? { |type, _| type == :keyrest }
@@ -99,24 +105,56 @@ module Raindown
       list[instances[key]]
     end
 
-    def placeholder(node)
-      "<!-- raindown:node #{list.index(node)} -->"
+    # Renders the node where it is, as a fragment, so its headings are part of the page, or through a placeholder, once
+    # the page is HTML, when its render takes html:, the page's HTML, like TOC's.
+    def rendered(node, context, slot: '')
+      raise NoRender, "#{node.class.name} has no render, so it can't be write-in: write it bare or in comments" unless renders?(node)
+      return placeholder(node, slot:) if !template?(node.class) && takes?(node, :render, :html)
+
+      Fragments.add(html(node, context, slot:))
+    end
+
+    def takes?(node, method_name, keyword)
+      node.method(method_name).parameters.any? { |_, name| name == keyword }
     end
 
-    # Swaps each placeholder for its node's HTML.
-    def render_placeholders(html, **context)
-      html.gsub(PLACEHOLDER) { html(list[::Regexp.last_match(1).to_i], **context) }
+    # Whether the node's class has a template, like a Raindeer .rbx component, which renders in place of render.
+    def template?(klass)
+      klass.respond_to?(:template) && !klass.template.nil?
     end
 
-    def html(node, **context)
-      return node.render_template(props: {}).to_s if node.class.respond_to?(:template) && node.class.template
+    def placeholder(node, slot: '')
+      return "<!-- raindown:node #{list.index(node)} -->" if slot.empty?
 
-      call(node, :render, **context).to_s
+      "<!-- raindown:node #{list.index(node)} slot #{Fragments.store(slot)} -->"
+    end
+
+    # Swaps each placeholder for its node's HTML, given the page's HTML and its slot, the HTML between its tags in <{ }>,
+    # which can hold components' fragments.
+    def render_placeholders(page_html, context)
+      page_html.gsub(PLACEHOLDER) do
+        match = ::Regexp.last_match
+        slot = match[2] ? Fragments.list[match[2].to_i] : ''
+        Fragments.fill(html(list[match[1].to_i], context, slot:, html: page_html))
+      end
     end
 
-    # Whether the node renders its own HTML rather than the HTML of its Markdown.
+    def html(node, context, **keywords)
+      return node.render_template(props: {}).to_s if template?(node.class)
+
+      call(node, :render, **context.to_h, **keywords).to_s
+    end
+
+    # Whether the node renders its own HTML rather than the HTML of its Markdown, which Raindown's nodes render by default.
     def html?(node)
-      node.respond_to?(:render) || (node.class.respond_to?(:template) && !node.class.template.nil?)
+      return true if template?(node.class)
+
+      node.respond_to?(:render) && node.method(:render).owner != Node
+    end
+
+    # Whether the node renders at all, so it can be write-in, in <{ }>.
+    def renders?(node)
+      node.respond_to?(:render) || html?(node)
     end
 
     def instances

data/lib/raindown/pages.rb

@@ -5,7 +5,7 @@ require_relative 'page'
 require_relative 'utils'
 
 module Raindown
-  # The metadata of a project's Markdown files, which list: and files: list by tag.
+  # The metadata of a project's Markdown files, which list: lists by tag.
   # Ported from Raindeer's Rain::Pages, and takes the same Dirload metadata.
   #
   # Each file is tagged with its front matter, like "tags: [ruby, docs]" or "date: 2099", and by its path,
@@ -65,7 +65,7 @@ module Raindown
     def initialize(root:, metadata:, render_options: {}, eager: false)
       @root = root
       @render_options = render_options
-      @file_paths = metadata.file_types.values_at(*EXTENSIONS).flatten.compact
+      @file_paths = filtered_paths(metadata:)
       load_metadata if eager
     end
 
@@ -82,6 +82,11 @@ module Raindown
 
     private
 
+    # The Markdown files in Dirload's metadata, only those under the root path.
+    def filtered_paths(metadata:)
+      metadata.file_types.values_at(*EXTENSIONS).flatten.compact.select { it.start_with?("#{@root}/") }
+    end
+
     def metadata
       load_metadata unless @metadata
       @metadata
@@ -103,8 +108,7 @@ module Raindown
     end
 
     def process(file_path:)
-      metadata = implicit_metadata(file_path:).merge(front_matter(file_path))
-      @metadata[file_path] = metadata
+      metadata = @metadata[file_path] = implicit_metadata(file_path:).merge(front_matter(file_path))
       metadata.each { |type, tag| Array(tag).each { |item| tag(type:, tag: item, file_path:) } }
     end
 

data/lib/raindown/pre_renderer.rb

@@ -5,31 +5,33 @@ require_relative '../elements'
 require_relative 'bare_directives'
 require_relative 'code'
 require_relative 'code_blocks'
+require_relative 'context'
 require_relative 'front_matter'
 
 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. Components and endpoints render here too, as fragments of HTML
-  # that Raindown puts back once the document is HTML.
+  # Nodes bare or in comments, like toc: and list:, render before this. Nodes in <{ }> and endpoints render here, as
+  # fragments of HTML that Raindown puts back once the document is HTML.
   module PreRenderer
     BLOCK_DIRECTIVES = %w[for if list].freeze
     # 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/
+    # A self-closing <{ :list folder: 'notes' }> isn't one, as only an open tag has props after its name.
+    BLOCK_LINE = /^[ \t]*(<\{\s*(?:(?:#{BLOCK_DIRECTIVES.join('|')}):[^}]*|:(?:#{BLOCK_DIRECTIVES.join('|')})\s*)\}>)[ \t]*\n/
     # An endpoint's directive or end tag in a comment, which renders as it would in Antlers' delimiters.
     ENDPOINT_COMMENT = /\A( {0,3})<!--\s*(endpoint:.*?|:endpoint)\s*-->/
 
     module_function
 
-    def render(markdown, variables:, metadata: {}, bare: false)
-      markdown = BareDirectives.expand(markdown) if bare
+    def render(markdown, variables:, context: Context.new)
+      markdown = BareDirectives.expand(markdown) if context.bare
       markdown = delimited_endpoints(markdown) if markdown.include?('<!--')
       return markdown unless markdown.include?('{')
 
       markdown = Code.hide_braces(markdown.dup.force_encoding('UTF-8'))
       body = FrontMatter.parse(markdown).last
-      "#{markdown.delete_suffix(body)}#{render_body(body, variables, metadata)}"
+      "#{markdown.delete_suffix(body)}#{render_body(body, variables, context)}"
     end
 
     # The endpoints in comments in Antlers' delimiters, which the template pass renders, leaving code as it is.
@@ -46,16 +48,17 @@ module Raindown
       lines.join
     end
 
-    def render_body(body, variables, metadata)
+    def render_body(body, variables, context)
       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/]
-      # 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:)
+      # Write-in nodes 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[:write_in, :endpoint]
+      rendered = Antlers.render(ast: Antlers.ast(template:, elements:), current_binding: variables.binding, context:)
 
       "#{leading}#{rendered}#{trailing}"
     end

data/lib/raindown/stat.rb

@@ -23,7 +23,7 @@ module Raindown
                '9' => ['█▀█', '▀▀█', '▀▀▀'], '-' => ['   ', '▀▀▀', '   '], '+' => [' ▄ ', '▀█▀', '   '],
                '.' => [' ', ' ', '▀'], ',' => [' ', ' ', '▀'] }.freeze
 
-    def replace(metadata: NoMetadata) = "```\n#{card_lines(metadata:).join("\n")}\n```"
+    def rewrite(metadata: NoMetadata) = "```\n#{card_lines(metadata:).join("\n")}\n```"
 
     # The number in block digits, then the label, as a card on the Dashboard shows them.
     def card_lines(metadata: NoMetadata)

data/lib/raindown/table/markdown_table.rb

@@ -11,6 +11,8 @@ module Raindown
     module_function
 
     def format(rows)
+      return '' if rows.empty?
+
       header, *body = rows.map { |row| "| #{row.map { escape(it) }.join(' | ')} |" }
       [header, "|#{Array.new(rows.first.length, '---').join('|')}|", *body].join("\n")
     end

data/lib/raindown/table/table.rb

@@ -27,16 +27,30 @@ module Raindown
     end
 
     # Written is what it wrote last time, so it can tell which of the table and the file changed since.
-    def replace(written: [], metadata: NoMetadata)
-      path = File.expand_path(@data.to_s, metadata.respond_to?(:root) ? metadata.root : Dir.pwd)
-      return "Can't show #{@data.inspect} as a table: only CSV and TSV files can be" unless SEPARATORS.key?(File.extname(path).downcase)
-      return "Can't show #{@data.inspect} as a table: no such file" unless File.file?(path)
+    def rewrite(written: [], metadata: NoMetadata)
+      path = data_path(metadata)
+      data_error(path) || synced(path, written.map(&:chomp))
+    end
 
-      synced(path, written.map(&:chomp))
+    # Write-in, in <{ }>, the table only shows its file, and never writes to it.
+    def render(metadata: NoMetadata)
+      path = data_path(metadata)
+      Raindown.commonmark(data_error(path) || MarkdownTable.format(read_rows(path)))
     end
 
     private
 
+    def data_path(metadata)
+      File.expand_path(@data.to_s, metadata.respond_to?(:root) ? metadata.root : Dir.pwd)
+    end
+
+    # Why the file can't be a table, or nil when it can.
+    def data_error(path)
+      return "Can't show #{@data.inspect} as a table: only CSV and TSV files can be" unless SEPARATORS.key?(File.extname(path).downcase)
+
+      "Can't show #{@data.inspect} as a table: no such file" unless File.file?(path)
+    end
+
     def synced(path, written)
       file = read_rows(path)
       synced_hash = written.first&.[](COMMENT, 1)

data/lib/raindown/toc.rb

@@ -14,7 +14,7 @@ module Raindown
     IGNORED = %r{<!--.*?-->|<script\b.*?</script\s*>}mi
     TAG = /<[^>]*>/
 
-    def replace(document:, metadata: nil, bare: false)
+    def rewrite(document:, metadata: nil, bare: false)
       headings = headings(markdown: document, metadata:, bare:)
       return '' if headings.empty?
 
@@ -45,7 +45,7 @@ module Raindown
 
     # 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:) }
+      html ||= Fragments.collect { Raindown.assembled(Context.new(document: markdown, metadata: metadata || NoMetadata, bare:)) }
 
       html.gsub(IGNORED, '').scan(HEADING).map do |level, *ids, content|
         { level: level.to_i, text: CGI.unescapeHTML(content.gsub(TAG, '')).strip, id: CGI.unescapeHTML(ids.compact.first) }

data/lib/raindown/wiki_links.rb

@@ -5,7 +5,7 @@ require_relative 'front_matter'
 
 module Raindown
   # Obsidian's links between notes, which render as Markdown links to the file they name, by its path in the project,
-  # like files: links, while the file keeps them as they are:
+  # like list: links, while the file keeps them as they are:
   #   [[Reading list]]                   [Reading list](<notes/Reading list.md>)
   #   [[Reading list|books]]             [books](<notes/Reading list.md>)
   #   [[Reading list#To read]]           [Reading list > To read](<notes/Reading list.md#to-read>)

data/lib/raindown.rb

@@ -8,6 +8,7 @@ require_relative 'elements'
 require_relative 'raindown/bare_directives'
 require_relative 'raindown/code'
 require_relative 'raindown/config'
+require_relative 'raindown/context'
 require_relative 'raindown/directives'
 require_relative 'raindown/fragments'
 require_relative 'raindown/front_matter'
@@ -32,7 +33,7 @@ module Raindown
   # Without highlighting, code blocks are left for the browser to highlight, like <pre><code class="language-ruby">.
   UNHIGHLIGHTED_OPTIONS = { render: { **HTML_OPTIONS[:render], github_pre_lang: false } }.freeze
 
-  # Stands in for an app's metadata when there isn't any, so list: and files: list nothing.
+  # Stands in for an app's metadata when there isn't any, so list: lists nothing.
   module NoMetadata
     def self.list(**) = []
   end
@@ -49,13 +50,12 @@ module Raindown
   # Bare directives like "toc:" show in bold in the HTML, and the rest stay hidden, as comments.
   # Code blocks are highlighted, unless highlight_code is false for a site that highlights code in the browser.
   def render(markdown:, metadata: NoMetadata, bare: false, highlight_code: true)
-    bare ||= BareDirectives.front_matter?(markdown)
+    context = Context.new(document: markdown, metadata:, bare: bare || BareDirectives.front_matter?(markdown))
 
     highlighting(highlight_code) do
       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:)
+        html = Nodes.render_placeholders(assembled(context), context)
 
         Directives.render("#{html.chomp}\n")
       end
@@ -77,15 +77,14 @@ module Raindown
   end
 
   # 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:)))
+  def assembled(context)
+    HeadingIds.unique(Fragments.fill(html(context)))
   end
 
   # 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 = WikiLinks.to_markdown(markdown, metadata:)
-    commonmark(PreRenderer.render(markdown, variables:, metadata:, bare:))
+  def html(context)
+    markdown = WikiLinks.to_markdown(NodeBlocks.to_rendered(context), metadata: context.metadata)
+    commonmark(PreRenderer.render(markdown, variables: context.variables, context:))
   end
 
   # Markdown to HTML, like a document's or a component's slot.
@@ -103,10 +102,6 @@ module Raindown
     doc.to_html(options: UNHIGHLIGHTED_OPTIONS, plugins: { syntax_highlighter: nil })
   end
 
-  def variables(markdown:)
-    Variables.new(FrontMatter.parse(markdown).first)
-  end
-
   # Commonmarker escapes directives, so they're hidden in HTML comments until it's done.
   def hide_directives(markdown:)
     markdown.gsub('<{', '<!-- ANTLERS').gsub('}>', 'ANTLERS -->').force_encoding('UTF-8')

data/lib/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-11-05 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: antlers
@@ -204,10 +204,10 @@ files:
 - bin/raindown
 - lib/elements.rb
 - lib/lexemes/endpoint_lexeme.rb
-- lib/lexemes/list_lexeme.rb
-- lib/nodes/component_nodes.rb
+- lib/lexemes/node_lexeme.rb
 - lib/nodes/endpoint_node.rb
 - lib/nodes/list_node.rb
+- lib/nodes/write_in_node.rb
 - lib/raindown.rb
 - lib/raindown/actions.rb
 - lib/raindown/bare_directives.rb
@@ -223,6 +223,7 @@ files:
 - lib/raindown/code.rb
 - lib/raindown/code_blocks.rb
 - lib/raindown/config.rb
+- lib/raindown/context.rb
 - lib/raindown/directives.rb
 - lib/raindown/document.rb
 - lib/raindown/editing.rb
@@ -232,13 +233,13 @@ files:
 - lib/raindown/endpoint/endpoint_runner.rb
 - lib/raindown/endpoint/endpoint_variables.rb
 - lib/raindown/endpoint/schema_block.rb
-- lib/raindown/files.rb
 - lib/raindown/fragments.rb
 - lib/raindown/front_matter.rb
 - lib/raindown/gitignore.rb
 - lib/raindown/heading_ids.rb
 - lib/raindown/js/host.mjs
 - lib/raindown/js/js_nodes.rb
+- lib/raindown/list.rb
 - lib/raindown/markdown_nodes.rb
 - lib/raindown/node.rb
 - lib/raindown/node_blocks.rb

data/lib/lexemes/list_lexeme.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-require 'antlers/api'
-
-module Raindown
-  module ListLexeme
-    include Antlers::Lexeme
-
-    module_function
-
-    KEYWORDS = ['list:', 'folder:', 'order:', ':list'].freeze
-
-    def match?(keywords:, **)
-      KEYWORDS.include?(keywords.keys.first)
-    end
-
-    def lexeme(keywords:, **)
-      if keywords['list:']
-        *key, value = keywords['list:'].split(',').map(&:strip)
-
-        list_def = { list_def: value, folder: keywords['folder:'] }
-        list_def[:order] = keywords['order:'] if keywords['order:']
-        list_def[:key] = key.first unless key.empty?
-
-        return list_def
-      end
-
-      # TODO: Keep track of which list loop we're in to allow nested list loops.
-      { list_end: 'level_1' }
-    end
-  end
-end

data/lib/nodes/component_nodes.rb

@@ -1,38 +0,0 @@
-# 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/raindown/files.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'node'
-
-module Raindown
-  # The node behind files:, a list of links to the files the metadata has for its props, like files: folder: 'notes'.
-  # A project can change how files are listed with its own Files node in .raindown, like "class Files < Raindown::Files".
-  class Files < Node
-    def initialize(**tags)
-      @tags = tags
-    end
-
-    # Each file has its front matter, its path and its content.
-    def files(metadata: NoMetadata)
-      metadata.list(**@tags)
-    end
-
-    def replace(metadata: NoMetadata)
-      files(metadata:).map { |file| "- [#{file.title || file.path}](#{file.path})" }.join("\n")
-    end
-  end
-end