raindown 0.10.0 → 0.12.0

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -4,12 +4,13 @@ require 'date'
 require_relative '../bare_directives'
 require_relative '../code_blocks'
 require_relative 'curl'
+require_relative 'endpoint_args'
+require_relative 'schema_block'
 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.
+  # block below it, followed by the date it was fetched, its status and how long it took.
   # 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: -->
@@ -19,10 +20,11 @@ module Raindown
   #   ```json
   #   { "id": 1 }
   #   ```
-  #   <!-- raindown:fetched 2026-10-14 -->
+  #   <!-- 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}.
+  # response, like {login.token}. With status: and schema:, each response in the file is checked, and failures are kept.
+  # A schema: can name a SchemaBlock above it, like schema: 'User', or one in .raindown/schemas.rd.
   # One in Antlers' delimiters, <{ endpoint: }>, only renders, so it's never run.
   class EndpointRunner
     # An endpoint's directive in Antlers' delimiters, which only renders, or in a comment, which writes its response back,
@@ -32,6 +34,9 @@ module Raindown
     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}) /
+
+    attr_reader :failures
 
     def self.rewrite(content:, path: nil, bare: false, execute: false, **)
       new(content:, path:, bare: BareDirectives.enabled?(path:, content:, bare:), execute:).rewrite
@@ -39,10 +44,13 @@ module Raindown
 
     def initialize(content:, path: nil, bare: false, execute: false, only: nil)
       @lines = content.lines
+      @path = path
       @variables = EndpointVariables.new(path:, content:)
       @bare = bare
       @execute = execute
       @only = only
+      @failures = []
+      @schemas = SchemaBlock.shared(path)
     end
 
     def rewrite
@@ -51,6 +59,9 @@ module Raindown
       while index < @lines.length
         if (block = CodeBlocks.at(@lines, index))
           index = block[:close]
+        elsif (schema = SchemaBlock.at(@lines, index, bare: @bare))
+          @schemas[schema.name] = SchemaBlock.resolve(schema.type, @schemas)
+          index = schema.last
         elsif (args = directive_args(@lines[index]))
           index = fill(index + 1, args, directive: index)
         end
@@ -67,23 +78,33 @@ module Raindown
     def directive_args(line)
       args = line[COMMENT, 1]
       args ||= BareDirectives.wrap(line)&.[](DIRECTIVE, 1) if @bare
-      args&.split
+      EndpointArgs.parse(args, schemas: @schemas) if args
     end
 
     # Returns the index of the last line it handled.
     def fill(index, args, directive:)
       curl, output = CodeBlocks.endpoint(@lines, index)
       return index - 1 unless curl&.dig(:body)&.lstrip&.start_with?('curl')
-      return write_output(curl:, output:, name: response_name(args)) if run?(output, directive)
+      return write_output(curl:, output:, args:, directive:) if run?(output, directive)
+      return curl[:close] unless output
 
-      @variables.remember(response_name(args), output[:body]) if output
+      @variables.remember(args.name, output[:body])
+      check(args, directive:, body: output[:body], status: fetched_status(output))
       curl[:close]
     end
 
-    # The name that as: gives the endpoint, for later snippets to use its response.
-    def response_name(args)
-      index = args.index('as:')
-      args[index + 1] if index
+    # 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
+    end
+
+    # Run alone, only the endpoint that ran is checked. One without a response or a status hasn't run, so it has nothing
+    # to check, while one that ran has a status even when its body is empty.
+    def check(args, directive:, body:, status:)
+      return if (@only && directive != @only) || (body.strip.empty? && status.nil?)
+
+      location = [@path, directive + 1].compact.join(':')
+      @failures.concat(args.failures(body:, status:).map { "#{location}: #{it}" })
     end
 
     def run?(output, directive)
@@ -93,21 +114,29 @@ module Raindown
     end
 
     # Replaces the output block and the date it was fetched, or with no block, replaces nothing just after the curl block.
-    def write_output(curl:, output:, name:)
-      body, language = Curl.run(curl[:body], @variables)
-      @variables.remember(name, body)
-      block = [*output_block(body, language), fetched]
+    # 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)])
+    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.
+      raise Curl::Error, message if @only
+
+      warn "Endpoint failed: #{message}"
+      curl[:close]
+    end
+
+    # 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 + block.length - 1
-    rescue Curl::Error => e
-      # The one endpoint that was asked for fails for the caller to show, like in the terminal UI.
-      raise if @only
-
-      warn "Endpoint failed: #{e.message}"
-      curl[:close]
     end
 
     # The output block, and the line after it when that's the date it was last fetched.
@@ -116,8 +145,8 @@ module Raindown
       @lines[output[:close] + 1]&.match?(FETCHED) ? length + 1 : length
     end
 
-    def fetched
-      "<!-- raindown:fetched #{Date.today.iso8601} -->\n"
+    def fetched(response)
+      "<!-- raindown:fetched #{Date.today.iso8601} · #{response.status} · #{response.milliseconds} ms -->\n"
     end
 
     # The fence is longer than any run of backticks in the body, so the body can't close it.

data/lib/raindown/endpoint/endpoint_variables.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'yaml'
+require 'antlers/api'
 require_relative '../front_matter'
 require_relative 'curl'
 
@@ -15,15 +16,22 @@ module Raindown
   #     base_url: http://localhost:3000
   #   staging:
   #     base_url: https://staging.example.com
+  # Secrets go in environments.local.yml beside it, which git ignores, and which adds to and overrides its environments.
+  # Its values and env's are secret, so a response or error that echoes one is written with its placeholder instead.
   class EndpointVariables
     class Error < Curl::Error; end
 
     FILE = 'environments.yml'
+    LOCAL_FILE = 'environments.local.yml'
+    # Shorter values, like a port or a flag, would be replaced wherever they happen to appear in a response.
+    SECRET_LENGTH = 4
     PLACEHOLDER = /\{([A-Za-z_][\w.-]*)\}/
 
     def initialize(path:, content:)
       @path = path
       @content = content
+      @local_names = []
+      @secrets = {}
     end
 
     # Keeps a named endpoint's response, as its JSON's data when it's JSON, or else its text.
@@ -41,15 +49,22 @@ module Raindown
     # placeholders are replaced once, so an environment can read secrets like {env.TOKEN}.
     def substitute(text, depth: 1)
       text.gsub(PLACEHOLDER) do |placeholder|
-        value = value(Regexp.last_match(1))
+        name = Regexp.last_match(1)
+        value = value(name)
         next placeholder if value.nil?
         next value.to_json if value.is_a?(Hash) || value.is_a?(Array)
-        next substitute(value, depth: 0) if depth.positive? && value.is_a?(String)
 
-        value.to_s
+        value = depth.positive? && value.is_a?(String) ? substitute(value, depth: 0) : value.to_s
+        @secrets[value] = placeholder if secret?(name) && value.length >= SECRET_LENGTH
+        value
       end
     end
 
+    # The text with each secret that was filled in put back as its placeholder, like {env.TOKEN}, longest first.
+    def redact(text)
+      @secrets.keys.sort_by { -it.length }.reduce(text) { |redacted, secret| redacted.gsub(secret, @secrets[secret]) }
+    end
+
     private
 
     # Read when they're first needed, so a file without endpoints doesn't need its environment.
@@ -59,22 +74,38 @@ module Raindown
 
     def environment
       folder = @path && Nodes.find_folder(File.dirname(File.expand_path(@path)))
-      file = folder && File.join(folder, FILE)
-      return {} unless file && File.exist?(file)
+      return {} unless folder
+
+      shared, local = [FILE, LOCAL_FILE].map { environments(File.join(folder, it)) }
+      return {} if shared.empty? && local.empty?
+
+      name = environment_name(shared, local)
+      @local_names = local.fetch(name, {}).keys
+      shared.fetch(name, {}).merge(local.fetch(name, {}))
+    end
+
+    # The one --env or RAINDOWN_ENV names, or else the first.
+    def environment_name(shared, local)
+      name = ENV.fetch('RAINDOWN_ENV') { (shared.keys + local.keys).first }
+      return name if shared.key?(name) || local.key?(name)
 
-      environments = YAML.safe_load_file(file) || {}
-      name = ENV.fetch('RAINDOWN_ENV') { environments.keys.first }
-      environments.fetch(name) { raise Error, "There's no #{name} environment in #{file}" }
+      raise Error, "There's no #{name} environment in #{Nodes::FOLDER}/#{FILE}"
+    end
+
+    def environments(file)
+      return {} unless File.exist?(file)
+
+      YAML.safe_load_file(file) || {}
+    end
+
+    def secret?(name)
+      first = name.split('.').first
+      first == 'env' || @local_names.include?(first)
     end
 
     # A value by its path, like login.token or users.0.id.
     def value(name)
-      name.split('.').reduce(values) do |value, key|
-        case value
-        when Hash then value.fetch(key) { value[key.to_sym] }
-        when Array then value[Integer(key, exception: false) || value.length]
-        end
-      end
+      Antlers::Queries.read_path(value: values, path: name.split('.'))
     end
   end
 end

data/lib/raindown/endpoint/schema_block.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative '../nodes'
+
+module Raindown
+  # A schema named for endpoints to check their responses against: a schema directive with its fields below it,
+  # indented, which become a LowType Schema[], where a key with no type holds the more indented fields below it:
+  #   <!-- schema: 'User'          schema: 'User'
+  #     name: String                 name: String
+  #     address:                     address:
+  #       city: String                 city: String
+  #   -->
+  # is Schema[name: String, address: Schema[city: String]]. Bare, in a Raindown file, its fields end at the first line
+  # that isn't indented. An endpoint below it names it, like schema: 'User' or schema: Array[User], as can a schema.
+  # Schemas in the project's .raindown/schemas.rd, written the same way, are named for every file's endpoints.
+  class SchemaBlock < Data.define(:name, :fields, :last)
+    # The name is quoted or not, like 'User' or User.
+    COMMENT = /\A {0,3}<!--\s*schema:\s*(['"]?)([A-Z]\w*)\1\s*$/
+    BARE = /\A {0,3}schema:\s*(['"]?)([A-Z]\w*)\1\s*$/
+    FIELD = /\A([ \t]*)(\S+:)[ \t]*(.*?)\s*\z/
+    FILE = 'schemas.rd'
+
+    # The schema starting at index, or nil when the line doesn't start one.
+    def self.at(lines, index, bare: false)
+      if (name = lines[index][COMMENT, 2])
+        close = (index + 1...lines.length).find { lines[it].strip == '-->' }
+        new(name:, fields: lines[index + 1...close], last: close) if close
+      elsif bare && (name = lines[index][BARE, 2])
+        last = index
+        last += 1 while lines[last + 1]&.match?(/\A[ \t]+\S/)
+        new(name:, fields: lines[index + 1..last], last:)
+      end
+    end
+
+    # The schemas in the project's .raindown/schemas.rd, by name.
+    def self.shared(path)
+      folder = path && Nodes.find_folder(File.dirname(File.expand_path(path)))
+      file = folder && File.join(folder, FILE)
+      return {} unless file && File.exist?(file)
+
+      lines = File.readlines(file)
+      schemas = {}
+      index = 0
+
+      while index < lines.length
+        if (block = at(lines, index, bare: true))
+          schemas[block.name] = resolve(block.type, schemas)
+          index = block.last
+        end
+        index += 1
+      end
+
+      schemas
+    end
+
+    # A schema: argument with the schemas it names written out, like Array[User] as Array[Schema[name: String]].
+    def self.resolve(text, schemas)
+      text = text.strip
+      text = text[1...-1] if text.match?(/\A(['"]).*\1\z/)
+      text.gsub(/\b[A-Z]\w*\b/) { schemas.fetch(it, it) }
+    end
+
+    # Each field's indent, key and type, as Schema[key: Type].
+    def self.type(fields)
+      pairs = []
+
+      until fields.empty?
+        indent, key, value = fields.shift
+        nested = []
+        nested << fields.shift while fields.first && fields.first[0].length > indent.length
+        value = type(nested) if nested.any?
+        pairs << "#{key} #{value}"
+      end
+
+      "Schema[#{pairs.join(', ')}]"
+    end
+
+    def type
+      self.class.type(fields.filter_map { it.match(FIELD)&.captures })
+    end
+  end
+end

data/lib/raindown/markdown_nodes.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'front_matter'
+require_relative 'node'
+require_relative 'variables'
+
+module Raindown
+  # Markdown Components, the .md and .rd files in a project's .raindown folder named like a component, like BookCard.md,
+  # which write their Markdown with their props as variables, so they need no code:
+  #   ---                          BookCard: title: Dune rating: 5
+  #   rating: 0
+  #   ---
+  #   **{title}** {rating}/5
+  # Its front matter is its props' defaults, and a value before its props, like Dune in BookCard: Dune, is {value}.
+  # Its template is read each time it's written, so changing it changes the next render.
+  module MarkdownNodes
+    EXTENSIONS = %w[.md .rd].freeze
+    NAME = /\A[A-Z]\w*\z/
+
+    module_function
+
+    def load(folder)
+      Dir.glob(EXTENSIONS.map { "*#{it}" }, base: folder).each do |file|
+        name = File.basename(file, '.*')
+        node_classes[name] ||= MarkdownNode.for(name:, path: File.join(folder, file)) if name.match?(NAME)
+      end
+    end
+
+    # 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
+
+    def node_class(name)
+      node_classes[name]
+    end
+
+    def node_classes
+      @node_classes ||= {}
+    end
+  end
+
+  # A Markdown Component, made with its props, which writes its template's Markdown.
+  class MarkdownNode < Node
+    def self.for(name:, path:)
+      Class.new(self) do
+        define_singleton_method(:name) { name }
+        define_singleton_method(:path) { path }
+      end
+    end
+
+    def initialize(value = nil, **props)
+      super()
+      @props = props
+      @props = { value:, **props } unless value.nil?
+    end
+
+    # 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)
+      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:)
+      Variables.unwrap(markdown.sub(/\A(?:[ \t]*\n)+/, '').rstrip)
+    end
+  end
+end

data/lib/raindown/node_blocks.rb

@@ -21,6 +21,7 @@ module Raindown
   # 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
 
     NAME = "(?:#{Nodes::BUILT_INS.keys.join('|')}|[A-Z]\\w*(?:::[A-Z]\\w*)*)".freeze
     OPEN = /\A( {0,3})<\{\s*(#{NAME}):(?:\s+(.*?))?\s*\}>[ \t]*$/
@@ -28,11 +29,13 @@ module Raindown
     BARE_OPEN = /\A( {0,3})(#{NAME}):(?:[ \t]+(.*?))?[ \t]*$/
     SELF_CLOSING = /\A( {0,3})<\{\s*:(#{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)/
     # A prop is name=value or name: value, where the value is quoted text, a number, true, false
-    # or a variable like author.name.
-    PROP = /(\w+)(?:=|:[ \t]+)("[^"]*"|'[^']*'|\S+)/
+    # or a variable like author.name. After name= it's one word.
+    PROP = /(\w+)(?:=|:[ \t]+)("[^"]*"|'[^']*'|(?<==)\S+|#{UNQUOTED})/
     # A value before the props is the node's argument.
-    ARG = /\A("[^"]*"|'[^']*'|[^\s"']\S*)(?:\s+|\z)/
+    ARG = /\A("[^"]*"|'[^']*'|[^\s"']#{UNQUOTED}|[^\s"'])(?:\s+|\z)/
 
     module_function
 
@@ -43,7 +46,8 @@ module Raindown
       variables = Variables.new(front_matter)
 
       spans(lines, bare:).map do |span|
-        span.except(:name, :class, :args).merge(node: Nodes.instance(span[:class], *args(span[:args], variables)))
+        node = Nodes.instance(span[:class], *args(span[:args], variables, antlers: span[:antlers]))
+        span.except(:name, :class, :args, :antlers).merge(node:)
       end
     end
 
@@ -99,7 +103,7 @@ module Raindown
       found, pattern = directive(lines[index], bare:)
       return unless found && (klass = Nodes.node_class(found[2]))
 
-      span = { name: found[2], class: klass, args: found[3].to_s }
+      span = { name: found[2], class: klass, args: found[3].to_s, antlers: %i[open self_closing].include?(pattern) }
       case pattern
       when :open, :comment_open
         end_tag(lines, index, found[2], comment: pattern == :comment_open)
@@ -141,21 +145,30 @@ module Raindown
     end
 
     # The props, after a value that's the node's argument when it comes first, like 'data.csv' in chart: 'data.csv'.
-    def args(text, variables)
+    def args(text, variables, antlers: true)
       arg = text.match(ARG) unless text.match?(/\A#{PROP}/)
-      return [props(text, variables)] unless arg
+      return [props(text, variables, antlers:)] unless arg
 
-      [props(arg.post_match, variables), [value(arg[1], variables)]]
+      [props(arg.post_match, variables, antlers:), [value(arg[1], variables, antlers:)]]
     end
 
-    def props(text, variables)
-      text.scan(PROP).to_h { |name, value| [name.to_sym, value(value, variables)] }
+    # Text that isn't a prop, like world in title: 'Hello' world or tag=a b, is an error rather than left out.
+    def props(text, variables, antlers: true)
+      unread = text.gsub(PROP, '').split
+      raise BrokenText, "Can't read #{unread.join(' ')} in #{text.strip}. Text with spaces needs quotes" if unread.any?
+
+      text.scan(PROP).to_h { |name, value| [name.to_sym, value(value, variables, antlers:)] }
     end
 
-    # A value, like 'text', 3, true, nil or :draft, or else a variable, like author.name.
-    def value(value, variables)
+    # 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,
+    # and only one in braces is a variable, like {author.name}.
+    def value(value, variables, antlers: true)
       Lowkey::ValueParser.parse(value) do
         next value[1..-2] if value.match?(/\A(["']).*\1\z/)
+        next Variables.value(variables, value[1..-2]) if !antlers && value.match?(/\A\{.+\}\z/)
+        next value unless antlers
+        raise BrokenText, "Can't read #{value} as a variable. Text with spaces needs quotes" if value.match?(/\s/)
 
         Variables.value(variables, value)
       end

data/lib/raindown/nodes.rb

@@ -3,13 +3,15 @@
 require_relative 'chart/chart'
 require_relative 'files'
 require_relative 'js/js_nodes'
+require_relative 'markdown_nodes'
 require_relative 'node'
 require_relative 'stat'
 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 Components, if any.
+  # 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.
   module Nodes
@@ -31,6 +33,7 @@ module Raindown
       loaded << folder
       dirload(folder)
       JSNodes.load(folder)
+      MarkdownNodes.load(folder)
     end
 
     def find_folder(directory)
@@ -56,12 +59,12 @@ module Raindown
       loaded_class(BUILT_INS[name]) || Raindown.const_get(BUILT_INS[name])
     end
 
-    # A Ruby node of the name, or else a JavaScript one.
+    # 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)
       return klass if node?(klass)
 
-      JSNodes.node_class(name)
+      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,

data/lib/raindown/pages.rb

@@ -13,23 +13,49 @@ 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
@@ -39,10 +65,6 @@ module Raindown
       @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:) }
     end
 
     # The files with any of the tags, like list(folder: 'basics') or list(tags: 'ruby'), sorted by order.
@@ -53,21 +75,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
+      process_files unless @metadata
+      @metadata
+    end
+
+    def tags
+      process_files unless @tags
+      @tags
+    end
+
+    def process_files
+      @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 +151,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

data/lib/raindown/projects.rb

@@ -69,7 +69,8 @@ module Raindown
 
     # Whether a file is one of a project's own nodes, which load when its watcher starts.
     def node?(path, root:)
-      File.expand_path(path).start_with?(File.join(root, Nodes::FOLDER, '')) && NODE_EXTENSIONS.include?(File.extname(path))
+      File.expand_path(path).start_with?(File.join(root, Nodes::FOLDER, '')) &&
+        (NODE_EXTENSIONS.include?(File.extname(path)) || MarkdownNodes.file?(path))
     end
 
     # The roots that aren't inside another of them, as a project's code includes the projects inside it.