raindown 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dffe3184c451794454149de18701ac6bd1afc2674b6a41385773d0f052bb2e5
-  data.tar.gz: 4e49463244dffc8e9b39873e2137f072f8632daec02c314d928fe09bbb115fd5
+  metadata.gz: f795c35070ab8ae4f6b40e5a32595ab9ba6099b99f42aada8d0faafe2f56121d
+  data.tar.gz: a01426b3aab916e21b0e68f66fddd7f6b55d7e9c34ceb9665118a60b3ceae4b5
 SHA512:
-  metadata.gz: 9502a0acb5cca634c884f74b8f2fc3e3a83c3fbe5bc635df7fccb779147718563a0a44679b3b3e6a1cf9da9e691026ff55953fc9a6b0aafad9cc48444eec12c6
-  data.tar.gz: dc928865b0da23c1b3dd67d859e94a3e718fe370b3d21d9344060cd5019e82fd5cce029b56d6008632690f9f1cc6f782cd41a8c38ca6d233bd06336f29fb7077
+  metadata.gz: 052231532f48cc3a575388ebe95fa62b70bc3eba2121742142071c2ab256ced437de1f4c80f2e439599d579c2b5eea2d793b7cb05439601523bc72ff9c252dd6
+  data.tar.gz: 98ff7b646f8e380817bbf69efc06a0bf67b4945a233349c9702d3140458bb27e387ecd010498c80dbfa4a9d2e64872b4f7af75bcd12b28b992e8b82ac66f56c9

data/lib/raindown/actions.rb

@@ -24,7 +24,7 @@ module Raindown
     # Writes back the whole file, like saving it while it's watched, with bare directives allowed, and endpoints with no
     # response run, when asked, like with --bare and -x.
     def write_back(path, bare: false, execute: false)
-      Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
+      Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path)).changed?
     end
 
     # Runs one endpoint's request and writes its response, replacing any response it had, then raises when the response

data/lib/raindown/bare_directives.rb

@@ -13,17 +13,17 @@ module Raindown
   #
   # A bare schema: shows in bold, with its fields in a code block below it.
   #
-  # Bare directives have no end tag. A bare endpoint closes itself after its curl snippet and response, so where it
-  # needs more than that, write it in comments with an end tag instead:
+  # Bare directives have no end tag. A bare endpoint holds the lines straight below it, its curl snippet, the comment
+  # with its response's status, time and date, and its response, up to the next blank line, like a bare node block, so
+  # where it needs blank lines, write it in comments with an end tag instead:
   #   <!-- endpoint: -->
   #   ...
   #   <!-- :endpoint -->
   module BareDirectives
     EXTENSIONS = %w[.rd .raindown].freeze
-    # The block directives, and the method that finds the line their end tag goes after.
-    BLOCK_KEYWORDS = { 'endpoint:' => :after_endpoint }.freeze
-    # Four spaces of indent would make the line a Markdown code block.
-    LINE = /\A( {0,3})((#{BLOCK_KEYWORDS.keys.join('|')})(?:[ \t]+\S.*?)?)[ \t]*$/
+    # A bare endpoint, the one bare directive with a block. Four spaces of indent would make the line a Markdown code
+    # block.
+    LINE = /\A( {0,3})(endpoint:(?:[ \t]+\S.*?)?)[ \t]*$/
 
     module_function
 
@@ -75,7 +75,7 @@ module Raindown
       return index unless match
 
       lines[index] = "#{Directives.marker(match[2], shown: true)}\n#{wrap(lines[index])}"
-      close_block(lines, index, indent: match[1], keyword: match[3])
+      close_block(lines, index, indent: match[1])
       index
     end
 
@@ -88,16 +88,10 @@ module Raindown
     end
 
     # The end tag after the block, then the end tag in bold, as a bare directive's shown.
-    def close_block(lines, index, indent:, keyword:)
-      last = public_send(BLOCK_KEYWORDS[keyword], lines, index + 1) || index
+    def close_block(lines, index, indent:)
+      last = CodeBlocks.last_before_blank(lines, index)
       lines[last] = "#{lines[last]}\n" unless lines[last].end_with?("\n")
-      name = keyword.delete_suffix(':')
-      lines.insert(last + 1, "#{indent}<{ :#{name} }>\n#{Directives.marker(":#{name}", shown: true)}\n")
-    end
-
-    # The last line of the curl snippet and response below an endpoint.
-    def after_endpoint(lines, index)
-      CodeBlocks.endpoint(lines, index).last&.fetch(:close)
+      lines.insert(last + 1, "#{indent}<{ :endpoint }>\n#{Directives.marker(':endpoint', shown: true)}\n")
     end
   end
 end

data/lib/raindown/blueprints.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
+require 'fileutils'
 require 'json'
 require 'time'
 require 'unicode/display_width'
 require_relative 'projects'
 
 module Raindown
-  # Blueprints from Claude Code's replies, kept in a project's .raindown/blueprints.md, which the terminal UI's Blueprints page
+  # Blueprints from Claude Code's replies, kept in a project's .raindown/data/blueprints.md, which the terminal UI's Blueprints page
   # shows, newest first. Each is a code block under a heading of when it was saved and its kind:
   #   ## 2026-10-30T03:14:07Z · mockup
   #
@@ -32,7 +33,7 @@ module Raindown
         "#{time.sub('T', ' ').sub(/:\d\dZ\z/, ' UTC')}#{SEPARATOR}#{kind}"
       end
 
-      # As it's saved in .raindown/blueprints.md, under when it was saved and its kind, then its description.
+      # As it's saved in .raindown/data/blueprints.md, under when it was saved and its kind, then its description.
       def markdown(saved_at)
         about = "#{description}\n\n" if description
         "## #{saved_at}#{SEPARATOR}#{kind}\n\n#{about}```#{kind}\n#{lines.join("\n")}\n```\n\n"
@@ -49,7 +50,7 @@ module Raindown
       def distance(other) = [(top - other.top).abs, (left + right - other.left - other.right).abs]
     end
 
-    FILE = File.join('.raindown', 'blueprints.md')
+    FILE = File.join('.raindown', 'data', 'blueprints.md')
     # The kinds a code block can be marked with to be a blueprint.
     KINDS = %w[mockup diagram chart table other].freeze
     # What a blueprint's drawn with: lines, like boxes' and arrows', and blocks, like charts' bars.
@@ -79,8 +80,7 @@ module Raindown
       return [] unless File.exist?(path)
 
       lines = File.readlines(path, chomp: true)
-      starts = lines.each_index.select { lines[it].start_with?('## ') }
-      starts.filter_map { |start| blueprint(lines, start) }.reverse
+      lines.each_index.select { lines[it].start_with?('## ') }.filter_map { blueprint(lines, it) }.reverse
     end
 
     # Saves the blueprints in Claude Code's last reply, from its Stop hook's JSON, to the project it's working in, if any,
@@ -91,7 +91,8 @@ module Raindown
       return if drawn.empty?
 
       time = Time.now.utc.iso8601
-      File.open(File.join(root, FILE), 'a') { |file| drawn.each { file.write(it.markdown(time)) } }
+      path = File.join(root, FILE).tap { FileUtils.mkdir_p(File.dirname(it)) }
+      File.open(path, 'a') { |file| drawn.each { file.write(it.markdown(time)) } }
     end
 
     # The text's code blocks that are blueprints, each with its kind and the paragraph above it.

data/lib/raindown/cli.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'open3'
+require 'tmpdir'
 require 'trees'
 require_relative '../raindown'
 require_relative '../version'
@@ -32,7 +34,7 @@ module Raindown
         init [DIRECTORY]    Create a .raindown folder for the project's config and nodes (default: current directory)
         server              Keep Raindown loaded for an editor, answering a JSON request a line on stdin with its HTML,
                             or its Markdown as it would be written back, like --stdin and --stdin --rewrite
-        blueprints            Save the blueprints in Claude Code's last reply to .raindown/blueprints.md, for the terminal
+        blueprints            Save the blueprints in Claude Code's last reply to .raindown/data/blueprints.md, for the terminal
                             UI's Blueprints page, as a Stop hook that's given the hook's JSON
 
       Options:
@@ -52,12 +54,8 @@ module Raindown
       Set RAINDOWN_DEBUG=1 to show where an error happened.
     TEXT
 
-    CONFIG = <<~YAML
-      # Raindown project settings. See https://raindown.dev/docs/config
-      #
-      # Leave code blocks unhighlighted, so the browser can highlight them instead:
-      # highlight_code: false
-    YAML
+    # The files "raindown init" puts in a project's .raindown folder, like "rain new" clones raindeer-template.
+    TEMPLATE_URL = 'https://github.com/rainpour/raindown-init'
 
     # A path opens the terminal UI, or after "watch" it's watched, and with --html or --stdin it's rendered. The flags
     # are keyword arguments, in any order, like -x for x:, and --html is the OUTPUT when it's given one.
@@ -111,16 +109,20 @@ module Raindown
       abort("raindown: #{path}: #{error.message}")
     end
 
-    # Creates the .raindown folder that marks a project's root and holds its config.yml and nodes.
+    # Clones raindown-init into the .raindown folder that marks a project's root and holds its config.yml and nodes,
+    # keeping any files already there.
     def self.init(directory = nil)
       folder = File.join(directory || Dir.pwd, Nodes::FOLDER)
       config = File.join(folder, Config::FILE)
       return puts("#{config} already exists") if File.exist?(config)
 
-      FileUtils.mkdir_p(folder)
-      File.write(config, CONFIG)
-      gitignore = File.join(folder, '.gitignore')
-      File.write(gitignore, "#{EndpointVariables::LOCAL_FILE}\n") unless File.exist?(gitignore)
+      Dir.mktmpdir do |clone|
+        clone_template(clone)
+        FileUtils.mkdir_p(folder)
+        (Dir.children(clone) - ['.git']).each do |name|
+          FileUtils.cp_r(File.join(clone, name), folder) unless File.exist?(File.join(folder, name))
+        end
+      end
       puts "Created #{config}"
       puts 'Put your own nodes in the same folder. See https://raindown.dev/docs/components'
     end
@@ -136,6 +138,11 @@ module Raindown
     class << self
       private
 
+      def clone_template(directory)
+        output, status = Open3.capture2e('git', 'clone', '--quiet', '--depth', '1', TEMPLATE_URL, directory)
+        abort("Couldn't clone #{TEMPLATE_URL}:\n#{output}") unless status.success?
+      end
+
       # Endpoints run while formatting, which --stdin skips, so -x can't go with it. --html - prints, like --html.
       def open_path(path, html:, stdin:, bare:, execute:)
         output = html unless [true, '-'].include?(html)
@@ -152,14 +159,13 @@ module Raindown
         Nodes.load(path)
 
         metadata = Pages.for(path)
-        Rewriter.update(path:, bare:, execute:, metadata:)
+        failures = Rewriter.update(path:, bare:, execute:, metadata:).failures
         write(output, Raindown.render_file(path:, bare:, metadata:))
-        check_endpoints(path, bare:)
+        check_endpoints(failures)
       end
 
       # Endpoint responses that fail their checks, like status: 200, are listed, and fail the command, for CI.
-      def check_endpoints(path, bare:)
-        failures = EndpointRunner.failures(content: Utils.read_markdown(path), path:, bare:)
+      def check_endpoints(failures)
         return if failures.empty?
 
         warn(*failures.map { "Endpoint check failed: #{it}" })

data/lib/raindown/code_blocks.rb

@@ -5,6 +5,11 @@ module Raindown
   module CodeBlocks
     FENCE = /\A {0,3}(`{3,}|~{3,})[ \t]*(\S*)/
     SNIPPET_LANGUAGES = %w[sh bash shell zsh console curl].freeze
+    # The comment Raindown writes between an endpoint's snippet and its response, with the response's status, how long
+    # it took and the date it was fetched, like <!-- response 200 · 142 ms · 2026-10-14 -->.
+    RESPONSE_COMMENT = /\A {0,3}<!-- response [^\n]*? -->[ \t]*$/
+    # The line closing a fence, like ``` or ~~~~, compiled once per fence.
+    CLOSINGS = Hash.new { |closings, fence| closings[fence] = /\A {0,3}#{fence[0]}{#{fence.length},}[ \t]*$/ }
 
     module_function
 
@@ -13,31 +18,36 @@ module Raindown
       fence, language = lines[index]&.match(FENCE)&.captures
       return unless fence
 
-      close = (index + 1...lines.length).find { |i| lines[i].match?(/\A {0,3}#{fence[0]}{#{fence.length},}[ \t]*$/) }
+      close = (index + 1...lines.length).find { |i| lines[i].match?(CLOSINGS[fence]) }
       { open: index, close:, language:, body: lines[index + 1...close].join } if close
     end
 
-    # An endpoint's curl snippet and its response, if it has one yet.
-    # A second snippet straight after is another example rather than the response.
-    def endpoint(lines, index)
-      snippet, response = following(lines, index, limit: 2)
-      response && snippet?(response) ? [snippet] : [snippet, response].compact
+    # An endpoint's curl snippet and its response, if it has one yet, with the line of the response comment between them
+    # as the response's :comment, if there is one. A second snippet straight after is another example rather than the
+    # response. A bare endpoint's are in the lines straight below it, up to the next blank line.
+    def endpoint(lines, index, bare: false)
+      lines = lines[..last_before_blank(lines, index - 1)] if bare
+      snippet = at(lines, skip_blank_lines(lines, index))
+      return [] unless snippet
+
+      index = skip_blank_lines(lines, snippet[:close] + 1)
+      comment = index if lines[index]&.match?(RESPONSE_COMMENT)
+      response = at(lines, comment ? skip_blank_lines(lines, comment + 1) : index)
+      return [snippet] if response.nil? || snippet?(response)
+
+      [snippet, response.merge(comment:)]
     end
 
     def snippet?(block)
       SNIPPET_LANGUAGES.include?(block[:language].downcase) || block[:body].lstrip.start_with?('curl')
     end
 
-    # Up to limit blocks from index on, with only blank lines before and between them.
-    def following(lines, index, limit:)
-      blocks = []
-
-      while blocks.length < limit && (block = at(lines, skip_blank_lines(lines, index)))
-        blocks << block
-        index = block[:close] + 1
-      end
-
-      blocks
+    # The last of the lines straight below open, up to the next blank line, with fenced code kept whole, or open when
+    # there are none, like a bare block's.
+    def last_before_blank(lines, open)
+      last = open
+      last = at(lines, last + 1)&.fetch(:close) || (last + 1) while lines[last + 1] && !lines[last + 1].strip.empty?
+      last
     end
 
     def skip_blank_lines(lines, index)

data/lib/raindown/document.rb

@@ -16,6 +16,9 @@ module Raindown
   class Document
     Heading = Data.define(:level, :text, :line)
 
+    # Its Markdown, and whether it allows bare directives.
+    attr_reader :markdown, :bare
+
     # A content directive: a node, like toc: or a project's Changelog:, or an endpoint.
     # It spans line to end_line, its end tag, or the last line of a bare block.
     # Body is the lines inside it, between it and its end tag, like an endpoint's request and response.
@@ -116,21 +119,18 @@ module Raindown
       [bare.strip, true] if bare
     end
 
-    # The response and the date it was fetched are the output, while the curl snippet above them is the author's.
+    # The response and the comment above it are the output, while the curl snippet above them is the author's.
     def endpoint(open, args, writes)
-      curl, response = CodeBlocks.endpoint(@lines, open + 1)
-      output = response && (response[:open]..(fetched?(response[:close] + 1) ? response[:close] + 1 : response[:close]))
+      bare = Directives.bare?(@lines[open])
+      curl, response = CodeBlocks.endpoint(@lines, open + 1, bare:)
+      output = response && ((response[:comment] || response[:open])..response[:close])
       last = output&.end || curl&.fetch(:close) || open
-      # A bare endpoint, which isn't delimited, ends after its blocks.
-      last = end_tag(after: last) || last unless Directives.bare?(@lines[open])
+      # A bare endpoint ends at the next blank line, and one in a comment at its end tag.
+      last = bare ? CodeBlocks.last_before_blank(@lines, open) : end_tag(after: last) || last
 
       directive('endpoint', args, open..last, output:, writes:)
     end
 
-    def fetched?(index)
-      @lines[index]&.match?(EndpointRunner::FETCHED)
-    end
-
     # The end tag after the endpoint's blocks, with only blank lines between.
     def end_tag(after:)
       index = CodeBlocks.skip_blank_lines(@lines, after + 1)

data/lib/raindown/editing.rb

@@ -17,8 +17,8 @@ module Raindown
 
     def rewrite_markdown(markdown, path:, bare: false, execute: false)
       Nodes.load(path)
-      rewritten = Rewriter.rewrite(content: markdown, path:, bare:, execute:, metadata: Pages.for(path))
-      { output: rewritten, warnings: EndpointRunner.failures(content: rewritten, path:, bare:).map { "Endpoint check failed: #{it}" } }
+      rewrite = Rewriter.rewrite(content: markdown, path:, bare:, execute:, metadata: Pages.for(path))
+      { output: rewrite.content, warnings: rewrite.failures.map { "Endpoint check failed: #{it}" } }
     end
   end
 end

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -10,17 +10,17 @@ require_relative 'endpoint_variables'
 
 module Raindown
   # Runs the curl block under an endpoint directive in a comment, or a bare one, and writes the response in the code
-  # block below it, followed by the date it was fetched, its status and how long it took.
+  # block below it, after a comment of its status, how long it took and the date it was fetched.
   # Only runs when that block is missing or empty, and --execute is passed, so a file can't run requests by itself.
   # Or with only: and a directive's line index, runs just that endpoint, replacing any response it has.
   #   <!-- endpoint: -->
   #   ```sh
   #   curl https://api.example.com
   #   ```
+  #   <!-- response 200 · 142 ms · 2026-10-14 -->
   #   ```json
   #   { "id": 1 }
   #   ```
-  #   <!-- raindown:fetched 2026-10-14 · 200 · 142 ms -->
   #   <!-- :endpoint -->
   # Its snippet's {placeholders} are filled from EndpointVariables, and with as: login, later snippets can use its
   # response, like {login.token}. With status: and schema:, each response in the file is checked, and failures are kept.
@@ -32,9 +32,7 @@ module Raindown
     DIRECTIVE = /\A {0,3}<\{\s*endpoint:(.*?)\}>[ \t]*$/
     COMMENT = /\A {0,3}<!--\s*endpoint:(.*?)-->[ \t]*$/
     END_TAG = /\A {0,3}(?:<\{\s*:endpoint\s*\}>|<!--\s*:endpoint\s*-->)[ \t]*$/
-    # The date a response was fetched, on the line after it.
-    FETCHED = /\A {0,3}<!-- raindown:fetched [^\n]*? -->[ \t]*$/
-    FETCHED_STATUS = /raindown:fetched \S+ · (\d{3}) /
+    RESPONSE_STATUS = /<!-- response (\d{3}) /
 
     attr_reader :failures
 
@@ -42,11 +40,6 @@ module Raindown
       new(content:, path:, bare: BareDirectives.enabled?(path:, content:, bare:), execute:).rewrite
     end
 
-    # The file's failed checks, like "api.md:3: expected status 200, received 404", from the responses in it.
-    def self.failures(content:, path: nil, bare: false)
-      new(content:, path:, bare: BareDirectives.enabled?(path:, content:, bare:)).tap(&:rewrite).failures
-    end
-
     def initialize(content:, path: nil, bare: false, execute: false, only: nil)
       @lines = content.lines
       @path = path
@@ -88,19 +81,19 @@ module Raindown
 
     # Returns the index of the last line it handled.
     def fill(index, args, directive:)
-      curl, output = CodeBlocks.endpoint(@lines, index)
+      curl, output = CodeBlocks.endpoint(@lines, index, bare: !@lines[directive].match?(COMMENT))
       return index - 1 unless curl&.dig(:body)&.lstrip&.start_with?('curl')
       return write_output(curl:, output:, args:, directive:) if run?(output, directive)
       return curl[:close] unless output
 
       @variables.remember(args.name, output[:body])
-      check(args, directive:, body: output[:body], status: fetched_status(output))
+      check(args, directive:, body: output[:body], status: response_status(output))
       curl[:close]
     end
 
-    # The status in the fetched comment after a response, which responses fetched before statuses were kept don't have.
-    def fetched_status(output)
-      @lines[output[:close] + 1]&.[](FETCHED_STATUS, 1)&.to_i
+    # The status in the comment above a response, which a comment written by hand may not have.
+    def response_status(output)
+      @lines[output[:comment]][RESPONSE_STATUS, 1]&.to_i if output[:comment]
     end
 
     # Run alone, only the endpoint that ran is checked. One without a response or a status hasn't run, so it has nothing
@@ -118,14 +111,15 @@ module Raindown
       @execute && (output.nil? || output[:body].strip.empty?)
     end
 
-    # Replaces the output block and the date it was fetched, or with no block, replaces nothing just after the curl block.
+    # Replaces everything from just after the curl block to the end of the output block, if there is one, like its
+    # comment.
     # Secrets that a response echoes are written as their placeholders.
     def write_output(curl:, output:, args:, directive:)
       response = Curl.run(curl[:body], @variables)
       body = @variables.redact(response.body)
       @variables.remember(args.name, body)
       check(args, directive:, body:, status: response.status)
-      replace_output(curl:, output:, block: [*output_block(body, response.language), fetched(response)])
+      replace_output(curl:, output:, block: [response_comment(response), *output_block(body, response.language)])
     rescue Curl::Error => e
       message = @variables.redact(e.message)
       # The one endpoint that was asked for fails for the caller to show, like in the terminal UI.
@@ -137,21 +131,13 @@ module Raindown
 
     # Returns the index of the block's last line.
     def replace_output(curl:, output:, block:)
-      block.unshift("\n") unless output
-      start = output ? output[:open] : curl[:close] + 1
-
-      @lines[start, output ? replaced_length(output) : 0] = block
+      start = curl[:close] + 1
+      @lines[start, output ? output[:close] - start + 1 : 0] = block
       start + block.length - 1
     end
 
-    # The output block, and the line after it when that's the date it was last fetched.
-    def replaced_length(output)
-      length = output[:close] - output[:open] + 1
-      @lines[output[:close] + 1]&.match?(FETCHED) ? length + 1 : length
-    end
-
-    def fetched(response)
-      "<!-- raindown:fetched #{Date.today.iso8601} · #{response.status} · #{response.milliseconds} ms -->\n"
+    def response_comment(response)
+      "<!-- response #{response.status} · #{response.milliseconds} ms · #{Date.today.iso8601} -->\n"
     end
 
     # The fence is longer than any run of backticks in the body, so the body can't close it.

data/lib/raindown/markdown_nodes.rb

@@ -26,7 +26,7 @@ module Raindown
       end
     end
 
-    # Whether a file is a Markdown Component, by its extension and name, so .raindown/blueprints.md isn't one.
+    # Whether a file is a Markdown Component, by its extension and name, so .raindown/data/blueprints.md isn't one.
     def file?(path)
       EXTENSIONS.include?(File.extname(path)) && File.basename(path, '.*').match?(NAME)
     end

data/lib/raindown/node_blocks.rb

@@ -127,12 +127,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:)

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], :replace, **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

@@ -6,6 +6,7 @@ require_relative 'js/js_nodes'
 require_relative 'markdown_nodes'
 require_relative 'node'
 require_relative 'stat'
+require_relative 'table/table'
 require_relative 'toc'
 
 module Raindown
@@ -13,11 +14,12 @@ module Raindown
   # 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.
+  # document: (the Markdown being rendered), metadata:, bare: and written: (the lines it wrote last time), and gets the
+  # ones it asks for.
   module Nodes
     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
+    # 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+) -->/
 

data/lib/raindown/pages.rb

@@ -13,36 +13,60 @@ module Raindown
   #   folder: basics, order: 1, path: docs/_basics/_1-getting-started.md
   # Folder tags can share a folder name with "&", like docs/_1&_basics/getting-started.md.
   # An app can add its own metadata by subclassing and overriding implicit_metadata, like Raindeer's URL paths.
+  # Each file's front matter is only read once something lists the files. The listing and the front matter are kept for
+  # as long as the process runs, like "raindown server", until they change.
   class Pages
     EXTENSIONS = %w[md rd markdown raindown].freeze
     SEGMENTS = Regexp.union(['/', '&', '-'])
 
     class << self
+      # Each file's front matter, by its path, with the time it was modified when it was read.
+      def front_matters
+        @front_matters ||= {}
+      end
+
       # The Markdown files under a project's root, the folder with its .raindown folder or else the file's folder.
       def for(path)
         file_directory = File.dirname(File.expand_path(path))
         load(root: Nodes.find_folder(file_directory)&.then { File.dirname(it) } || file_directory)
       end
 
-      # Lists the files under the root with Dirload, without loading them.
+      # Lists the files under the root, without loading them, for Dirload.
       def load(root:)
         require 'dirload'
-        file_types = Dirload.file_paths(absolute_path: root).group_by { Dirload.extension(file_path: it) }
+        file_types = file_paths(root).group_by { Dirload.extension(file_path: it) }
         new(metadata: Dirload::Metadata.new(loaded_paths: {}, missed_paths: [], file_types:), root:)
       end
+
+      # The files under the root, outside hidden folders, like Dirload lists them. They're listed again once a folder
+      # among them has changed, which adding, removing or renaming a file or folder in it does.
+      def file_paths(root)
+        listing = listings[root]
+        return listing[:file_paths] if listing&.dig(:folders)&.all? { |folder, modified| modified_at(folder) == modified }
+
+        folders, file_paths = Dir["#{root}/**/*"].partition { File.directory?(it) }
+        listings[root] = { file_paths:, folders: [root, *folders].to_h { [it, modified_at(it)] } }
+        file_paths
+      end
+
+      def listings
+        @listings ||= {}
+      end
+
+      def modified_at(path)
+        File.mtime(path) if File.exist?(path)
+      end
     end
 
     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
-      @metadata = {}
-      @tags = {}
-
-      @file_paths.each { |file_path| process(file_path:) }
+      load_metadata if eager
     end
 
     # The files with any of the tags, like list(folder: 'basics') or list(tags: 'ruby'), sorted by order.
@@ -53,21 +77,46 @@ module Raindown
     end
 
     def tagged(**tags)
-      tags.flat_map { |type, tag| @tags.dig(type.to_sym, tag) || [] }.uniq
+      tags.flat_map { |type, tag| self.tags.dig(type.to_sym, tag) || [] }.uniq
     end
 
     private
 
+    def metadata
+      load_metadata unless @metadata
+      @metadata
+    end
+
+    def tags
+      load_metadata unless @tags
+      @tags
+    end
+
+    def load_metadata
+      @metadata = {}
+      @tags = {}
+      @file_paths.each { |file_path| process(file_path:) }
+    end
+
     def listed_page(file_path)
-      Page.new(file_path:, metadata: @metadata[file_path], render_options: @render_options)
+      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(Utils.read_markdown(file_path)).first)
+      metadata = implicit_metadata(file_path:).merge(front_matter(file_path))
       @metadata[file_path] = metadata
       metadata.each { |type, tag| Array(tag).each { |item| tag(type:, tag: item, file_path:) } }
     end
 
+    # The file's front matter, read again only when the file's changed since it was last read.
+    def front_matter(file_path)
+      modified = File.mtime(file_path)
+      modified_then, front_matter = self.class.front_matters[file_path]
+      return front_matter if modified_then == modified
+
+      FrontMatter.parse(Utils.read_markdown(file_path)).first.tap { self.class.front_matters[file_path] = [modified, it] }
+    end
+
     # The path is relative to the root, like docs/_basics/_1-getting-started.md.
     # A subclass can add or replace metadata here, like Raindeer's Rain::Pages replacing the path with a URL path.
     def implicit_metadata(file_path:)
@@ -104,8 +153,8 @@ module Raindown
 
     # Files with an order come first, by order, then the rest by path.
     def sort_key(file_path)
-      order = @metadata[file_path][:order]
-      [order.is_a?(Numeric) ? 0 : 1, order.is_a?(Numeric) ? order : 0, @metadata[file_path][:path].to_s]
+      order = metadata[file_path][:order]
+      [order.is_a?(Numeric) ? 0 : 1, order.is_a?(Numeric) ? order : 0, metadata[file_path][:path].to_s]
     end
   end
 end