raindown 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0e77b47d4bdedcda5ace520aff8dabc470b3d49a9d7f2dac83b43d23d0928c2
-  data.tar.gz: 0e26371c232241abfcfbaec62a09eb89445299fdd5e4d67273a9c0839bb1982a
+  metadata.gz: 17711b42b7bfd45766f0ad743b58035648b99394031bde5a420e92f01918f8a3
+  data.tar.gz: 94753448785a4825b3e2745d0690db75d69b052d57c3ca2e185793b427fedbef
 SHA512:
-  metadata.gz: 917089b01769a65e0b96d645613f182fdbd7212760823293ed87dd1581071751f53548bdc84d363c40e5a50d4c4941c10f6a409ded7dd2c5687708581dcd9213
-  data.tar.gz: 1ae3a21d68f7bb6fd7042e371cec3352eb7e1781855dcf3a5c92b80c1024a628481c2a3f159be9ee6fb1769592169640f5d767989aadf29bfbadba76ab610849
+  metadata.gz: be61212919255c9018253757f33d02e6cae3ec7811276791fe06bfbdaad748ffe4f47abeac8aad807d5862a7b2bcb493a2d53bebfd30f9abcb820c7faffaf438
+  data.tar.gz: 50488661cf504f7fa1fc9963a9aff7a6ebefb755ba46e2b0e63413133ee4e5781e9d9b94f0ba7c3965d7759b453d95ea7254713cf5e5dce73df2e6299de89b71

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

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require 'fileutils'
 require 'trees'
 require_relative '../raindown'
+require_relative '../version'
 require_relative 'rewriter'
 require_relative 'watcher'
 
@@ -11,9 +13,13 @@ module Raindown
 
     USAGE = <<~TEXT
       Usage: raindown FILE [options]
+             raindown init [DIRECTORY]
 
       Renders FILE to HTML, then re-renders it every time it is saved.
 
+      Commands:
+        init [DIRECTORY]    Create a .raindown folder for the project's config and nodes (default: current directory)
+
       Options:
         -o, --output PATH   Write output to PATH instead of FILE.html beside FILE
         --once              Render once without watching, printing to stdout unless -o is given
@@ -22,8 +28,21 @@ module Raindown
         --bare              Allow bare directives like :toc in Markdown files
         -x, --execute       Run endpoint curl snippets that have no output yet
         -h, --help          Show this message
+        -v, --version       Show the version
+
+      Set RAINDOWN_DEBUG=1 to show where an error happened.
     TEXT
 
+    CONFIG = <<~YAML
+      # Raindown project settings. See https://raindown.dev/docs/config
+      #
+      # Show directives as HTML comments rather than in bold:
+      # hide_directives: true
+      #
+      # Leave code blocks unhighlighted, so the browser can highlight them instead:
+      # highlight_code: false
+    YAML
+
     OPTIONS = { output: ['-o :output', '--output :output'], bare: ['--bare'], execute: ['-x', '--execute'],
                 once: ['--once'], stdin: ['--stdin'] }.freeze
 
@@ -50,11 +69,34 @@ module Raindown
       end
     end
 
-    # The :path line would match a help flag as the file, so help is checked first.
+    # The :path line would match help, version and init as the file, so they're checked first.
     def self.run(argv)
       abort(USAGE) if argv.empty? || argv.intersect?(%w[-h --help])
+      return puts(VERSION) if argv.intersect?(%w[-v --version])
+      return init(argv[1]) if argv.first == 'init' && argv.size <= 2
 
       super || abort("Unknown arguments: #{argv.join(' ')}\n\n#{USAGE}")
+    rescue StandardError => e
+      report(e, path: argv.first)
+    end
+
+    # Shows an error in a file as one line, rather than a backtrace, unless RAINDOWN_DEBUG is set.
+    def self.report(error, path:)
+      raise error if ENV['RAINDOWN_DEBUG']
+
+      abort("raindown: #{path}: #{error.message}")
+    end
+
+    # Creates the .raindown folder that marks a project's root and holds its config.yml and nodes.
+    def self.init(directory = nil)
+      folder = File.join(directory || Dir.pwd, Nodes::FOLDER)
+      config = File.join(folder, Config::FILE)
+      return puts("#{config} already exists") if File.exist?(config)
+
+      FileUtils.mkdir_p(folder)
+      File.write(config, CONFIG)
+      puts "Created #{config}"
+      puts 'Put your own nodes in the same folder. See https://raindown.dev/docs/nodes'
     end
 
     class << self
@@ -72,7 +114,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/directives.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'erb'
+require 'cgi/escape'
 
 module Raindown
   # Content directives, like a node's directive and end tag or an endpoint's, are kept in the HTML:
@@ -22,7 +22,7 @@ module Raindown
     def render(html, hide: false)
       html.gsub(MARKER) do
         text = ::Regexp.last_match(1)
-        hide ? "<!-- #{text} -->" : "<p><strong>#{ERB::Util.html_escape(text)}</strong></p>"
+        hide ? "<!-- #{text} -->" : "<p><strong>#{CGI.escapeHTML(text.to_s)}</strong></p>"
       end
     end
   end

data/lib/raindown/node_blocks.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require 'lowkey'
+
 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 +28,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 +84,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 +121,24 @@ 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 value(value, front_matter)
-      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 }
+    def props(text, variables)
+      text.scan(PROP).to_h { |name, value| [name.to_sym, value(value, variables)] }
+    end
+
+    # A value, like 'text', 3, true, nil or :draft, or else a variable, like author.name.
+    def value(value, variables)
+      Lowkey::ValueParser.parse(value) do
+        next value[1..-2] if value.match?(/\A(["']).*\1\z/)
+
+        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, 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

data/lib/raindown/toc.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require 'erb'
-require 'nokogiri'
+require 'cgi/escape'
 
 require_relative 'node'
 
@@ -9,6 +8,12 @@ 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
+    # A heading with an id, in the HTML that Commonmarker and Raindown's components write, like <h2 id="setup">.
+    HEADING = %r{<h([1-6])\b[^>]*?\bid=(?:"([^"]*)"|'([^']*)'|([^\s>]+))[^>]*>(.*?)</h\1\s*>}mi
+    # Comments and scripts can hold heading tags that aren't in the page.
+    IGNORED = %r{<!--.*?-->|<script\b.*?</script\s*>}mi
+    TAG = /<[^>]*>/
+
     def replace(document:, metadata: nil, bare: false)
       headings = headings(markdown: document, metadata:, bare:)
       return '' if headings.empty?
@@ -23,7 +28,7 @@ module Raindown
     # 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>"
+        "<li class='h#{heading[:level]}'><a href='##{heading[:id]}'>#{CGI.escapeHTML(heading[:text])}</a></li>"
       end
 
       <<~HTML
@@ -42,8 +47,8 @@ module Raindown
     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'] }
+      html.gsub(IGNORED, '').scan(HEADING).map do |level, *ids, content|
+        { level: level.to_i, text: CGI.unescapeHTML(content.gsub(TAG, '')).strip, id: CGI.unescapeHTML(ids.compact.first) }
       end
     end
   end

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/watcher.rb

@@ -19,8 +19,10 @@ module Raindown
 
       $stdout.sync = true
 
-      rewrite
-      render
+      safely do
+        rewrite
+        render
+      end
       puts "Watching #{path} for changes (writing to #{output})..."
 
       listener.start
@@ -35,14 +37,26 @@ module Raindown
 
       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}"
+        safely do
+          # Formatting saves the file again, and that change triggers the render.
+          next if rewrite
+
+          render
+          puts "Re-rendered #{path} -> #{output}"
+        end
       end
     end
 
+    # An error in the file is shown rather than stopping the watcher, so it can be fixed and saved again.
+    def safely
+      yield
+    rescue StandardError => e
+      raise if ENV['RAINDOWN_DEBUG']
+
+      warn "raindown: #{path}: #{e.message}"
+    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))

data/lib/raindown.rb

@@ -27,34 +27,51 @@ 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
     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
 
-  # 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, encoding: Encoding::UTF_8), 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 +88,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.2'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-25 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
@@ -38,7 +38,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: dirload
+  name: csv
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -52,7 +52,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: listen
+  name: dirload
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -66,7 +66,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: lownode
+  name: listen
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -80,7 +80,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: nokogiri
+  name: lowkey
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: lownode
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -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