jekyll-slides 0.1.0

data/lib/jekyll/slides/component_renderer.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+require "set"
+
+module Jekyll
+  module Slides
+    class ComponentRenderer
+      FRAGMENT_PATTERN = /<!-- jekyll-slides:start:(\d+) -->(.*?)<!-- jekyll-slides:end:\1 -->/m
+      RenderedDocument = Struct.new(:components, :fragments, keyword_init: true)
+      SIZES = %w[sm md lg].freeze
+      # Advisory only: available space depends on the slide layout and component size.
+      LONG_CODE_LINE_THRESHOLD = 20
+
+      def self.render(markdown, warning: nil, options: {})
+        new(warning: warning, options: options).render(markdown)
+      end
+
+      def initialize(warning: nil, rouge_renderer: nil, options: {})
+        @warning = warning
+        @rouge_renderer = rouge_renderer || RougeRenderer.new(warning: warning)
+        @options = options
+      end
+
+      def render(markdown)
+        render_document(markdown).fragments.map { |_kind, html, _metadata| html }.join
+      end
+
+      def render_fragments(markdown, id_prefix: "")
+        render_document(markdown, id_prefix: id_prefix).fragments
+      end
+
+      def render_document(markdown, id_prefix: "")
+        document = Kramdown::Document.new(markdown.to_s, kramdown_options(id_prefix))
+        descriptors = []
+        components = []
+        document.root.children = document.root.children.flat_map do |element|
+          next element if element.type == :blank
+
+          index = descriptors.length
+          kind, rendered, component = render_element(element)
+          components << component if component
+          descriptors << [kind, heading_level(element)]
+          [marker("start", index), rendered, marker("end", index)]
+        end
+
+        html, warnings = Kramdown::Converter::Html.convert(document.root, document.options)
+        warnings.each { |message| Support.warn(@warning, message) }
+        RenderedDocument.new(
+          components: components,
+          fragments: merge_prose_fragments(extract_fragments(html, descriptors))
+        )
+      end
+
+      private
+
+      def kramdown_options(id_prefix)
+        @options.merge(
+          "input" => @options.fetch("input", "GFM"),
+          "auto_id_prefix" => id_prefix,
+          "footnote_prefix" => "#{@options.fetch('footnote_prefix', '')}#{id_prefix}"
+        )
+      end
+
+      def render_element(element)
+        attributes = component_attributes(element)
+        component = component_type(element, attributes)
+        return [:prose, element, nil] unless component
+
+        source_lines = element.value.to_s.lines.map do |line|
+          [line.sub(/\r?\n\z/, ""), line[/\r?\n\z/].to_s]
+        end
+        language = element.options[:lang].to_s
+        html = render_component(component, source_lines, language, attributes)
+        [:visual, raw_element(html), component]
+      end
+
+      def component_attributes(element)
+        ial = element.options[:ial] || {}
+        attributes = ial.each_with_object({ classes: [] }) do |(key, value), result|
+          if key.to_s == "class"
+            result[:classes] = value.to_s.split
+          elsif key.to_s == "id"
+            result[:id] = value
+          else
+            result[key.to_s] = value
+          end
+        end
+        attributes[:id] ||= element.attr["id"]
+        attributes
+      end
+
+      def component_type(element, attributes)
+        return unless element.type == :codeblock
+        return :editor if attributes[:classes].include?("editor")
+
+        :terminal if attributes[:classes].include?("terminal")
+      end
+
+      def heading_level(element)
+        element.type == :header ? element.options[:level] : nil
+      end
+
+      def marker(position, index)
+        raw_element("<!-- jekyll-slides:#{position}:#{index} -->")
+      end
+
+      def raw_element(html)
+        Kramdown::Element.new(:raw, html, {}, category: :block, type: "html")
+      end
+
+      def extract_fragments(html, descriptors)
+        matches = html.to_enum(:scan, FRAGMENT_PATTERN).map { Regexp.last_match }
+        fragments = matches.map do |match|
+          kind, level = descriptors.fetch(match[1].to_i)
+          [kind, match[2].strip, { heading_level: level }]
+        end
+        append_converter_tail(fragments, html[matches.last&.end(0).to_i..].to_s)
+      end
+
+      def append_converter_tail(fragments, tail)
+        tail = tail.strip
+        return fragments if tail.empty?
+
+        if fragments.last&.first == :prose
+          fragments.last[1] << tail
+        else
+          fragments << [:prose, tail, { heading_level: nil }]
+        end
+        fragments
+      end
+
+      def merge_prose_fragments(fragments)
+        fragments.each_with_object([]) do |fragment, merged|
+          kind, html, metadata = fragment
+          previous = merged.last
+          if kind == :prose && previous&.first == :prose && metadata[:heading_level].nil?
+            previous[1] << html
+          else
+            merged << fragment
+          end
+        end
+      end
+
+      def render_component(component, source_lines, language, attrs)
+        if source_lines.length > LONG_CODE_LINE_THRESHOLD
+          Support.warn(@warning, "#{component.to_s.capitalize} block has #{source_lines.length} lines and may require scrolling; " \
+                                 "consider splitting it across slides, especially for print.")
+        end
+
+        if component == :editor
+          render_editor(source_lines, language, attrs)
+        elsif component == :terminal
+          render_terminal(source_lines, attrs)
+        else
+          ""
+        end
+      end
+
+      def render_editor(lines, language, attrs)
+        size = normalize_size(attrs["size"])
+        highlight = line_range(attrs["highlight"], max_line: lines.length)
+        focus = line_range(attrs["focus"], max_line: lines.length)
+        line_numbers = line_numbers?(attrs.fetch("line_numbers", "true"))
+        classes = ["code-window", "size-#{size}"] + attrs[:classes].reject { |name| name == "editor" }
+        classes << "has-focus" unless focus.empty?
+        attributes = html_attributes(class: classes.join(" "), id: attrs[:id])
+        header = +'<header class="code-window-header"><span class="code-window-controls" aria-hidden="true"><i></i><i></i><i></i></span>'
+        header << %(<span class="code-window-language">#{Support.escape(language)}</span></header>)
+        caption = attrs["title"] ? %(<figcaption>#{Support.escape(attrs['title'])}</figcaption>) : ""
+        source = lines.map { |line, newline| line + newline }.join
+        highlighted = @rouge_renderer.render_lines(source, language)
+        highlight = highlight.to_set
+        focus = focus.to_set
+        code = lines.each_with_index.map do |(_line, _newline), index|
+          line_classes = ["line"]
+          line_classes << "is-highlighted" if highlight.include?(index + 1)
+          line_classes << "is-focused" if focus.include?(index + 1)
+          line_attrs = { class: line_classes.join(" ") }
+          line_attrs["data-line-number"] = index + 1 if line_numbers
+          %(<span#{html_attributes(line_attrs)}>#{highlighted[index]}</span>)
+        end.join
+        %(<figure#{attributes}>#{caption}#{header}<pre><code>#{code}</code></pre></figure>)
+      end
+
+      def render_terminal(lines, attrs)
+        size = normalize_size(attrs["size"])
+        classes = ["terminal-window", "size-#{size}"] + attrs[:classes].reject { |name| name == "terminal" }
+        figure_attrs = html_attributes(class: classes.join(" "), id: attrs[:id])
+        caption = attrs["title"] ? %(<figcaption>#{Support.escape(attrs['title'])}</figcaption>) : ""
+        body = lines.map do |line, newline|
+          visible = Support.escape(line)
+          if (prompt_match = line.match(/\A([$>❯]) /))
+            prompt = Support.escape(prompt_match[1])
+            rest = Support.escape(line[1..].to_s)
+            visible = %(<span class="prompt">#{prompt}</span><span class="cmd">#{rest}</span>)
+          end
+          %(<span class="tline">#{visible}#{Support.escape(newline)}</span>)
+        end.join
+        %(<figure#{figure_attrs}>#{caption}<pre><code>#{body}</code></pre></figure>)
+      end
+
+      def line_range(value, max_line: nil)
+        RangeParser.parse(value, warning: @warning, max_line: max_line)
+      end
+
+      def line_numbers?(value)
+        case value.to_s.downcase
+        when "true"
+          true
+        when "false"
+          false
+        else
+          Support.warn(@warning, "Invalid line_numbers #{value.inspect}; falling back to true")
+          true
+        end
+      end
+
+      def normalize_size(value)
+        return "md" if value.nil? || value.to_s.empty?
+        return value.to_s if SIZES.include?(value.to_s)
+
+        Support.warn(@warning, "Unsupported component size #{value.inspect}; falling back to md")
+        "md"
+      end
+
+      def html_attributes(values)
+        values.map do |key, value|
+          next if value.nil?
+
+          %( #{key}="#{Support.escape(value)}")
+        end.compact.join
+      end
+    end
+  end
+end

data/lib/jekyll/slides/jekyll_integration.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "jekyll"
+
+module Jekyll
+  module Slides
+    module JekyllIntegration
+      DEFAULTS = {
+        "theme" => "midnight",
+        "aspect_ratio" => "16:9",
+        "progress" => true,
+        "slide_numbers" => true,
+        "overview" => true,
+        "fullscreen" => true
+      }.freeze
+      THEMES = %w[minimal-light minimal-dark midnight ruby].freeze
+      BOOLEAN_OPTIONS = %w[progress slide_numbers overview fullscreen].freeze
+      OPTION_KEYS = DEFAULTS.keys.freeze
+
+      class << self
+        def install!
+          return if @installed
+
+          Jekyll::Hooks.register(:site, :post_read) do |site|
+            process_site(site)
+          end
+          @installed = true
+        end
+
+        def process_site(site)
+          install_resources(site)
+          presentation_documents(site).each { |document| process(document) }
+        end
+
+        def process(document)
+          return unless presentation?(document)
+          return if document.instance_variable_defined?(:@jekyll_slides_processed)
+
+          site = document.site
+          options = normalized_options(site, document.data)
+          source = document.content.to_s
+          document.data.merge!(normalized_data(options, source))
+          document.instance_variable_set(:@renderer, Renderer.new(site, document))
+          document.instance_variable_set(:@jekyll_slides_processed, true)
+        end
+
+        private
+
+        def presentation?(document)
+          document.respond_to?(:data) && document.data.is_a?(Hash) && document.data["layout"].to_s == "presentation"
+        end
+
+        def install_resources(site)
+          site.layouts[LAYOUT_NAME] ||= Layout.new(site)
+          includes_path = File.join(ROOT, "_includes")
+          site.includes_load_paths << includes_path unless site.includes_load_paths.include?(includes_path)
+          Assets.install(site)
+        end
+
+        def presentation_documents(site)
+          collection_documents = site.collections.values.flat_map(&:docs)
+          site.pages + collection_documents
+        end
+
+        def normalized_options(site, front_matter)
+          global = site.config.is_a?(Hash) ? site.config["slides"] : nil
+          if global.nil?
+            global = {}
+          elsif !global.is_a?(Hash)
+            warning("Invalid slides configuration; using defaults")
+            global = {}
+          end
+
+          OPTION_KEYS.to_h do |key|
+            value = front_matter[key]
+            value = global.fetch(key, DEFAULTS[key]) if value.nil?
+            [key, normalize_option(key, value)]
+          end
+        end
+
+        def normalize_option(key, value)
+          case key
+          when "theme"
+            theme = value.to_s
+            return theme if THEMES.include?(theme)
+
+            warning("Invalid theme #{value.inspect}; falling back to midnight")
+            DEFAULTS[key]
+          when "aspect_ratio"
+            return value if value == DEFAULTS[key]
+
+            warning("Invalid aspect ratio #{value.inspect}; quote it in YAML as aspect_ratio: \"16:9\"; falling back to 16:9")
+            DEFAULTS[key]
+          when *BOOLEAN_OPTIONS
+            return value if [true, false].include?(value)
+
+            normalized = value.to_s.strip.downcase
+            return true if normalized == "true"
+            return false if normalized == "false"
+
+            warning("Invalid #{key} option #{value.inspect}; falling back to #{DEFAULTS[key]}")
+            DEFAULTS[key]
+          end
+        end
+
+        def normalized_data(options, source)
+          {
+            "slides_theme" => options["theme"],
+            "slides_aspect_ratio" => options["aspect_ratio"],
+            "slides_progress" => options["progress"],
+            "slides_slide_numbers" => options["slide_numbers"],
+            "slides_overview" => options["overview"],
+            "slides_fullscreen" => options["fullscreen"],
+            "slides_count" => PresentationParser.new(source).parse.length
+          }
+        end
+
+        def warning(message)
+          Jekyll.logger.warn("Jekyll Slides:", message)
+        end
+      end
+    end
+  end
+end
+
+Jekyll::Slides::JekyllIntegration.install!

data/lib/jekyll/slides/layout.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Slides
+    class Layout < Jekyll::Layout
+      def initialize(site)
+        @site = site
+        @base = ROOT
+        @base_dir = ROOT
+        @name = "presentation.html"
+        @path = File.join(ROOT, "_layouts", @name)
+        @relative_path = File.join("_layouts", @name)
+        self.data = {}
+
+        process(@name)
+        read_yaml(File.dirname(@path), @name)
+      end
+    end
+  end
+end

data/lib/jekyll/slides/presentation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Slides
+    # Renders a Markdown deck into slide sections without the page layout.
+    class Presentation
+      # @param markdown [String] Markdown without page YAML front matter
+      # @param warning [#call, nil] receives advisory rendering warnings
+      # @param options [Hash] kramdown options
+      def initialize(markdown, warning: nil, options: {})
+        @markdown = markdown
+        @renderer = SlideRenderer.new(warning: warning, options: options)
+      end
+
+      # @param markdown [String] optional replacement for the initial Markdown
+      # @return [String] rendered slide section HTML
+      def render(markdown = @markdown)
+        @renderer.render(markdown)
+      end
+    end
+  end
+end

data/lib/jekyll/slides/presentation_parser.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+
+module Jekyll
+  module Slides
+    class PresentationParser
+      def self.parse(body)
+        new(body).parse
+      end
+
+      def initialize(body = nil)
+        @body = body.to_s
+      end
+
+      def parse(body = @body)
+        @invalid_front_matter = false
+        @invalid_front_matter_closing = nil
+        @unterminated_front_matter = false
+        source = strip_front_matter(body.to_s)
+        slides = []
+        current = []
+        fence = nil
+
+        source.each_line.with_index do |line, line_index|
+          if fence
+            fence = nil if closing_fence?(line, fence)
+            current << line
+          elsif (opening = fence_line(line))
+            fence = opening
+            current << line
+          elsif slide_separator?(line, line_index)
+            slide = normalize_slide(current.join)
+            slides << slide if slide
+            current = []
+          else
+            current << line
+          end
+        end
+        slide = normalize_slide(current.join)
+        slides << slide if slide
+        slides
+      end
+
+      private
+
+      def slide_separator?(line, line_index)
+        return false unless line.chomp == "---"
+        return false if @unterminated_front_matter && line_index.zero?
+        return false if @invalid_front_matter && [0, @invalid_front_matter_closing].include?(line_index)
+
+        true
+      end
+
+      def strip_front_matter(source)
+        return source unless source.start_with?("---\n", "---\r\n")
+
+        lines = source.lines
+        closing = lines[1..]&.index { |line| line.chomp == "---" }
+        unless closing
+          @unterminated_front_matter = true
+          return source
+        end
+        closing += 1
+
+        front_lines = lines[1...closing]
+        valid = begin
+          parsed = YAML.safe_load(front_lines.join, permitted_classes: [Date, Time, DateTime])
+          front_lines.empty? || parsed.is_a?(Hash)
+        rescue Psych::Exception
+          false
+        end
+        unless valid
+          @invalid_front_matter = true
+          @invalid_front_matter_closing = closing
+          return source
+        end
+        lines[(closing + 1)..]&.join.to_s
+      end
+
+      def normalize_slide(text)
+        return if text.strip.empty?
+
+        text = text.sub(/\A(?:[ \t]*\r?\n)+/, "")
+        text.sub(/(?:\r?\n[ \t]*)+\z/, "")
+      end
+
+      def fence_line(line)
+        match = line.match(/\A( {0,3})(`{3,}|~{3,})([^\r\n]*)\r?\n?\z/)
+        return unless match
+        return if match[2].start_with?("`") && match[3].include?("`")
+
+        { indent: match[1].length, char: match[2][0], length: match[2].length }
+      end
+
+      def closing_fence?(line, fence)
+        line.match?(/\A {0,3}#{Regexp.escape(fence[:char])}{#{fence[:length]},} *\r?\n?\z/)
+      end
+    end
+  end
+end

data/lib/jekyll/slides/range_parser.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Slides
+    class RangeParser
+      # Prevent author-controlled ranges from forcing unbounded allocation.
+      MAX_RANGE_SIZE = 100_000
+
+      class << self
+        def parse(value, warning: nil, max_line: nil)
+          new(value, warning: warning, max_line: max_line).parse
+        end
+      end
+
+      def initialize(value = nil, warning: nil, max_line: nil)
+        @value = value
+        @warning = warning
+        @max_line = max_line
+      end
+
+      def parse
+        return [] if @value.nil? || @value.to_s.strip.empty?
+
+        spans = @value.to_s.split(",", -1).map do |token|
+          token = token.strip
+          case token
+          when /\A([1-9]\d*)\z/
+            number = Regexp.last_match(1).to_i
+            raise ArgumentError if @max_line && number > @max_line
+
+            [number, number]
+          when /\A([1-9]\d*)-([1-9]\d*)\z/
+            first = Regexp.last_match(1).to_i
+            last = Regexp.last_match(2).to_i
+            raise ArgumentError if first > last || last - first + 1 > MAX_RANGE_SIZE
+            raise ArgumentError if @max_line && last > @max_line
+
+            [first, last]
+          else
+            raise ArgumentError
+          end
+        end
+        raise ArgumentError if spans.sum { |first, last| last - first + 1 } > MAX_RANGE_SIZE
+
+        spans.flat_map { |first, last| (first..last).to_a }.uniq.sort
+      rescue ArgumentError
+        Support.warn(@warning, "Invalid line range #{@value.inspect}; ignoring range")
+        []
+      end
+    end
+  end
+end

data/lib/jekyll/slides/renderer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Slides
+    class Renderer < Jekyll::Renderer
+      def convert(content)
+        Presentation.new(
+          content,
+          warning: method(:warning),
+          options: site.config.fetch("kramdown", {})
+        ).render
+      end
+
+      private
+
+      def warning(message)
+        Jekyll.logger.warn("Jekyll Slides:", "#{document.relative_path}: #{message}")
+      end
+    end
+  end
+end

data/lib/jekyll/slides/rouge_renderer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Slides
+    class RougeRenderer
+      def initialize(warning: nil)
+        @warning = warning
+      end
+
+      def render(source, language)
+        lexer = Rouge::Lexer.find(language.to_s)
+        return Support.escape(source.to_s) unless lexer
+
+        Rouge::Formatters::HTML.new.format(lexer.lex(source.to_s))
+      rescue StandardError => e
+        Support.warn(@warning, "Unable to highlight #{language.inspect}: #{e.message}")
+        Support.escape(source.to_s)
+      end
+
+      def render_lines(source, language)
+        source = source.to_s
+        distribute(render(source, language), source)
+      end
+
+      private
+
+      def distribute(html, source)
+        lines = []
+        current = +""
+        open_tags = []
+        html.scan(/<[^>]+>|[^<]+/m).each do |token|
+          if token.start_with?("<")
+            current << token
+            if token.match?(/\A<span\b/)
+              open_tags << token
+            elsif token == "</span>"
+              open_tags.pop
+            end
+            next
+          end
+
+          token.split(/(\r?\n)/, -1).each do |part|
+            if part.match?(/\A\r?\n\z/)
+              current << ("</span>" * open_tags.length) << part
+              lines << current
+              current = +open_tags.join
+            else
+              current << part
+            end
+          end
+        end
+        lines << current unless current.empty?
+        expected = source.lines.length
+        lines.first(expected)
+      end
+    end
+  end
+end