raindown 0.1.0 → 0.2.1

data/lib/raindown/pages.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative 'front_matter'
+require_relative 'page'
+
+module Raindown
+  # The metadata of a project's Markdown files, which list: and files: list by tag.
+  # Ported from Raindeer's Rain::Pages, and takes the same Dirload metadata.
+  #
+  # Each file is tagged with its front matter, like "tags: [ruby, docs]" or "date: 2099", and by its path,
+  # where underscored folders are metadata: docs/_basics/_1-getting-started.md has
+  #   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.
+  class Pages
+    EXTENSIONS = %w[md rd markdown raindown].freeze
+    SEGMENTS = Regexp.union(['/', '&', '-'])
+
+    class << self
+      # 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.
+      def load(root:)
+        require 'dirload'
+        file_types = Dirload.file_paths(absolute_path: root).group_by { Dirload.extension(file_path: it) }
+        new(metadata: Dirload::Metadata.new(loaded_paths: {}, missed_paths: [], file_types:), root:)
+      end
+    end
+
+    # Render options, like hide_directives: true, are for rendering each listed file's content.
+    def initialize(metadata:, root:, render_options: {})
+      @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.
+    # Without tags, every file.
+    def list(**tags)
+      file_paths = tags.empty? ? @file_paths : tagged(**tags)
+      file_paths.sort_by { |file_path| sort_key(file_path) }.map { |file_path| listed_page(file_path) }
+    end
+
+    def tagged(**tags)
+      tags.flat_map { |type, tag| @tags.dig(type.to_sym, tag) || [] }.uniq
+    end
+
+    private
+
+    def listed_page(file_path)
+      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(File.read(file_path)).first)
+      @metadata[file_path] = metadata
+      metadata.each { |type, tag| Array(tag).each { |item| tag(type:, tag: item, file_path:) } }
+    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:)
+      { folder: folders(file_path:).last, order: order(file_path:), path: relative(file_path).delete_prefix('/') }.compact
+    end
+
+    def tag(type:, tag:, file_path:)
+      @tags[type] ||= {}
+      @tags[type][tag] ||= []
+      @tags[type][tag] << file_path
+    end
+
+    # The underscored folders, like basics in docs/_basics/.
+    def folders(file_path:)
+      underscored(File.dirname(relative(file_path))).reject { number?(it) }
+    end
+
+    # The last underscored number in the path, like 1 in docs/_basics/_1-getting-started.md.
+    def order(file_path:)
+      underscored(relative(file_path)).select { number?(it) }.last&.then { Integer(it, exception: false) || Float(it) }
+    end
+
+    def underscored(path)
+      path.split(SEGMENTS).select { it.start_with?('_') }.map { it.delete_prefix('_') }
+    end
+
+    def relative(file_path)
+      File.expand_path(file_path).delete_prefix(File.expand_path(@root))
+    end
+
+    def number?(string)
+      !Float(string, exception: false).nil?
+    end
+
+    # 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]
+    end
+  end
+end

data/lib/raindown/pre_renderer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'antlers'
+require_relative '../elements'
+require_relative 'bare_directives'
+require_relative 'code'
+require_relative 'front_matter'
+
+module Raindown
+  # Renders the directives whose output is Markdown, before Commonmarker reads it: variables, loops, conditions and lists.
+  # So a loop's items become one Markdown list or table, and a heading's id and its entry in a table of contents
+  # come from its text, like "# Notes for {name}" becoming "Notes for Mark" with the id "notes-for-mark".
+  # Nodes like toc: and files: render before this. Components and endpoints render here too, as fragments of HTML
+  # that Raindown puts back once the document is HTML.
+  module PreRenderer
+    BLOCK_DIRECTIVES = %w[for if list].freeze
+    # A for, if or list directive alone on its line, which leaves no line behind, so a loop's list items stay together.
+    BLOCK_LINE = /^[ \t]*(<\{\s*:?(?:#{BLOCK_DIRECTIVES.join('|')})\b[^}]*\}>)[ \t]*\n/
+
+    module_function
+
+    def render(markdown, variables:, metadata: {}, bare: false)
+      markdown = BareDirectives.expand(markdown) if bare
+      return markdown unless markdown.include?('{')
+
+      markdown = Code.hide_braces(markdown.dup.force_encoding('UTF-8'))
+      body = FrontMatter.parse(markdown).last
+      "#{markdown.delete_suffix(body)}#{render_body(body, variables, metadata)}"
+    end
+
+    def render_body(body, variables, metadata)
+      template = body.gsub(BLOCK_LINE, '\1')
+      return body unless template.include?('{')
+
+      # Antlers strips the whitespace around a template, which can be Markdown, like an indented code block.
+      leading = template[/\A\s*/]
+      trailing = template[/\s*\z/]
+      # Components and endpoints render here too, where loop variables are in scope, and keep their HTML as fragments.
+      elements = Antlers::Elements[:html, :var, :if, :for] + Elements[:list, :endpoint, :prop_component, :slot_component]
+      rendered = Antlers.render(ast: Antlers.ast(template:, elements:), current_binding: variables.binding, metadata:)
+
+      "#{leading}#{rendered}#{trailing}"
+    end
+  end
+end

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,50 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'nokogiri'
+
+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: nil, bare: false)
+      headings = 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
+
+    # With the document's final HTML, the headings include ones its components render.
+    def render(document:, html: nil, metadata: nil, bare: false)
+      items = headings(markdown: document, html:, 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
+
+    # The document's headings, from its final HTML, or else by rendering it with its components.
+    def headings(markdown:, html: nil, metadata: nil, bare: false)
+      html ||= Fragments.collect { Raindown.assembled(markdown:, metadata: metadata || NoMetadata, bare:) }
+
+      Nokogiri::HTML(html).css(HEADINGS).map do |heading|
+        { level: heading.name[1].to_i, text: heading.text.strip, id: heading['id'] }
+      end
+    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,96 @@
 # frozen_string_literal: true
 
 require 'commonmarker'
+require 'antlers'
 require 'antlers/api'
+
 require_relative 'elements'
+require_relative 'raindown/bare_directives'
+require_relative 'raindown/code'
+require_relative 'raindown/config'
+require_relative 'raindown/directives'
+require_relative 'raindown/fragments'
+require_relative 'raindown/front_matter'
+require_relative 'raindown/heading_ids'
+require_relative 'raindown/node_blocks'
+require_relative 'raindown/pages'
+require_relative 'raindown/pre_renderer'
+require_relative 'raindown/variables'
+
+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
+
+  # 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
+
+  # Stands in for an app's metadata when there isn't any, so list: and files: list nothing.
+  module NoMetadata
+    def self.list(**) = []
+  end
 
-module Rain
-  module Raindown
-    module_function
+  # 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]'
 
-    def render(markdown:, metadata: {})
-      template = markdown.gsub('<{', '<!-- ANTLERS').gsub('}>', 'ANTLERS -->')
+  module_function
 
-      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
+  # 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
 
-      template = doc.to_html(options: { render: { unsafe: true } })
-      template = template.gsub('<!-- ANTLERS', '<{').gsub('ANTLERS -->', '}>')
+  # Front matter keys are variables, like {title} or <{ title }>.
+  # Directives like "toc:" export to HTML as bold or comments depending on hide_directives config.
+  def render(markdown:, metadata: NoMetadata, bare: false, hide_directives: false)
+    Fragments.collect do
+      # Components' HTML goes back in, then their headings get unique ids, before nodes like the TOC see it.
+      html = assembled(markdown:, metadata:, bare:)
+      html = Nodes.render_placeholders(html, document: markdown, metadata:, bare:, html:)
 
-      return template unless template.include?('<{') || template.include?('{')
+      Directives.render("#{html.chomp}\n", hide: hide_directives)
+    end
+  end
+
+  # The document's HTML with its components' HTML put back, and unique heading ids.
+  def assembled(markdown:, metadata: NoMetadata, bare: false)
+    HeadingIds.unique(Fragments.fill(html(markdown:, variables: variables(markdown:), metadata:, bare:)))
+  end
+
+  # 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:)
+    commonmark(PreRenderer.render(markdown, variables:, metadata:, bare:))
+  end
+
+  # Markdown to HTML, like a document's or a component's slot.
+  def commonmark(markdown)
+    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.1'
 end