raindown 0.1.0 → 0.2.0

data/lib/raindown/rewriter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'node_injector'
+require_relative 'endpoint/endpoint_runner'
+require_relative 'table_formatter'
+
+module Raindown
+  # Rewrites the generated parts of a Markdown file in place before it's rendered:
+  # node output, like the TOC, endpoint responses and table alignment.
+  # Each rewriter responds to rewrite(content:, path:, bare:, execute:, metadata:) and returns the new content.
+  module Rewriter
+    REWRITERS = [NodeInjector, EndpointRunner, TableFormatter].freeze
+
+    module_function
+
+    def rewrite(content:, path:, bare: false, execute: false, metadata: NoMetadata)
+      REWRITERS.reduce(content) do |rewritten, rewriter|
+        rewriter.rewrite(content: rewritten, path:, bare:, execute:, metadata:)
+      end
+    end
+
+    # Returns true when the file changed.
+    def update(path:, bare: false, execute: false, metadata: NoMetadata)
+      content = File.read(path)
+      rewritten = rewrite(content:, path:, bare:, execute:, metadata:)
+      return false if rewritten == content
+
+      File.write(path, rewritten)
+      true
+    end
+  end
+end

data/lib/raindown/table_formatter.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'unicode/display_width'
+
+module Raindown
+  # Pads every column of each Markdown table to the width of its widest cell.
+  class TableFormatter
+    DELIMITER_CELL = /\A:?-+:?\z/
+    FENCE = /\A\s*(```|~~~)/
+
+    def self.rewrite(content:, **)
+      new(content:).format
+    end
+
+    def initialize(content:)
+      @lines = content.lines
+    end
+
+    def format
+      output = []
+      index = 0
+      in_fence = false
+
+      while index < @lines.length
+        line = @lines[index]
+        in_fence = !in_fence if line.match?(FENCE)
+
+        if !in_fence && table_start?(index)
+          table_end = find_table_end(index)
+          output.concat(align(@lines[index...table_end]))
+          index = table_end
+        else
+          output << line
+          index += 1
+        end
+      end
+
+      output.join
+    end
+
+    private
+
+    def table_start?(index)
+      header = @lines[index]
+      delimiter = @lines[index + 1]
+      return false unless header&.include?('|') && delimiter
+
+      delimiter_cells = cells(delimiter)
+      delimiter_cells.any? && delimiter_cells.all? { |cell| cell.match?(DELIMITER_CELL) } &&
+        delimiter_cells.length == cells(header).length
+    end
+
+    def find_table_end(index)
+      table_end = index + 2
+      table_end += 1 while @lines[table_end]&.include?('|') && !@lines[table_end].strip.empty?
+      table_end
+    end
+
+    def align(table)
+      indent = table.first[/\A\s*/]
+      rows = table.map { |line| cells(line) }
+      header, delimiter, *body = rows
+      return table if body.any? { |row| row.length > header.length }
+
+      table_lines(indent:, header:, body:, alignments: delimiter.map { |cell| alignment(cell) })
+    end
+
+    def table_lines(indent:, header:, body:, alignments:)
+      body = body.map { |row| row + ([''] * (header.length - row.length)) }
+      widths = column_widths(rows: [header, *body])
+
+      [
+        row_line(indent:, cells: header, widths:, alignments:),
+        delimiter_line(indent:, widths:, alignments:),
+        *body.map { |row| row_line(indent:, cells: row, widths:, alignments:) }
+      ].map { |line| "#{line}\n" }
+    end
+
+    # Split on pipes that aren't escaped, dropping the optional outer pipes.
+    def cells(line)
+      content = line.strip
+      content = content.delete_prefix('|')
+      content = content.delete_suffix('|') unless content.end_with?('\|')
+
+      content.split(/(?<!\\)\|/, -1).map(&:strip)
+    end
+
+    def alignment(cell)
+      if cell.start_with?(':') && cell.end_with?(':') then :center
+      elsif cell.end_with?(':') then :right
+      elsif cell.start_with?(':') then :left
+      end
+    end
+
+    # Three is the shortest delimiter cell, which also fits ':-:'.
+    def column_widths(rows:)
+      rows.transpose.map { |column| [column.map { |cell| display_width(cell) }.max, 3].max }
+    end
+
+    # Wide characters like CJK and emoji take two columns. Emoji are always measured as two,
+    # instead of guessing from the terminal, so a file formats the same on every machine.
+    def display_width(cell)
+      Unicode::DisplayWidth.of(cell, emoji: :all)
+    end
+
+    def row_line(indent:, cells:, widths:, alignments:)
+      padded = cells.each_with_index.map { |cell, i| pad(cell, widths[i], alignments[i]) }
+      "#{indent}| #{padded.join(' | ')} |"
+    end
+
+    def delimiter_line(indent:, widths:, alignments:)
+      dashes = widths.each_with_index.map do |width, i|
+        case alignments[i]
+        when :center then ":#{'-' * (width - 2)}:"
+        when :right then "#{'-' * (width - 1)}:"
+        when :left then ":#{'-' * (width - 1)}"
+        else '-' * width
+        end
+      end
+
+      "#{indent}| #{dashes.join(' | ')} |"
+    end
+
+    def pad(cell, width, alignment)
+      padding = width - display_width(cell)
+
+      case alignment
+      when :center then "#{' ' * (padding / 2)}#{cell}#{' ' * (padding - (padding / 2))}"
+      when :right then "#{' ' * padding}#{cell}"
+      else "#{cell}#{' ' * padding}"
+      end
+    end
+  end
+end

data/lib/raindown/toc.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'erb'
+require_relative 'node'
+
+module Raindown
+  # The node behind toc: and :toc, a table of contents of the document's headings.
+  # A project can replace it with its own TOC node in .raindown, like "class TOC < Raindown::TOC".
+  class TOC < Node
+    def replace(document:, metadata: NoMetadata, bare: false)
+      headings = Raindown.headings(markdown: document, metadata:, bare:)
+      return '' if headings.empty?
+
+      min_level = headings.map { |heading| heading[:level] }.min
+
+      headings.map do |heading|
+        "#{'  ' * (heading[:level] - min_level)}- [#{heading[:text]}](##{heading[:id]})"
+      end.join("\n")
+    end
+
+    def render(document:, metadata: NoMetadata, bare: false)
+      items = Raindown.headings(markdown: document, metadata:, bare:).map do |heading|
+        "<li class='h#{heading[:level]}'><a href='##{heading[:id]}'>#{ERB::Util.html_escape(heading[:text])}</a></li>"
+      end
+
+      <<~HTML
+        <div class="floating">
+          <details id="toc" open>
+            <summary>Table of contents</summary>
+            <ul>
+              #{items.join("\n")}
+            </ul>
+          </details>
+        </div>
+      HTML
+    end
+  end
+end

data/lib/raindown/variables.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Raindown
+  # The front matter values that Antlers variables like {title} and <{ title }> render.
+  # Antlers reads a variable from the binding's locals, then by sending it to the binding's receiver, which is this.
+  # It's a BasicObject so a key like "hash" or "display" isn't shadowed by a method, and unknown names render nothing.
+  # Nested values work too, like {author.name} and <{ for: tag in: tags }>.
+  class Variables < BasicObject
+    # Braces in a value become the placeholders that render as braces, so Antlers doesn't read them as a variable.
+    def self.wrap(value)
+      case value
+      when ::Hash then new(value)
+      when ::Array then value.map { |item| wrap(item) }
+      when ::String then value.gsub(/[{}]/, CODE_BRACES)
+      else value
+      end
+    end
+
+    def initialize(values)
+      @values = values.to_h { |key, value| [key.to_sym, Variables.wrap(value)] }
+    end
+
+    def respond_to?(name, _include_all = false) # rubocop:disable Style/OptionalBooleanParameter -- Ruby's signature
+      @values.key?(name.to_sym)
+    end
+
+    def send(name, *)
+      @values[name.to_sym]
+    end
+
+    def binding
+      ::Kernel.binding
+    end
+
+    def to_s
+      @values.to_s
+    end
+    alias inspect to_s
+
+    def method_missing(*)
+      nil
+    end
+
+    def respond_to_missing?(*)
+      false
+    end
+  end
+end

data/lib/raindown/watcher.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative '../raindown'
+require_relative 'rewriter'
+
+module Raindown
+  class Watcher
+    attr_reader :path, :output, :bare, :execute
+
+    def initialize(path:, output: nil, bare: false, execute: false)
+      @path = path
+      @output = output || default_output
+      @bare = bare
+      @execute = execute
+    end
+
+    def start
+      require 'listen'
+
+      $stdout.sync = true
+
+      rewrite
+      render
+      puts "Watching #{path} for changes (writing to #{output})..."
+
+      listener.start
+      sleep
+    end
+
+    private
+
+    def listener
+      directory = File.dirname(File.expand_path(path))
+      filename = File.basename(path)
+
+      Listen.to(directory) do |modified, added, _removed|
+        next unless (modified + added).any? { |f| File.basename(f) == filename }
+        # Formatting saves the file again, and that change triggers the render.
+        next if rewrite
+
+        render
+        puts "Re-rendered #{path} -> #{output}"
+      end
+    end
+
+    # 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))
+    end
+
+    def render
+      File.write(output, Raindown.render_file(path:, bare:, metadata: Pages.for(path)))
+    end
+
+    def default_output
+      "#{File.dirname(path)}/#{File.basename(path, '.*')}.html"
+    end
+  end
+end

data/lib/raindown.rb

@@ -1,31 +1,98 @@
 # frozen_string_literal: true
 
 require 'commonmarker'
+require 'antlers'
 require 'antlers/api'
+require 'nokogiri'
 require_relative 'elements'
+require_relative 'raindown/bare_directives'
+require_relative 'raindown/code'
+require_relative 'raindown/config'
+require_relative 'raindown/directives'
+require_relative 'raindown/front_matter'
+require_relative 'raindown/node_blocks'
+require_relative 'raindown/pages'
+require_relative 'raindown/pre_renderer'
+require_relative 'raindown/variables'
 
-module Rain
-  module Raindown
-    module_function
+module Raindown
+  # Antlers evaluates any braces in the HTML, so braces in code are swapped for placeholders
+  # then HTML entities, which browsers still display as braces.
+  CODE_BRACES = { '{' => "\u{E000}", '}' => "\u{E001}" }.freeze
+  CODE_BRACE_ENTITIES = { "\u{E000}" => '{', "\u{E001}" => '}' }.freeze
 
-    def render(markdown:, metadata: {})
-      template = markdown.gsub('<{', '<!-- ANTLERS').gsub('}>', 'ANTLERS -->')
+  # Front matter is metadata, so it's left out of the HTML and the headings.
+  MARKDOWN_OPTIONS = { extension: { alerts: true, front_matter_delimiter: '---' } }.freeze
+  # Directives are HTML comments until Antlers renders them, and escaped characters like "\#" stay plain text.
+  HTML_OPTIONS = { render: { unsafe: true, escaped_char_spans: false } }.freeze
 
-      doc = Commonmarker.parse(template.force_encoding('UTF-8'), options: { extension: { alerts: true } })
-      doc.walk do |node|
-        if %i[code code_block].include?(node.type)
-          node.string_content = node.string_content.gsub('<!-- ANTLERS', '<{').gsub('ANTLERS -->', '}>')
-        end
-      end
+  # Stands in for an app's metadata when there isn't any, so list: and files: list nothing.
+  module NoMetadata
+    def self.list(**) = []
+  end
+
+  # Headings with an id, which are the ones a table of contents links to.
+  HEADINGS = 'h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]'
+
+  module_function
+
+  def headings(markdown:, metadata: NoMetadata, bare: false)
+    html = html(markdown:, variables: variables(markdown:), metadata:, bare:)
+
+    Nokogiri::HTML(html).css(HEADINGS).map do |heading|
+      { level: heading.name[1].to_i, text: heading.text.strip, id: heading['id'] }
+    end
+  end
 
-      template = doc.to_html(options: { render: { unsafe: true } })
-      template = template.gsub('<!-- ANTLERS', '<{').gsub('ANTLERS -->', '}>')
+  # Directives show in bold, unless the file's project hides them in .raindown/config.yml.
+  def render_file(path:, metadata: NoMetadata, bare: false, hide_directives: Config.for(path)[:hide_directives])
+    render(markdown: File.read(path), metadata:, bare: bare || BareDirectives.file?(path), hide_directives:)
+  end
 
-      return template unless template.include?('<{') || template.include?('{')
+  # Front matter keys are variables, like {title} or <{ title }>.
+  # Directives like a node's show in bold, or as HTML comments with hide_directives.
+  def render(markdown:, metadata: NoMetadata, bare: false, hide_directives: false)
+    variables = variables(markdown:)
+    template = html(markdown:, variables:, metadata:, bare:)
+    context = { document: markdown, metadata:, bare: }
+
+    if template.include?('<{')
+      # Directives whose output is HTML. The rest rendered before Commonmarker, in PreRenderer.
+      ast = Antlers.ast(template:, elements: Antlers::Elements[:html, :prop, :slot] + Elements[:endpoint])
+      template = "#{Antlers.render(ast:, current_binding: variables.binding, metadata:).chomp}\n"
+    end
+
+    # Nodes and directives render last, so their HTML isn't read as Markdown or directives.
+    Directives.render(Nodes.render_placeholders(template, **context), hide: hide_directives)
+  end
+
+  # The HTML from Commonmarker, after PreRenderer and before the directives whose output is HTML.
+  def html(markdown:, variables:, metadata:, bare:)
+    markdown = NodeBlocks.to_rendered(markdown.dup.force_encoding('UTF-8'), metadata:, bare:)
+    markdown = PreRenderer.render(markdown, variables:, metadata:, bare:)
+    doc = Commonmarker.parse(hide_directives(markdown:), options: MARKDOWN_OPTIONS)
+    preserve_code(doc:)
+
+    doc.to_html(options: HTML_OPTIONS).gsub('<!-- ANTLERS', '<{').gsub('ANTLERS -->', '}>')
+       .gsub(/[\u{E000}\u{E001}]/, CODE_BRACE_ENTITIES)
+  end
+
+  def variables(markdown:)
+    Variables.new(FrontMatter.parse(markdown).first)
+  end
+
+  # Commonmarker escapes directives, so they're hidden in HTML comments until it's done.
+  def hide_directives(markdown:)
+    markdown.gsub('<{', '<!-- ANTLERS').gsub('}>', 'ANTLERS -->').force_encoding('UTF-8')
+  end
 
-      ast = Antlers.ast(template:, elements: Antlers::Elements[:html, :var, :prop, :slot, :if, :for] + Rain::Elements[:toc, :list])
+  # Restore directives in code and hide its braces from Antlers.
+  def preserve_code(doc:)
+    doc.walk do |node|
+      next unless %i[code code_block].include?(node.type)
 
-      Antlers.render(ast:, current_binding: binding, metadata:)
+      node.string_content = node.string_content.gsub('<!-- ANTLERS', '<{').gsub('ANTLERS -->', '}>')
+                                .gsub(/[{}]/, CODE_BRACES)
     end
   end
 end

data/lib/version.rb

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

metadata

@@ -1,16 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - maedi
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: antlers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: commonmarker
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -24,7 +38,49 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: commonmarker
+  name: dirload
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: lownode
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -51,21 +107,73 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: trees
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.5
+- !ruby/object:Gem::Dependency
+  name: unicode-display_width
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 description: |
   Raindown is a templating layer for static site generation
   and an annotation framework for Markdown files.
 email:
 - maediprichard@gmail.com
-executables: []
+executables:
+- raindown
 extensions: []
 extra_rdoc_files: []
 files:
+- bin/raindown
 - lib/elements.rb
+- lib/lexemes/endpoint_lexeme.rb
 - lib/lexemes/list_lexeme.rb
-- lib/lexemes/toc_lexeme.rb
+- lib/nodes/endpoint_node.rb
 - lib/nodes/list_node.rb
-- lib/nodes/toc_node.rb
 - lib/raindown.rb
+- lib/raindown/bare_directives.rb
+- lib/raindown/cli.rb
+- lib/raindown/code.rb
+- lib/raindown/code_blocks.rb
+- lib/raindown/config.rb
+- lib/raindown/directives.rb
+- lib/raindown/endpoint/curl.rb
+- lib/raindown/endpoint/endpoint_runner.rb
+- lib/raindown/files.rb
+- lib/raindown/front_matter.rb
+- lib/raindown/node.rb
+- lib/raindown/node_blocks.rb
+- lib/raindown/node_injector.rb
+- lib/raindown/nodes.rb
+- lib/raindown/page.rb
+- lib/raindown/pages.rb
+- lib/raindown/pre_renderer.rb
+- lib/raindown/rewriter.rb
+- lib/raindown/table_formatter.rb
+- lib/raindown/toc.rb
+- lib/raindown/variables.rb
+- lib/raindown/watcher.rb
 - lib/version.rb
 homepage: https://github.com/raindeer-rb/raindown
 licenses: []
@@ -79,14 +187,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.3.0
+      version: 3.4.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Markup your markdown with a template and annotation layer
 test_files: []

data/lib/lexemes/toc_lexeme.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-require 'antlers/api'
-
-module Rain
-  module TOCLexeme
-    include Antlers::Lexeme
-
-    module_function
-
-    KEYWORDS = [':toc'].freeze
-
-    def match?(keywords:, **)
-      keywords.keys.include?(':toc')
-    end
-
-    def lexeme(**)
-      { toc: :default }
-    end
-  end
-end

data/lib/nodes/toc_node.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-require 'antlers/api'
-require 'nokogiri'
-
-module Rain
-  class TOCNode < Antlers::LeafNode
-    def initialize(name:, template:)
-      super(name:)
-
-      @template = template
-    end
-
-    def render(current_binding: nil, parent_binding: nil, slot_node: nil, metadata: {})
-      doc = Nokogiri::HTML(@template)
-
-      <<~HTML
-        <div class="floating">
-          <details id="toc" open>
-            <summary>Table of contents</summary>
-            <ul>
-              #{doc.css('h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]').map do |h|
-                "<li class='#{h.name}'><a href='\##{h['id']}'>#{h.text.strip}</a></li>"
-              end.join("\n")}
-            </ul>
-          </details>
-        </div>
-      HTML
-    end
-
-    class << self
-      def match?(segment:)
-        segment[:toc]
-      end
-
-      def build(template:, **)
-        new(name: :toc, template:)
-      end
-    end
-  end
-end