raindown 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d8b4a4baae078b6b14f7ae6fd66dde441f97776e7107a07864ca4c12beebb74
-  data.tar.gz: 582a5012c02638f89991497cc789ef9513e7c13262445784c40ddb026b246574
+  metadata.gz: 1dffe3184c451794454149de18701ac6bd1afc2674b6a41385773d0f052bb2e5
+  data.tar.gz: 4e49463244dffc8e9b39873e2137f072f8632daec02c314d928fe09bbb115fd5
 SHA512:
-  metadata.gz: 1e8fc0825e5462616ce435e35188f5d41b45b23fdbbb59ff840c140cf46279de4a0e696def346a92f168dc6e04e97d1bcac9e309b1db3d9219fe59eeaadad52a
-  data.tar.gz: 5025d3381c0e0e2049a6b5fe462102438226feaa2d1a563c89b34dde74b1679163071d4df43e61d3a261e489ed71a107ae925db7f4cf08f1b9e83e773b45b46c
+  metadata.gz: 9502a0acb5cca634c884f74b8f2fc3e3a83c3fbe5bc635df7fccb779147718563a0a44679b3b3e6a1cf9da9e691026ff55953fc9a6b0aafad9cc48444eec12c6
+  data.tar.gz: dc928865b0da23c1b3dd67d859e94a3e718fe370b3d21d9344060cd5019e82fd5cce029b56d6008632690f9f1cc6f782cd41a8c38ca6d233bd06336f29fb7077

data/lib/raindown/actions.rb

@@ -12,6 +12,7 @@ module Raindown
   # Each returns true when the file changed, and raises when it can't, for the tool to show.
   module Actions
     class NotAnEndpoint < StandardError; end
+    class FailedCheck < StandardError; end
 
     # Editors that open a file at a line with "path:line" rather than "+line path".
     PATH_LINE_EDITORS = %w[hx helix subl zed].freeze
@@ -26,17 +27,22 @@ module Raindown
       Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
     end
 
-    # Runs one endpoint's request and writes its response, replacing any response it had.
+    # Runs one endpoint's request and writes its response, replacing any response it had, then raises when the response
+    # fails its checks, like status: 200.
     def execute(path, directive)
-      raise NotAnEndpoint, "#{directive.name} on line #{directive.line} isn't an endpoint" unless directive.endpoint?
-      raise NotAnEndpoint, "The endpoint on line #{directive.line} only renders, so put it in comments to run it" unless directive.writes
-
+      check_runnable(directive)
       content = Utils.read_markdown(path)
-      rewritten = EndpointRunner.new(content:, path:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1).rewrite
-      return false if rewritten == content
+      runner = EndpointRunner.new(content:, path:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1)
+      rewritten = runner.rewrite
+      File.write(path, rewritten) unless rewritten == content
+      raise FailedCheck, runner.failures.join("\n") if runner.failures.any?
 
-      File.write(path, rewritten)
-      true
+      rewritten != content
+    end
+
+    def check_runnable(directive)
+      raise NotAnEndpoint, "#{directive.name} on line #{directive.line} isn't an endpoint" unless directive.endpoint?
+      raise NotAnEndpoint, "The endpoint on line #{directive.line} only renders, so put it in comments to run it" unless directive.writes
     end
 
     # The command that opens the file at a line in the person's editor, like ["vim", "+12", "notes.md"].

data/lib/raindown/bare_directives.rb

@@ -2,6 +2,7 @@
 
 require_relative 'code_blocks'
 require_relative 'directives'
+require_relative 'endpoint/schema_block'
 require_relative 'front_matter'
 
 module Raindown
@@ -10,6 +11,8 @@ module Raindown
   # matter, or with the --bare flag. Nodes like toc: and files: 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.
+  #
   # 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:
   #   <!-- endpoint: -->
@@ -65,6 +68,9 @@ module Raindown
     # Returns the index of the last line it handled. That's the directive itself, so the lines it holds
     # are expanded too, and a bare directive inside it closes before it does.
     def expand_line(lines, index)
+      schema = SchemaBlock.at(lines, index, bare: true)
+      return expand_schema(lines, index, schema) if schema
+
       match = lines[index].match(LINE)
       return index unless match
 
@@ -73,6 +79,14 @@ module Raindown
       index
     end
 
+    # Returns the index of the code block's last line.
+    def expand_schema(lines, index, schema)
+      indent = schema.fields.first.to_s[/\A[ \t]*/]
+      block = [Directives.marker(lines[index], shown: true), "\n```\n", *schema.fields.map { it.delete_prefix(indent) }, "```\n"]
+      lines[index..schema.last] = block
+      index + block.length - 1
+    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

data/lib/raindown/cli.rb

@@ -5,7 +5,9 @@ require 'trees'
 require_relative '../raindown'
 require_relative '../version'
 require_relative 'blueprints'
+require_relative 'editing'
 require_relative 'rewriter'
+require_relative 'server'
 require_relative 'watcher/file_watcher'
 require_relative 'watcher/supervisor'
 
@@ -28,16 +30,22 @@ module Raindown
                             PATH is a file, or a directory (default: current directory) whose projects with a
                             .raindown folder are watched
         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
                             UI's Blueprints page, as a Stop hook that's given the hook's JSON
 
       Options:
-        --html [OUTPUT]     Render FILE to HTML once, writing to OUTPUT or else printing to stdout
+        --html [OUTPUT]     Render FILE to HTML once, writing to OUTPUT, or to stdout without one or with -, then exit with 1
+                            if its endpoint responses fail their status: or schema: checks
         --stdin             Render Markdown from stdin to HTML once, without formatting FILE, which only needs
                             its extension (to allow bare directives) and can be unsaved. Add --html OUTPUT to write a file
+        --rewrite           With --stdin, print its Markdown as it would be written back to FILE, without writing
+                            FILE, for editors like Obsidian. Add -x to run its endpoints
         --bare              Allow bare directives like :toc in Markdown files
         -x, --execute       Run endpoint curl snippets that have no output yet, as files are written back
-        --env NAME          Fill endpoint snippets from the NAME environment in .raindown/environments.yml
+        --env NAME          Fill endpoint snippets from the NAME environment in .raindown/environments.yml and
+                            environments.local.yml
         -h, --help          Show this message
         -v, --version       Show the version
 
@@ -53,9 +61,11 @@ module Raindown
 
     # 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.
-    line(':path') do |path, html: nil, stdin: false, bare: false, execute: false, x: false, env: nil| # rubocop:disable Metrics/ParameterLists -- each keyword is a flag
+    line(':path') do |path, html: nil, stdin: false, rewrite: false, bare: false, execute: false, x: false, env: nil| # rubocop:disable Metrics/ParameterLists -- each keyword is a flag
       execute do
         ENV['RAINDOWN_ENV'] = env if env
+        next rewrite_stdin(path, bare:, execute: execute || x) if stdin && rewrite
+
         open_path(path, html:, stdin:, bare:, execute: execute || x)
       end
     end
@@ -87,6 +97,7 @@ module Raindown
       if argv.intersect?(%w[-v --version]) then puts(VERSION)
       elsif argv.first == 'init' && argv.size <= 2 then init(argv[1])
       elsif argv == ['blueprints'] then Blueprints.save(JSON.parse($stdin.read))
+      elsif argv == ['server'] then serve
       else return false
       end
 
@@ -108,8 +119,10 @@ module Raindown
 
       FileUtils.mkdir_p(folder)
       File.write(config, CONFIG)
+      gitignore = File.join(folder, '.gitignore')
+      File.write(gitignore, "#{EndpointVariables::LOCAL_FILE}\n") unless File.exist?(gitignore)
       puts "Created #{config}"
-      puts 'Put your own nodes in the same folder. See https://raindown.dev/docs/nodes'
+      puts 'Put your own nodes in the same folder. See https://raindown.dev/docs/components'
     end
 
     # The terminal UI loads curses, so it's only required when it starts. Without a terminal, the path's watched instead.
@@ -123,9 +136,9 @@ module Raindown
     class << self
       private
 
-      # Endpoints run while formatting, which --stdin skips, so -x can't go with it.
+      # 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 html == true
+        output = html unless [true, '-'].include?(html)
         abort("-x runs endpoints as the file's formatted, which --stdin doesn't do\n\n#{USAGE}") if stdin && execute
         return render_stdin(path, output, bare:) if stdin
         return render(path, output, bare:, execute:) if html
@@ -141,12 +154,28 @@ module Raindown
         metadata = Pages.for(path)
         Rewriter.update(path:, bare:, execute:, metadata:)
         write(output, Raindown.render_file(path:, bare:, metadata:))
+        check_endpoints(path, bare:)
+      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:)
+        return if failures.empty?
+
+        warn(*failures.map { "Endpoint check failed: #{it}" })
+        exit 1
+      end
+
+      # The Markdown from stdin written back as it would be to the file, and its failed endpoint checks, for an editor
+      # to apply to what it's editing.
+      def rewrite_stdin(path, bare:, execute:)
+        rewritten = Editing.rewrite_markdown($stdin.read, path:, bare:, execute:)
+        $stdout.write(rewritten[:output])
+        warn(*rewritten[:warnings])
       end
 
       def render_stdin(path, output = nil, bare: false, **)
-        Nodes.load(path)
-        write(output, Raindown.render(markdown: $stdin.read, metadata: Pages.for(path), bare: bare || BareDirectives.file?(path),
-                                      **Config.render_options(path)))
+        write(output, Editing.render_markdown($stdin.read, path:, bare:))
       end
 
       # Watching only writes back to the files, while --html and --stdin render HTML.
@@ -158,6 +187,13 @@ module Raindown
         Watcher::FileWatcher.new(path:, bare:, execute:).start
       end
 
+      # The answers have stdout to themselves, so what nodes print goes to stderr.
+      def serve
+        output = $stdout.dup
+        $stdout.reopen($stderr)
+        Server.new(output:).start
+      end
+
       def write(output, html)
         output ? File.write(output, html) : puts(html)
       end

data/lib/raindown/directives.rb

@@ -31,16 +31,20 @@ module Raindown
     # Whether the directive's line is bare, without delimiters, so it shows in bold.
     def bare?(line) = text(line) == line.strip
 
-    # A directive's line as a marker: in bold when it's shown, like a bare directive, or else hidden.
+    # A directive's line as a marker: in bold when it's shown, like a bare directive, or else hidden. Its braces are
+    # hidden from Antlers like code's, so a shown chart: {stats} shows as it's written.
     def marker(line, shown: bare?(line))
-      text = text(line).gsub('--', '- -')
+      text = text(line).gsub('--', '- -').gsub(/[{}]/, CODE_BRACES)
       return "<!-- raindown:hidden #{text} -->" unless shown
 
       "<!-- raindown:directive #{text} -->"
     end
 
+    # The braces' entities, like code's, are kept as they are.
     def render(html)
-      html.gsub(HIDDEN, '').gsub(MARKER) { "<p><strong>#{CGI.escapeHTML(::Regexp.last_match(1).to_s)}</strong></p>" }
+      html.gsub(HIDDEN, '').gsub(MARKER) do
+        "<p><strong>#{CGI.escapeHTML(::Regexp.last_match(1).to_s).gsub(/&amp;(#12[35];)/, '&\1')}</strong></p>"
+      end
     end
   end
 end

data/lib/raindown/editing.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../raindown'
+require_relative 'rewriter'
+
+module Raindown
+  # What an editor asks of Raindown about Markdown it's editing, which needn't be saved: its HTML, or the Markdown as it
+  # would be written back to the file, with its failed endpoint checks. "raindown FILE --stdin" and "raindown server"
+  # both answer with it.
+  module Editing
+    module_function
+
+    def render_markdown(markdown, path:, bare: false)
+      Nodes.load(path)
+      Raindown.render(markdown:, metadata: Pages.for(path), bare: bare || BareDirectives.file?(path), **Config.render_options(path))
+    end
+
+    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}" } }
+    end
+  end
+end

data/lib/raindown/endpoint/curl.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 require 'ipaddr'
-require 'json'
 require 'open3'
 require 'shellwords'
 require 'socket'
 require 'uri'
+require_relative 'curl_response'
 
 module Raindown
   # Runs a curl snippet with the curl binary. There's no shell, so pipes, redirects and variables don't apply.
@@ -48,28 +48,17 @@ module Raindown
       '--data-urlencode' => :no_urlencoded_file
     }.freeze
 
-    # Separates the response body from the content type that --write-out appends.
-    TYPE_MARKER = "\n--raindown-content-type--"
-    WRITE_OUT = "#{TYPE_MARKER}%{content_type}".freeze # rubocop:disable Style/FormatStringToken -- curl's syntax, not Ruby's
-    LANGUAGES = {
-      /json/ => 'json', /xml/ => 'xml', /html/ => 'html', /javascript/ => 'javascript',
-      /css/ => 'css', /yaml/ => 'yaml', %r{\Atext/plain} => 'text'
-    }.freeze
-
     module_function
 
-    # Returns the response body and the code block language for its content type.
+    # Returns the Response, with the code block language for its content type.
     # Placeholders like {base_url} are replaced from the variables, word by word, so a value can't add options.
     def run(snippet, variables = nil)
       args = arguments(snippet, variables)
       stdout, stderr, status = Open3.capture3('curl', *SAFE_OPTIONS, '--silent', '--show-error', '--max-time', TIMEOUT,
-                                              *resolve_options(args), *args, '--write-out', WRITE_OUT)
+                                              *resolve_options(args), *args, '--write-out', Response::WRITE_OUT)
       raise Error, stderr.strip.empty? ? "curl exited with #{status.exitstatus}" : stderr.strip unless status.success?
 
-      body, _, content_type = stdout.rpartition(TYPE_MARKER)
-      language = language(content_type)
-
-      [language == 'json' ? pretty_json(body) : body, language]
+      Response.parse(stdout)
     rescue Errno::ENOENT
       raise Error, 'curl is not installed'
     end
@@ -213,15 +202,5 @@ module Raindown
     rescue SocketError => e
       raise Error, "Can't resolve #{host}: #{e.message}"
     end
-
-    def language(content_type)
-      LANGUAGES.find { |pattern, _| content_type.match?(pattern) }&.last || ''
-    end
-
-    def pretty_json(body)
-      JSON.pretty_generate(JSON.parse(body))
-    rescue JSON::ParserError
-      body
-    end
   end
 end

data/lib/raindown/endpoint/curl_response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Raindown
+  module Curl
+    # A response's body, its code block language, and its status code and time, like 200 in 142 milliseconds,
+    # read from what curl prints with --write-out WRITE_OUT.
+    class Response < Data.define(:body, :language, :status, :milliseconds)
+      # Separates the response body from the status, time and content type that --write-out appends.
+      INFO_MARKER = "\n--raindown-response-info--"
+      WRITE_OUT = "#{INFO_MARKER}%{http_code} %{time_total} %{content_type}".freeze # rubocop:disable Style/FormatStringToken -- curl's syntax, not Ruby's
+      LANGUAGES = {
+        /json/ => 'json', /xml/ => 'xml', /html/ => 'html', /javascript/ => 'javascript',
+        /css/ => 'css', /yaml/ => 'yaml', %r{\Atext/plain} => 'text'
+      }.freeze
+
+      # JSON is pretty-printed, and other bodies are kept as they are.
+      def self.parse(stdout)
+        body, _, info = stdout.rpartition(INFO_MARKER)
+        status, seconds, content_type = info.split(' ', 3)
+        language = LANGUAGES.find { |pattern, _| content_type.to_s.match?(pattern) }&.last || ''
+
+        new(body: language == 'json' ? pretty_json(body) : body, language:, status: status.to_i,
+            milliseconds: (seconds.to_f * 1000).round)
+      end
+
+      def self.pretty_json(body)
+        JSON.pretty_generate(JSON.parse(body))
+      rescue JSON::ParserError
+        body
+      end
+    end
+  end
+end

data/lib/raindown/endpoint/endpoint_args.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'schema_block'
+
+module Raindown
+  # An endpoint directive's arguments: as: names its response for later snippets, and status: and schema: are what its
+  # response is checked against, like "as: user status: 200 schema: Schema[id: Integer, email: String | nil]".
+  # A schema is a LowType type, read without running it, and is written with Schema[] rather than {}, which Antlers reads,
+  # or names a SchemaBlock, like schema: 'User' or schema: Array[User].
+  class EndpointArgs < Data.define(:name, :status, :schema)
+    KEYWORDS = %w[as: status: schema:].freeze
+
+    def self.parse(text, schemas: {})
+      values = keyword_values(text.to_s)
+      new(name: values['as'], status: values['status']&.then { Integer(it, exception: false) },
+          schema: values['schema']&.then { SchemaBlock.resolve(it, schemas) })
+    end
+
+    # Each keyword's words, up to the next keyword outside brackets, so a schema's own keys, like Schema[status: Integer],
+    # stay in it.
+    def self.keyword_values(text)
+      values = {}
+      key = nil
+      depth = 0
+
+      text.split.each do |word|
+        next values[key = word.delete_suffix(':')] = [] if depth.zero? && KEYWORDS.include?(word)
+        next unless key
+
+        values[key] << word
+        depth += word.count('[(') - word.count('])')
+      end
+
+      values.transform_values { it.join(' ') }
+    end
+
+    # What's wrong with a response, like "expected status 200, received 404" or "id: expected Integer, received "1"".
+    # A response fetched before statuses were kept has no status to check.
+    def failures(body:, status:)
+      failures = []
+      failures << "expected status #{self.status}, received #{status}" if self.status && status && status != self.status
+      failures.concat(schema_failures(body)) if schema
+      failures
+    end
+
+    private
+
+    # LowType is only loaded for an endpoint with a schema.
+    def schema_failures(body)
+      require 'lowtype'
+
+      Low::TypeParser.parse(schema).errors(data(body)).map do |node|
+        "#{node.path.to_s.empty? ? 'response' : node.path}: expected #{node.expected}, received #{node.received}"
+      end
+    rescue Low::ParseError => e
+      ["schema: #{e.message}"]
+    end
+
+    def data(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body.strip
+    end
+  end
+end

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,17 +34,28 @@ 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
     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
       @variables = EndpointVariables.new(path:, content:)
       @bare = bare
       @execute = execute
       @only = only
+      @failures = []
+      @schemas = SchemaBlock.shared(path)
     end
 
     def rewrite
@@ -51,6 +64,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 +83,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 +119,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 +150,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/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/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.

data/lib/raindown/server.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../version'
+require_relative 'editing'
+require_relative 'projects'
+require_relative 'workers/workers'
+
+module Raindown
+  # "raindown server" keeps Raindown loaded for editors, like the Obsidian plugin and the VS Code extension, so a render
+  # doesn't start Ruby again. Once it's ready, it says so, then answers a JSON request a line, in order:
+  #   {"ready": true, "version": "0.10.0"}
+  #   {"id": 1, "path": "/notes/a.md", "markdown": "<!-- toc: -->", "rewrite": true}
+  #   {"id": 1, "output": "<!-- toc: -->\n- ...", "warnings": []}
+  # Rewriting answers like --stdin --rewrite, with "execute" like -x, and otherwise it's HTML, like --stdin. An error's
+  # answered as {"id": 1, "error": "raindown: /notes/a.md: ..."}, like the CLI writes it.
+  # Each project renders in a worker of its own, which starts again when its .raindown folder changes, so its nodes,
+  # config and schemas are never stale. Without fork, as on Windows, node changes need the server started again.
+  class Server
+    def initialize(input: $stdin, output: $stdout)
+      @input = input
+      @output = output
+      @workers = Workers.new(root: Dir.pwd) { Editing }
+      @stamps = {}
+    end
+
+    def start
+      write(ready: true, version: VERSION)
+      @input.each_line { |line| write(answer(line)) }
+    ensure
+      @workers.stop
+    end
+
+    private
+
+    def answer(line)
+      request = JSON.parse(line)
+      { id: request['id'], **edit(request) }
+    rescue JSON::ParserError, KeyError => e
+      { id: request&.dig('id'), error: "raindown: #{e.message}" }
+    rescue Workers::Worker::Error => e
+      { id: request['id'], error: "raindown: #{request['path']}: #{e.message}" }
+    end
+
+    def edit(request)
+      path = File.expand_path(request.fetch('path'))
+      options = { path:, bare: request['bare'] == true }
+      worker = worker_for(path)
+      return worker.call(:rewrite_markdown, request.fetch('markdown'), **options, execute: request['execute'] == true) if request['rewrite']
+
+      { output: worker.call(:render_markdown, request.fetch('markdown'), **options) }
+    end
+
+    # The project's worker, started again first when a file in its .raindown folder was added, changed or removed.
+    def worker_for(path)
+      project = Projects.root(path) || @workers.root
+      @workers.restart(project) if nodes_changed?(project)
+      @workers[project]
+    end
+
+    def nodes_changed?(project)
+      stamp = Dir.glob(File.join(project, Nodes::FOLDER, '**', '*')).to_h { [it, File.mtime(it)] }
+      changed = @stamps.key?(project) && @stamps[project] != stamp
+      @stamps[project] = stamp
+      changed
+    end
+
+    def write(message)
+      @output.puts(JSON.generate(message))
+      @output.flush
+    end
+  end
+end

data/lib/raindown/tui/project.rb

@@ -90,8 +90,9 @@ module Raindown
 
       def endpoint(path, lines, directive)
         snippet = CodeBlocks.endpoint(lines, directive.line).first&.dig(:body)
-        request = Curl.request(snippet.to_s, EndpointVariables.new(path:, content: lines.join))
-        Endpoint.new(project: root, path:, line: directive.line, **request.to_h) if request
+        variables = EndpointVariables.new(path:, content: lines.join)
+        request = Curl.request(snippet.to_s, variables)
+        Endpoint.new(project: root, path:, line: directive.line, method: request.method, url: variables.redact(request.url)) if request
       end
 
       def charts_in(path)

data/lib/raindown/watcher/file_watcher.rb

@@ -51,7 +51,9 @@ module Raindown
 
       # The files' metadata is loaded again each time, so new and renamed files are listed.
       def rewrite
-        Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
+        changed = Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
+        EndpointRunner.failures(content: Utils.read_markdown(path), path:, bare:).each { warn "Endpoint check failed: #{it}" }
+        changed
       end
     end
   end

data/lib/raindown/watcher/project.rb

@@ -30,6 +30,8 @@ module Raindown
       def update(path)
         changed = Rewriter.update(path:, bare: @bare, execute: @execute, metadata: Pages.for(path))
         puts "[#{name}] Updated #{relative(path)}" if changed
+        EndpointRunner.failures(content: Utils.read_markdown(path), path:, bare: @bare)
+                      .each { warn "[#{name}] Endpoint check failed: #{it}" }
       rescue StandardError => e
         raise if ENV['RAINDOWN_DEBUG']
 

data/lib/raindown/wiki_links.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'code'
+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:
+  #   [[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>)
+  # A name matches a file's name, or the end of its path, like [[notes/Reading list]], without its extension and
+  # whatever its case. One that matches no file, and ones in code or front matter, are left as they are, as are
+  # embeds, like ![[photo.png]].
+  module WikiLinks
+    LINK = /(?<!!)\[\[([^\[\]|#\n]+)(?:#([^\[\]|\n]+))?(?:\|([^\[\]\n]+))?\]\]/
+
+    module_function
+
+    def to_markdown(markdown, metadata:)
+      return markdown unless markdown.include?('[[')
+
+      pages = metadata.list
+      links(markdown).reverse_each.with_object(markdown.b) do |link, bytes|
+        page = page_for(link[1], pages)
+        bytes[link.byteoffset(0)[0]...link.byteoffset(0)[1]] = markdown_link(link, page).b if page
+      end.force_encoding('UTF-8')
+    end
+
+    # The links in the Markdown, outside its code and front matter, as matches.
+    def links(markdown)
+      start = markdown.bytesize - FrontMatter.parse(markdown).last.bytesize
+      code = Code.ranges(markdown)
+      found = []
+
+      markdown.scan(LINK) do
+        link = ::Regexp.last_match
+        offset = link.byteoffset(0)[0]
+        found << link if offset >= start && code.none? { it.cover?(offset) }
+      end
+
+      found
+    end
+
+    # The page a name links to: one whose path without its extension is the name, or ends with it.
+    def page_for(name, pages)
+      name = name.strip.downcase.sub(/\.(?:md|rd|markdown|raindown)\z/, '')
+      stems = pages.to_h { [it, it.path.to_s.downcase.sub(%r{\.[^./]+\z}, '')] }
+
+      pages.find { stems[it] == name } || pages.find { stems[it].end_with?("/#{name}") }
+    end
+
+    def markdown_link(link, page)
+      name, heading, label = link.captures.map { it&.strip }
+      label ||= [name, heading].compact.join(' > ')
+      anchor = "##{anchor(heading)}" if heading
+
+      "[#{label.gsub(/[\[\]]/) { "\\#{it}" }}](<#{page.path}#{anchor}>)"
+    end
+
+    # A heading's id, the way Commonmarker makes it, like to-read for "To read".
+    def anchor(heading)
+      heading.downcase.gsub(/[^\p{Word}\- ]/, '').tr(' ', '-')
+    end
+  end
+end

data/lib/raindown.rb

@@ -17,6 +17,7 @@ require_relative 'raindown/pages'
 require_relative 'raindown/pre_renderer'
 require_relative 'raindown/utils'
 require_relative 'raindown/variables'
+require_relative 'raindown/wiki_links'
 
 module Raindown
   # Antlers evaluates any braces in the HTML, so braces in code are swapped for placeholders
@@ -83,6 +84,7 @@ module Raindown
   # 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:))
   end
 

data/lib/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - maedi
@@ -121,6 +121,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: lowtype
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: plugs
   requirement: !ruby/object:Gem::Requirement
@@ -211,9 +225,13 @@ files:
 - lib/raindown/config.rb
 - lib/raindown/directives.rb
 - lib/raindown/document.rb
+- lib/raindown/editing.rb
 - lib/raindown/endpoint/curl.rb
+- lib/raindown/endpoint/curl_response.rb
+- lib/raindown/endpoint/endpoint_args.rb
 - 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
@@ -221,6 +239,7 @@ files:
 - lib/raindown/heading_ids.rb
 - lib/raindown/js/host.mjs
 - lib/raindown/js/js_nodes.rb
+- lib/raindown/markdown_nodes.rb
 - lib/raindown/node.rb
 - lib/raindown/node_blocks.rb
 - lib/raindown/node_injector.rb
@@ -230,6 +249,7 @@ files:
 - lib/raindown/pre_renderer.rb
 - lib/raindown/projects.rb
 - lib/raindown/rewriter.rb
+- lib/raindown/server.rb
 - lib/raindown/stat.rb
 - lib/raindown/table_formatter.rb
 - lib/raindown/toc.rb
@@ -305,6 +325,7 @@ files:
 - lib/raindown/watcher/file_watcher.rb
 - lib/raindown/watcher/project.rb
 - lib/raindown/watcher/supervisor.rb
+- lib/raindown/wiki_links.rb
 - lib/raindown/workers/worker.rb
 - lib/raindown/workers/workers.rb
 - lib/version.rb