raindown 0.12.0 → 0.14.0

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
 
@@ -127,12 +133,7 @@ module Raindown
     end
 
     # A bare block holds the lines straight below it, up to the next blank line, with fenced code kept whole.
-    def bare_block(lines, open)
-      last = open
-      last = CodeBlocks.at(lines, last + 1)&.fetch(:close) || (last + 1) while lines[last + 1] && !lines[last + 1].strip.empty?
-
-      { open:, close: nil, last: }
-    end
+    def bare_block(lines, open) = { open:, close: nil, last: CodeBlocks.last_before_blank(lines, open) }
 
     # The end tag written the same way as the directive: in a comment, or in Antlers' delimiters.
     def end_tag(lines, open, name, comment:)
@@ -161,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

@@ -35,7 +35,8 @@ module Raindown
     private
 
     def block_lines(lines, block)
-      markdown = Nodes.call(block[:node], :replace, document: @content, metadata: @metadata, bare: @bare).to_s.chomp
+      context = { document: @content, metadata: @metadata, bare: @bare, written: written_lines(lines, block) }
+      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]
 
@@ -54,6 +55,11 @@ module Raindown
       raise BlankLine, "#{name} writes blank lines, so it needs <!-- #{name}: --> and <!-- :#{name} --> around it"
     end
 
+    # What the block's node wrote last time, between its directive and its end tag, or the next blank line.
+    def written_lines(lines, block)
+      lines[(block[:open] + 1)...(block[:close] || (block[:last] + 1))]
+    end
+
     def line(line)
       line.end_with?("\n") ? line : "#{line}\n"
     end

data/lib/raindown/nodes.rb

@@ -1,25 +1,33 @@
 # 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'
+require_relative 'table/table'
 require_relative 'toc'
 
 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: and bare:, 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 or Chart node replaces Raindown's.
-    BUILT_INS = { 'toc' => 'TOC', 'files' => 'Files', 'chart' => 'Chart' }.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
 
@@ -61,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 }
@@ -97,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,
@@ -61,10 +61,12 @@ module Raindown
     attr_reader :root
 
     # Render options, like highlight_code: false, are for rendering each listed file's content.
-    def initialize(metadata:, root:, render_options: {})
+    # Eager reads every file's front matter straight away, for an app like Raindeer that needs all of it from the start.
+    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
 
     # The files with any of the tags, like list(folder: 'basics') or list(tags: 'ruby'), sorted by order.
@@ -80,17 +82,22 @@ 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
-      process_files unless @metadata
+      load_metadata unless @metadata
       @metadata
     end
 
     def tags
-      process_files unless @tags
+      load_metadata unless @tags
       @tags
     end
 
-    def process_files
+    def load_metadata
       @metadata = {}
       @tags = {}
       @file_paths.each { |file_path| process(file_path:) }
@@ -101,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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Raindown
+  # Rows of cells as a Markdown table, its first row the header, and back again. A | in a cell is escaped as \|, and
+  # a line break is written as a space, as a table's cells are one line. The TableFormatter lines up its columns.
+  module MarkdownTable
+    SEPARATOR = /\A\|?(\s*:?-+:?\s*\|)*\s*:?-+:?\s*\|?\z/
+    # A | that isn't escaped.
+    PIPE = /(?<!\\)\|/
+
+    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
+
+    # The rows of the table in the lines, leaving out its separator, or none when they aren't a table.
+    def parse(lines)
+      return [] unless lines[1]&.strip&.match?(SEPARATOR)
+
+      [lines[0], *lines.drop(2)].take_while { it.strip.start_with?('|') }.map { cells(it.strip) }
+    end
+
+    def cells(line)
+      line.delete_prefix('|').delete_suffix('|').split(PIPE, -1).map { it.strip.gsub('\|', '|') }
+    end
+
+    def escape(cell)
+      cell.gsub('|', '\|').gsub(/\s*\R\s*/, ' ')
+    end
+  end
+end

data/lib/raindown/table/table.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'digest'
+require 'json'
+
+require_relative '../node'
+require_relative 'markdown_table'
+
+module Raindown
+  # The node behind table:, a CSV or TSV file relative to the project as a Markdown table, after a comment of how many
+  # rows it has and a hash of them, as they were when the table and the file last matched:
+  #   table: 'data/team.csv'
+  #   <!-- table 2 rows · 3f2a9c -->
+  #   | name | role     |
+  #   |------|----------|
+  #   | Ada  | engineer |
+  #   | Lin  | design   |
+  # Edit the table and its rows are written back to the file, or edit the file and the table's written again. When
+  # both changed, neither is, and the table's comment says so until they match again.
+  class Table < Node
+    COMMENT = /\A<!-- table (?:conflict|\d+ rows?) · (\h+) -->\z/
+    SEPARATORS = { '.csv' => ',', '.tsv' => "\t" }.freeze
+
+    def initialize(data)
+      @data = data
+    end
+
+    # Written is what it wrote last time, so it can tell which of the table and the file changed since.
+    def rewrite(written: [], metadata: NoMetadata)
+      path = data_path(metadata)
+      data_error(path) || synced(path, written.map(&:chomp))
+    end
+
+    # 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)
+      table = MarkdownTable.parse(written.drop(1))
+      return markdown(file) if synced_hash.nil? || table.empty? || [synced_hash, hash_rows(file)].include?(hash_rows(table))
+      return markdown(write_rows(path, table)) if hash_rows(file) == synced_hash
+
+      warn "raindown: #{@data} and its table both changed, so neither is written until they match"
+      ["<!-- table conflict · #{synced_hash} -->", *written.drop(1)].join("\n")
+    end
+
+    def markdown(rows)
+      return '' if rows.empty?
+
+      count = rows.length - 1
+      "<!-- table #{count} row#{'s' unless count == 1} · #{hash_rows(rows)} -->\n#{MarkdownTable.format(rows)}"
+    end
+
+    def read_rows(path)
+      rows = CSV.read(path, col_sep: SEPARATORS[File.extname(path).downcase], skip_blanks: true, encoding: Encoding::UTF_8)
+      width = rows.map(&:length).max.to_i
+      rows.map { |row| Array.new(width) { row[it].to_s.strip } }
+    end
+
+    def write_rows(path, rows)
+      File.write(path, rows.map { CSV.generate_line(it, col_sep: SEPARATORS[File.extname(path).downcase]) }.join)
+      rows
+    end
+
+    def hash_rows(rows)
+      Digest::SHA256.hexdigest(JSON.generate(rows))[0, 6]
+    end
+  end
+end

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) }