raindown 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c36e6807f4679d073cdc969831684565451ce3f6fe1c1d09eb89b1b9526faf7
-  data.tar.gz: 23b34dd9c842c9ad29a159c96f74ff5053df08bc146b4589f2aef22bc0a0e19f
+  metadata.gz: ee322a9f4df788bddfb51b6d669a7a676574620ecd1ce30e69a5682d49b8c88e
+  data.tar.gz: 2bb5f698d9c5e90f0c44271e4b1529512dab858dcd07beb04061ac8690a81bff
 SHA512:
-  metadata.gz: 9db6ef5e7a58ee401621073c809f0eaf0d7147a8d265ff68d803eefbd70f161efe8a447b6ec6d5e6e3ad9952f3a7929b4c7ac8f9fa4fd2f5af8778375ff878ba
-  data.tar.gz: d91807885cf892c6bfc944e20067c87a317558d3062390767bfb2cb32429c88936e9bc90e76e891258bb913e2d3753310a930d140043a75f37dfef3f9a7b9b3c
+  metadata.gz: e550608449c87c693edef3c249472a89c62618de92941b81e135250462bbc74a062b61b2e025ea8666ff571b5057a25b67a13ed6fb385f304e500448f09a3034
+  data.tar.gz: a60db4e479d593ea779e93c3c683401519599ac0bf1d07f6f1e2a280634eff26b5f46167f27d5ce24fcd08f54660cb4051ed21e0c422951247a8f3d2c53938a7

data/lib/raindown/chart/bars.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'drawing'
+
+module Raindown
+  class Chart < Node
+    # Horizontal bars, with negative values or a minus column left of a line:
+    #   Jan  ████████████▍    1,240        a1b2c3d  -38 ▕████│███████████▍  +142
+    class Bars < Drawing
+      LEFT = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉'].freeze
+      # Negative bars fill a cell from the right, which only has eighths and halves.
+      RIGHT = ['', '▕', '▕', '▐', '▐', '▐', FULL, FULL].freeze
+
+      def lines
+        measure
+        values = value_texts
+        minuses = minus_texts
+        @labels.each_index.map { |index| "#{label_text(@labels[index])}#{minuses[index]}#{bar_line(index)} #{values[index]}" }
+      end
+
+      private
+
+      # How many characters a value takes, and how many the bars take either side of the line.
+      def measure
+        low, high = range
+        @scale = @width / (high - low).to_f
+        @left = cells(-low * @scale)
+        @right = cells(high * @scale)
+        @line = low.negative? ? '│' : ''
+      end
+
+      # Each minus value lined up left of its bar, or nothing without a minus column.
+      def minus_texts
+        return Array.new(@labels.length, '') unless @minus
+
+        aligned(@below.map { "-#{number_text(it)}" }).map { "#{it} " }
+      end
+
+      # Each value, lined up, with a + when a minus column is charted against it, whose values go left of the bars.
+      def value_texts
+        aligned(@minus ? @above.map { "+#{number_text(it)}" } : @values.map { number_text(it) })
+      end
+
+      def aligned(texts)
+        texts.map { it.rjust(texts.map(&:length).max) }
+      end
+
+      def bar_line(index)
+        negative = @below[index].positive? ? bar(@below[index] * @scale, RIGHT, from: :right) : ''
+        positive = @above[index].positive? ? bar(@above[index] * @scale, LEFT) : ''
+
+        "#{negative.rjust(@left)}#{@line}#{pad(positive, @right)}"
+      end
+
+      def label_text(label)
+        label_width = @labels.map { display_width(it) }.max
+        label_width.zero? ? '' : "#{pad(label, label_width)}  "
+      end
+
+      # A bar of full cells and an eighth, where any value above zero shows.
+      def bar(length, partials, from: :left)
+        eighths = (length * 8).round.clamp(1..)
+        full, part = eighths.divmod(8)
+
+        from == :left ? (FULL * full) + partials[part] : partials[part] + (FULL * full)
+      end
+    end
+  end
+end

data/lib/raindown/chart/chart.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative '../node'
+require_relative 'bars'
+require_relative 'columns'
+require_relative 'line'
+require_relative 'points'
+require_relative 'sparkline'
+
+module Raindown
+  # The node behind chart:, a chart in block characters of the data it's given, written into the Markdown as code:
+  #   chart: 'data/downloads.csv'      chart: stats format: 'columns'      chart: '3 5 -2 8'
+  # The data is a CSV, TSV, JSON or YAML file relative to the project, numbers, or a variable with either, or with
+  # data of its own like a list or a hash. Labeled data draws as bars and numbers alone as a sparkline,
+  # unless format: is 'bars', 'columns', 'line' or 'sparkline'. Negative values go below a line, or left of it for bars.
+  # A project can draw charts its own way with a Chart node in .raindown, like "class Chart < Raindown::Chart".
+  class Chart < Node
+    FORMATS = { 'bars' => Bars, 'columns' => Columns, 'line' => Line, 'sparkline' => Sparkline }.freeze
+
+    # Label and value are the columns to chart, by name or index, and minus a column to chart against the values.
+    # Width is in characters, for bars and lines, and height in lines, for columns and lines.
+    def initialize(data = nil, format: nil, label: nil, value: nil, minus: nil, width: 40, height: 8) # rubocop:disable Metrics/ParameterLists -- each is a prop
+      @data = data
+      @format = format
+      @label = label
+      @value = value
+      @minus = minus
+      @width = width
+      @height = height
+    end
+
+    # The data is read every time, so the chart follows changes to its file.
+    def replace(metadata: NoMetadata)
+      points = points(metadata:)
+      return '' if points.empty?
+
+      "```\n#{draw(points).map(&:rstrip).join("\n")}\n```"
+    rescue Error => e
+      "Can't chart #{@data.inspect}: #{e.message}"
+    end
+
+    # Each value with its label, or nil for numbers alone.
+    def points(metadata: NoMetadata)
+      root = metadata.respond_to?(:root) ? metadata.root : Dir.pwd
+      Points.new(label: @label, value: @value, minus: @minus, root:).from(@data)
+    end
+
+    def draw(points)
+      format = @format || (points.any?(&:first) ? 'bars' : 'sparkline')
+      drawing = FORMATS[format] || raise(Error, "format: is #{FORMATS.keys.join(', ')}, not #{format.inspect}")
+
+      drawing.new(points, width: @width, height: @height).lines
+    end
+  end
+end

data/lib/raindown/chart/columns.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'drawing'
+
+module Raindown
+  class Chart < Node
+    # Vertical columns from a line at zero, with negative values or a minus column below it,
+    # the largest and smallest values on the left and labels below.
+    #   2,210 ┤     ▄▄▄
+    #         │ ███ ███
+    #       0 ┼─────────
+    #           Jan Feb
+    class Columns < Drawing
+      def lines
+        low, high = range
+        @slot = [3, *@labels.map { display_width(it) }].max
+        above, below = grid(@height / (high - low).to_f, slot: @slot, gap: 1)
+        top, bottom = ticks
+
+        [*axis(above, top, at: 0), baseline, *axis(below, bottom, at: below.length - 1), *label_line]
+      end
+
+      private
+
+      # The largest value at the top, and the smallest at the bottom when it's below zero.
+      def ticks
+        top = @above.max.positive? ? number_text(@above.max) : ''
+        bottom = @below.max.positive? ? number_text(-@below.max) : ''
+        @tick_width = [top, bottom, '0'].map(&:length).max
+
+        [top, bottom]
+      end
+
+      # Rows after the axis, with the tick on the row at its index.
+      def axis(rows, tick, at:)
+        rows.each_with_index.map do |row, index|
+          index == at && !tick.empty? ? "#{tick.rjust(@tick_width)} ┤ #{row}" : "#{' ' * @tick_width} │ #{row}"
+        end
+      end
+
+      def baseline
+        "#{'0'.rjust(@tick_width)} ┼#{'─' * ((@values.length * (@slot + 1)) + 1)}"
+      end
+
+      def label_line
+        return [] if @labels.all?(&:empty?)
+
+        ["#{' ' * (@tick_width + 3)}#{@labels.map { center(it, @slot) }.join(' ')}"]
+      end
+    end
+  end
+end

data/lib/raindown/chart/drawing.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'unicode/display_width'
+
+require_relative '../node'
+
+module Raindown
+  class Chart < Node
+    class Drawing
+      FULL = '█'
+      # Columns fill a cell from the bottom, and negative columns from the top, which only has eighths and halves.
+      LOWER = ['', '▁', '▂', '▃', '▄', '▅', '▆', '▇'].freeze
+      UPPER = ['', '▔', '▔', '▀', '▀', '▀', FULL, FULL].freeze
+      # Float error, so a value of exactly 3 cells doesn't reach into a 4th.
+      EPSILON = 1e-9
+
+      # Values go above zero or right of its line, and negative values below or left of it. With a minus column,
+      # each point is [label, value, minus], and its value goes above and its minus below, whatever their signs.
+      def initialize(points, width:, height:)
+        @labels = points.map { it.first.to_s }
+        @values = points.map { it[1] }
+        @minus = points.map { it[2] } if points.any? { it.length > 2 }
+        @above = @minus ? @values.map(&:abs) : @values.map { it.clamp(0..) }
+        @below = @minus ? @minus.map(&:abs) : @values.map { (-it).clamp(0..) }
+        @width = width
+        @height = height
+      end
+
+      private
+
+      # How far below and above zero the chart goes, which always includes zero, so bars and columns start from it.
+      def range
+        low = -@below.max
+        high = @above.max
+
+        [low, low == high ? 1 : high]
+      end
+
+      # The rows of columns above and below zero, top to bottom, each column in the middle of its slot.
+      def grid(scale, slot:, gap:)
+        low, high = range
+
+        [grid_rows(cells(high * scale).downto(1), @above, scale, LOWER, slot:, gap:),
+         grid_rows(1.upto(cells(-low * scale)), @below, scale, UPPER, slot:, gap:)]
+      end
+
+      # Each row by how many cells it is from zero, for the values above it or below it.
+      def grid_rows(rows, values, scale, partials, slot:, gap:) # rubocop:disable Metrics/ParameterLists -- a row of the grid
+        rows.map do |row|
+          values.map { |value| center(cell((value * scale) - row + 1, partials) * [slot, 3].min, slot) }.join(' ' * gap)
+        end
+      end
+
+      # How much of a cell a column fills, by eighths, where any value above zero shows.
+      def cell(level, partials)
+        return ' ' if level <= EPSILON
+
+        eighths = (level.clamp(..1) * 8).round.clamp(1..)
+        eighths == 8 ? FULL : partials[eighths]
+      end
+
+      def cells(length)
+        (length - EPSILON).ceil.clamp(0..)
+      end
+
+      # Whole numbers with thousands separators, and others to two decimal places.
+      def number_text(value)
+        value = value.round(2)
+        value = value.to_i if value.is_a?(Float) && value == value.to_i
+        whole, decimal = value.abs.to_s.split('.')
+
+        "#{'-' if value.negative?}#{whole.reverse.scan(/\d{1,3}/).join(',').reverse}#{".#{decimal}" if decimal}"
+      end
+
+      def display_width(text)
+        Unicode::DisplayWidth.of(text)
+      end
+
+      def pad(text, width)
+        text + (' ' * (width - display_width(text)))
+      end
+
+      def center(text, width)
+        pad((' ' * ((width - display_width(text)) / 2)) + text, width)
+      end
+    end
+  end
+end

data/lib/raindown/chart/line.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative 'drawing'
+
+module Raindown
+  class Chart < Node
+    # A line through the values in braille, where each character is a grid of dots 2 wide and 4 high,
+    # with the highest and lowest values on the left, labels below and negative values below a line at zero.
+    # With a minus column, its values are a second line below zero.
+    #    4 ┤ ⠑⡄     ⢀⠎
+    #    0 ┼──⠈⠢⡀──⡰⠁─
+    #   -4 ┤    ⠘⢄⠎
+    #        Jan   Mar
+    class Line < Drawing
+      BRAILLE = 0x2800
+      # The bit of each dot in a braille character, by its row and then its column.
+      DOTS = [[0x01, 0x08], [0x02, 0x10], [0x04, 0x20], [0x40, 0x80]].freeze
+
+      def lines
+        @series = @minus ? [@above, @below.map(&:-@)] : [@values]
+        @low, @high = bounds
+        @cells = Array.new(@height) { Array.new(@width, 0) }
+        @series.each { plot_series(it) }
+
+        [*axis, *label_line]
+      end
+
+      private
+
+      def plot_series(values)
+        dots = values.each_index.map { |index| [x(index), y(values[index])] }
+        dots.each_cons(2) { |from, to| plot_line(*from, *to) }
+        plot(*dots.first) if dots.one?
+      end
+
+      # The lowest and highest values, which include zero when there are negative values, so they go below its line.
+      def bounds
+        low, high = @series.flatten.minmax
+        high = [high, 0].max if low.negative?
+
+        [low, high]
+      end
+
+      def x(index)
+        return 0 if @values.one?
+
+        (index * ((@width * 2) - 1).to_f / (@values.length - 1)).round
+      end
+
+      def y(value)
+        return (@height * 4) - 1 if @high == @low
+
+        ((@high - value) * ((@height * 4) - 1).to_f / (@high - @low)).round
+      end
+
+      # The dots between two dots, a step at a time along whichever of across or down is longer.
+      def plot_line(x_from, y_from, x_to, y_to)
+        steps = [(x_to - x_from).abs, (y_to - y_from).abs, 1].max
+        0.upto(steps) { |step| plot(between(x_from, x_to, step, steps), between(y_from, y_to, step, steps)) }
+      end
+
+      def between(from, to, step, steps)
+        from + ((to - from) * step.to_f / steps).round
+      end
+
+      def plot(x, y) # rubocop:disable Naming/MethodParameterName -- a dot's coordinates
+        @cells[y / 4][x / 2] |= DOTS[y % 4][x % 2]
+      end
+
+      # Each row of braille after the axis, with the highest value at the top, the lowest at the bottom,
+      # and zero on the line through the negative values' row.
+      def axis
+        @ticks = ticks
+        @tick_width = @ticks.values.map(&:length).max
+
+        @cells.each_with_index.map do |cells, row|
+          "#{@ticks[row].to_s.rjust(@tick_width)} #{mark(row)}#{cells.map { cell(it, row) }.join}"
+        end
+      end
+
+      # The values on the axis by their row, where the highest wins a row it shares with the lowest.
+      def ticks
+        ticks = { (@height - 1) => number_text(@low) }
+        ticks[0] = number_text(@high) unless @high == @low
+        ticks[zero_row] ||= '0' if zero_row
+        ticks
+      end
+
+      def mark(row)
+        return '┼─' if row == zero_row
+
+        @ticks[row] ? '┤ ' : '│ '
+      end
+
+      def zero_row
+        y(0) / 4 if @low.negative?
+      end
+
+      def cell(bits, row)
+        return (BRAILLE + bits).chr(Encoding::UTF_8) unless bits.zero?
+
+        row == zero_row ? '─' : ' '
+      end
+
+      # The labels under their values, the first and last ones first, leaving out any that would touch another.
+      def label_line
+        return [] if @labels.all?(&:empty?)
+
+        line = placed_labels.sort.reduce(+'') { |text, (from, _, label)| text << (' ' * (from - display_width(text))) << label }
+        ["#{' ' * (@tick_width + 3)}#{line}"]
+      end
+
+      # Each label that fits, with where it starts and ends.
+      def placed_labels
+        [0, @labels.length - 1, *(1...(@labels.length - 1))].uniq.each_with_object([]) do |index, placed|
+          span = label_span(index)
+          placed << [*span, @labels[index]] if placed.none? { |from, to| span[0] <= to + 1 && span[1] >= from - 1 }
+        end
+      end
+
+      # Where a label starts and ends, centered on its value's column and kept inside the chart.
+      def label_span(index)
+        width = display_width(@labels[index])
+        from = ((x(index) / 2) - (width / 2)).clamp(0, [@width - width, 0].max)
+
+        [from, from + width - 1]
+      end
+    end
+  end
+end

data/lib/raindown/chart/points.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'json'
+require 'yaml'
+
+require_relative '../node'
+
+module Raindown
+  class Chart < Node
+    class Error < StandardError; end
+
+    # A chart's data as points, each value with its label, or with nil for numbers alone.
+    # Label and value are the columns to chart, by name or index, which default to the first column
+    # and the first column of numbers after it. Rows without a number are left out.
+    # Minus is a column of numbers to chart against the values, like lines deleted against lines added,
+    # which makes each point [label, value, minus].
+    class Points
+      NUMBER = /\A[+-]?(?:\d{1,3}(?:,\d{3})+|\d+)?(?:\.\d+)?\z/
+
+      def initialize(label: nil, value: nil, minus: nil, root: Dir.pwd)
+        @label = label
+        @value = value
+        @minus = minus
+        @root = root
+      end
+
+      def from(data)
+        case data
+        when String then from_string(data)
+        when Numeric then numbers([data])
+        when Hash then from_table(data.to_a, header: false)
+        when Array then from_list(data)
+        else raise Error, 'there is no data'
+        end
+      end
+
+      private
+
+      # A file's path, relative to the root, or numbers like '3 5 -2 8' or '3, 5, -2, 8'.
+      def from_string(string)
+        numbers = string.strip.split(/[\s,]+/)
+        return numbers(numbers) if numbers.any? && numbers.all? { number(it) }
+
+        path = File.expand_path(string, @root)
+        raise Error, 'no such file' unless File.file?(path)
+
+        from(read(path))
+      end
+
+      def read(path)
+        text = File.read(path, encoding: Encoding::UTF_8)
+
+        case File.extname(path).downcase
+        when '.csv' then CSV.parse(text, skip_blanks: true)
+        when '.tsv' then CSV.parse(text, col_sep: "\t", skip_blanks: true)
+        when '.json' then JSON.parse(text)
+        when '.yml', '.yaml' then YAML.safe_load(text)
+        else raise Error, 'only CSV, TSV, JSON and YAML files can be charted'
+        end
+      rescue CSV::MalformedCSVError, JSON::ParserError, Psych::SyntaxError => e
+        raise Error, e.message
+      end
+
+      # Numbers, rows of hashes like JSON or YAML, or rows of cells like CSV.
+      def from_list(list)
+        return numbers(list) if list.all? { number(it) }
+        return from_table(hash_rows(list), header: true) if list.all?(Hash)
+        return from_table(list, header: header?(list.first)) if list.all?(Array)
+
+        raise Error, 'it needs numbers, or rows with a number in each'
+      end
+
+      # Numbers alone, which have no column to chart against them.
+      def numbers(list)
+        raise Error, 'minus: needs a table, with a column of numbers to chart against the values' if @minus
+
+        list.map { [nil, number(it)] }
+      end
+
+      # Rows of hashes as a table, with their keys as its header.
+      def hash_rows(rows)
+        keys = rows.flat_map(&:keys).uniq
+        [keys.map(&:to_s), *rows.map { |row| row.values_at(*keys) }]
+      end
+
+      # A first row without numbers names the columns, like "month,downloads".
+      def header?(row)
+        row.none? { number(it) }
+      end
+
+      def from_table(rows, header:)
+        names = header ? rows.first.map(&:to_s) : []
+        rows = rows.drop(1) if header
+        label, value, minus = columns(rows, names)
+
+        rows.filter_map do |row|
+          number = number(row[value])
+          [label && row[label].to_s, number, *(number(row[minus]) || 0 if minus)] if number
+        end
+      end
+
+      # The label, value and minus columns' indexes, where a single column of numbers has no labels.
+      def columns(rows, names)
+        minus = column(@minus, names) if @minus
+        value = column(@value, names) if @value
+        label = @label ? column(@label, names) : first_label(rows, [value, minus])
+        value ||= first_value(rows, [label, minus])
+        raise Error, 'there is no column of numbers' unless value
+
+        [label, value, minus]
+      end
+
+      # The first column that isn't taken, when there's more than one.
+      def first_label(rows, taken)
+        count = rows.map(&:length).max.to_i
+        (0...count).find { !taken.include?(it) } if count > 1
+      end
+
+      # The first column of numbers that isn't taken.
+      def first_value(rows, taken)
+        (0...rows.map(&:length).max.to_i).find { |index| !taken.include?(index) && rows.any? { number(it[index]) } }
+      end
+
+      def column(name, names)
+        return name if name.is_a?(Integer)
+
+        names.index(name.to_s) || raise(Error, "there is no #{name.inspect} column")
+      end
+
+      def number(value)
+        return value if value.is_a?(Numeric)
+        return unless value.is_a?(String) && value.strip.match?(NUMBER) && value.match?(/\d/)
+
+        text = value.strip.delete(',')
+        text.include?('.') ? Float(text) : Integer(text, 10)
+      end
+    end
+  end
+end

data/lib/raindown/chart/sparkline.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'drawing'
+
+module Raindown
+  class Chart < Node
+    # A line of numbers from lowest to highest, or columns a cell high with negative values or a minus column
+    # below a line.
+    #   ▁▃▅█▂
+    class Sparkline < Drawing
+      SPARKS = %w[▁ ▂ ▃ ▄ ▅ ▆ ▇ █].freeze
+
+      def lines
+        return [@above.map { spark(it, *@above.minmax) }.join] if @below.none?(&:positive?)
+
+        above, below = grid(1.0 / [@above.max, @below.max].max, slot: 1, gap: 0)
+        [*above, '─' * @values.length, *below]
+      end
+
+      private
+
+      def spark(value, low, high)
+        SPARKS[high == low ? 0 : ((value - low) * 7.0 / (high - low)).round]
+      end
+    end
+  end
+end

data/lib/raindown/cli.rb

@@ -72,7 +72,7 @@ module Raindown
       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),
-                                      hide_directives: Config.for(path)[:hide_directives]))
+                                      **Config.render_options(path)))
       end
 
       def watch(path, output = nil, bare: false, execute: false)

data/lib/raindown/config.rb

@@ -5,9 +5,10 @@ require 'yaml'
 module Raindown
   # A project's settings, from config.yml in its .raindown folder:
   #   hide_directives: true    # Directives become HTML comments rather than bold text in the HTML.
+  #   highlight_code: false    # Code blocks aren't highlighted, so the browser can highlight them instead.
   module Config
     FILE = 'config.yml'
-    DEFAULTS = { hide_directives: false }.freeze
+    DEFAULTS = { hide_directives: false, highlight_code: true }.freeze
 
     module_function
 
@@ -19,5 +20,10 @@ module Raindown
 
       DEFAULTS.merge(YAML.safe_load_file(file, symbolize_names: true) || {})
     end
+
+    # The settings for rendering a file, like Raindown.render(**Config.render_options(path)).
+    def render_options(path)
+      self.for(path).slice(:hide_directives, :highlight_code)
+    end
   end
 end

data/lib/raindown/node_blocks.rb

@@ -4,6 +4,7 @@ require_relative 'code_blocks'
 require_relative 'directives'
 require_relative 'front_matter'
 require_relative 'nodes'
+require_relative 'variables'
 
 module Raindown
   # Finds node blocks in a file's lines: a node's directive and the Markdown it wrote below it.
@@ -25,8 +26,10 @@ module Raindown
     SELF_CLOSING = /\A( {0,3})<\{\s*:(#{NAME})(?:\s+(.*?))?\s*\}>[ \t]*$/
     BARE_SELF_CLOSING = /\A( {0,3}):(#{NAME})(?:[ \t]+(.*?))?[ \t]*$/
     # A prop is name=value or name: value, where the value is quoted text, a number, true, false
-    # or a front matter key like author.name.
+    # or a variable like author.name.
     PROP = /(\w+)(?:=|:[ \t]+)("[^"]*"|'[^']*'|\S+)/
+    # A value before the props is the node's argument.
+    ARG = /\A("[^"]*"|'[^']*'|[^\s"']\S*)(?:\s+|\z)/
 
     module_function
 
@@ -79,7 +82,7 @@ module Raindown
       found, pattern = directive(lines[index], bare:)
       return unless found && (klass = Nodes.node_class(found[2]))
 
-      node = Nodes.instance(klass, props(found[3].to_s, front_matter))
+      node = Nodes.instance(klass, *args(found[3].to_s, Variables.new(front_matter)))
       case pattern
       when :open then end_tag(lines, index, found[2]).then { |close| { open: index, close:, last: close, node: } }
       when :bare_open then bare_block(lines, index, node)
@@ -116,17 +119,25 @@ module Raindown
       close
     end
 
-    def props(text, front_matter)
-      text.scan(PROP).to_h { |name, value| [name.to_sym, value(value, front_matter)] }
+    # 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)
+      arg = text.match(ARG) unless text.match?(/\A#{PROP}/)
+      return [props(text, variables)] unless arg
+
+      [props(arg.post_match, variables), [value(arg[1], variables)]]
+    end
+
+    def props(text, variables)
+      text.scan(PROP).to_h { |name, value| [name.to_sym, value(value, variables)] }
     end
 
-    def value(value, front_matter)
+    def value(value, variables)
       case value
       when /\A(["']).*\1\z/ then value[1..-2]
       when /\A-?\d+\z/ then value.to_i
       when /\A-?\d+\.\d+\z/ then value.to_f
       when 'true', 'false' then value == 'true'
-      else value.split('.').reduce(front_matter) { |data, key| data.is_a?(Hash) ? data[key.to_sym] : nil }
+      else Variables.value(variables, value)
       end
     end
   end

data/lib/raindown/nodes.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'chart/chart'
 require_relative 'files'
 require_relative 'node'
 require_relative 'toc'
@@ -11,8 +12,8 @@ module Raindown
   # document: (the Markdown being rendered), metadata: and bare:, and gets the ones it asks for.
   module Nodes
     FOLDER = '.raindown'
-    # Lowercase directives for Raindown's own nodes. A project's own TOC or Files node replaces Raindown's.
-    BUILT_INS = { 'toc' => 'TOC', 'files' => 'Files' }.freeze
+    # Lowercase directives for Raindown's own nodes. A project's own TOC, Files or Chart node replaces Raindown's.
+    BUILT_INS = { 'toc' => 'TOC', 'files' => 'Files', 'chart' => 'Chart' }.freeze
     # A placeholder for a node's HTML, which stays as it is through Commonmarker and Antlers.
     PLACEHOLDER = /<!-- raindown:node (\d+) -->/
 
@@ -78,11 +79,11 @@ module Raindown
 
     # One instance for each node and its props, kept for the whole process.
     # So a node can keep what its Markdown and HTML share, like a date, and both stay the same between renders.
-    def instance(klass, props)
-      key = [klass, props]
+    def instance(klass, props, args = [])
+      key = [klass, args, props]
       instances[key] ||= begin
         id = list.length
-        list << klass.new(**props)
+        list << klass.new(*args, **props)
         id
       end
 

data/lib/raindown/page.rb

@@ -14,12 +14,13 @@ module Raindown
 
     # Rendered when asked for, so a file that lists itself doesn't render forever.
     # The front matter is rendered with it, so its variables work, and a Raindown file's bare directives too.
+    # It follows the file's project config, like render_file, unless the render options say otherwise.
     def content
       @content ||= begin
-        markdown = File.read(file_path)
+        markdown = File.read(file_path, encoding: Encoding::UTF_8)
 
         if FrontMatter.parse(markdown).last.strip.empty? then ''
-        else Raindown.render(markdown:, bare: BareDirectives.file?(file_path), **@render_options)
+        else Raindown.render(markdown:, bare: BareDirectives.file?(file_path), **Config.render_options(file_path).merge(@render_options))
         end
       end
     end

data/lib/raindown/pages.rb

@@ -31,6 +31,8 @@ module Raindown
       end
     end
 
+    attr_reader :root
+
     # Render options, like hide_directives: true, are for rendering each listed file's content.
     def initialize(metadata:, root:, render_options: {})
       @root = root
@@ -60,7 +62,7 @@ module Raindown
     end
 
     def process(file_path:)
-      metadata = implicit_metadata(file_path:).merge(FrontMatter.parse(File.read(file_path)).first)
+      metadata = implicit_metadata(file_path:).merge(FrontMatter.parse(File.read(file_path, encoding: Encoding::UTF_8)).first)
       @metadata[file_path] = metadata
       metadata.each { |type, tag| Array(tag).each { |item| tag(type:, tag: item, file_path:) } }
     end

data/lib/raindown/rewriter.rb

@@ -21,7 +21,7 @@ module Raindown
 
     # Returns true when the file changed.
     def update(path:, bare: false, execute: false, metadata: NoMetadata)
-      content = File.read(path)
+      content = File.read(path, encoding: Encoding::UTF_8)
       rewritten = rewrite(content:, path:, bare:, execute:, metadata:)
       return false if rewritten == content
 

data/lib/raindown/variables.rb

@@ -16,6 +16,21 @@ module Raindown
       end
     end
 
+    # A wrapped value as the data it was, so a variable in a node's props is a hash, list or text like any other.
+    def self.unwrap(value)
+      case value
+      when Variables then value.to_h
+      when ::Array then value.map { |item| unwrap(item) }
+      when ::String then value.tr(CODE_BRACES.values.join, CODE_BRACES.keys.join)
+      else value
+      end
+    end
+
+    # A variable's value, like author.name, read the way {author.name} reads it, unwrapped. Unknown names are nil.
+    def self.value(variables, name)
+      unwrap(name.split('.').reduce(variables) { |value, key| value.respond_to?(key) ? value.send(key) : nil })
+    end
+
     def initialize(values)
       @values = values.to_h { |key, value| [key.to_sym, Variables.wrap(value)] }
     end
@@ -32,6 +47,10 @@ module Raindown
       ::Kernel.binding
     end
 
+    def to_h
+      @values.transform_values { |value| Variables.unwrap(value) }
+    end
+
     def to_s
       @values.to_s
     end

data/lib/raindown.rb

@@ -27,6 +27,8 @@ module Raindown
   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
+  # Without highlighting, code blocks are left for the browser to highlight, like <pre><code class="language-ruby">.
+  UNHIGHLIGHTED_OPTIONS = { render: { **HTML_OPTIONS[:render], github_pre_lang: false } }.freeze
 
   # Stands in for an app's metadata when there isn't any, so list: and files: list nothing.
   module NoMetadata
@@ -38,23 +40,41 @@ module Raindown
 
   module_function
 
-  # 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:)
+  # Directives show in bold and code is highlighted, unless the file's project changes them in .raindown/config.yml.
+  def render_file(path:, metadata: NoMetadata, bare: false, **options)
+    options = Config.render_options(path).merge(options)
+    render(markdown: File.read(path, encoding: Encoding::UTF_8), metadata:, bare: bare || BareDirectives.file?(path), **options)
   end
 
   # 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:)
-
-      Directives.render("#{html.chomp}\n", hide: hide_directives)
+  # Code blocks are highlighted, unless highlight_code is false for a site that highlights code in the browser.
+  def render(markdown:, metadata: NoMetadata, bare: false, hide_directives: false, highlight_code: true)
+    highlighting(highlight_code) do
+      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:)
+
+        Directives.render("#{html.chomp}\n", hide: hide_directives)
+      end
     end
   end
 
+  # Whether code is highlighted while the block runs, like one document's render,
+  # so components and endpoints rendering their own Markdown follow it too.
+  def highlighting(highlight_code)
+    outer = Thread.current[:raindown_highlight_code]
+    Thread.current[:raindown_highlight_code] = highlight_code
+    yield
+  ensure
+    Thread.current[:raindown_highlight_code] = outer
+  end
+
+  def highlight_code?
+    Thread.current[:raindown_highlight_code] != false
+  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:)))
@@ -71,8 +91,14 @@ module Raindown
     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)
+    html = highlight_code? ? doc.to_html(options: HTML_OPTIONS) : unhighlighted_html(doc:)
+    html.gsub('<!-- ANTLERS', '<{').gsub('ANTLERS -->', '}>')
+        .gsub(/[\u{E000}\u{E001}]/, CODE_BRACE_ENTITIES)
+  end
+
+  # Code blocks without highlighting, with a language class for highlighting in the browser.
+  def unhighlighted_html(doc:)
+    doc.to_html(options: UNHIGHLIGHTED_OPTIONS, plugins: { syntax_highlighter: nil })
   end
 
   def variables(markdown:)

data/lib/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: antlers
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.2.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.2.2
 - !ruby/object:Gem::Dependency
   name: commonmarker
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  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: dirload
   requirement: !ruby/object:Gem::Requirement
@@ -154,6 +168,13 @@ files:
 - lib/nodes/list_node.rb
 - lib/raindown.rb
 - lib/raindown/bare_directives.rb
+- lib/raindown/chart/bars.rb
+- lib/raindown/chart/chart.rb
+- lib/raindown/chart/columns.rb
+- lib/raindown/chart/drawing.rb
+- lib/raindown/chart/line.rb
+- lib/raindown/chart/points.rb
+- lib/raindown/chart/sparkline.rb
 - lib/raindown/cli.rb
 - lib/raindown/code.rb
 - lib/raindown/code_blocks.rb