jekyll-database-tables 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b6ef16fd80c0260fe03a2d55fe293a39c7ddfc0350e1ace10199052b034bf0e
+  data.tar.gz: d6e6b26601c76f96bc19bb40ce06fda25bb6cb2de40578579219e93b9870f6d5
+SHA512:
+  metadata.gz: '08d3dcf78d286c9e7c1d522bd8ec38686e5aca1c64614b9a38b44556770a75fa87c76046dc8cb2891c0cbf771e2c2c47069db90c6fb85105b3c9fbd98528a0f6'
+  data.tar.gz: 718f97cbe8be09c7e721137d6a77a9c3559a6cf67a94116393ee9f0c94c2336240c96eee714ef9c8ae7cd452f1ca9103e16e421cbddf549308d8dd4ad42651bf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Aguiar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,117 @@
+# jekyll-database-tables
+
+Render Markdown pipe tables as databse-styled terminal output inside `<pre>` blocks for [Jekyll](https://jekyllrb.com/).
+
+## Installation
+
+Install via RubyGems:
+
+``` bash
+gem install jekyll-database-tables
+```
+
+Or add it to your `Gemfile`:
+
+``` ruby
+gem 'jekyll-database-tables'
+```
+
+Then enable the plugin in `_config.yml`:
+
+``` yaml
+plugins:
+  - jekyll-database-tables
+```
+
+## Usage
+
+Write a standard GFM pipe table in any page or document:
+
+``` markdown
+| Name  | Age |
+|-------|-----|
+| Alice | 30  |
+| Bob   | 25  |
+```
+
+The plugin replaces it with a `<pre class="[db]-table">` block during the build:
+
+``` html
+Name  | Age
+------+----
+Alice | 30
+Bob   | 25
+```
+
+Content inside fenced code blocks is never processed, so example tables in documentation stay intact.
+
+### Configuration
+
+All options go under the `jekyll_database_tables` key in `_config.yml`:
+
+``` yaml
+jekyll_database_tables:
+  formatter: psql
+```
+
+#### Formatters
+
+- **Default (`psql`)**: PostgreSQL-styled terminal output with space-padded columns separated by `|` and a `-+-` divider.
+
+Custom formatters can also be provided (see [Development](#development)).
+
+## Development
+
+### Nix
+
+``` bash
+git clone https://github.com/gdiasag/jekyll-database-tables
+cd jekyll-database-tables
+nix develop
+rake test
+```
+
+Starting a shell with the build environment provided in `flake.nix` provides you with Ruby, Bundler, and all gem dependencies pinned to exact versions from the lock file, so no `bundle install` needed. Gem executables (e.g. `rake` and `rubocop`) are on `PATH` directly.
+
+### Others
+
+Requires [Ruby] v3.3+ and [Bundler] v2.7+.
+
+``` bash
+git clone https://github.com/gdiasag/jekyll-database-tables
+cd jekyll-database-tables
+bundle install
+bundle exec rake test
+```
+
+[Ruby]: https://www.ruby-lang.org/en
+[Bundler]: https://bundler.io
+
+### Writing a custom formatter
+
+Create a subclass of `Jekyll::DatabaseTables::Formatter` implementing `#render`, `#format_row`, and `#separator`. Then register it in `Jekyll::DatabaseTables::Converter#formatter_instance`:
+
+``` ruby
+class CustomFormatter < Jekyll::DatabaseTables::Formatter
+  include Formatter::Helpers
+
+  def render(table, title: nil)
+    # ...
+  end
+
+  def format_row(cells, widths)
+    # ...
+  end
+
+  def separator(widths)
+    # ...
+  end
+end
+```
+
+Users select it via `_config.yml`:
+
+``` yaml
+jekyll_database_tables:
+  formatter: custom
+```

data/lib/jekyll-database-tables/converter.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module DatabaseTables
+    # Scans document content and replaces Markdown pipe tables with
+    # database-style terminal table HTML.
+    #
+    # Lines inside fenced blocks (+```+ or +~~~+) are never treated as tables,
+    # regardless of whether they contain pipe characters.
+    class Converter
+      FENCE_PATTERN = /^\s*(`{3,}|~{3,})/
+
+      # Convenience method - equivalent to +Converter.new(formatter:).call(content)+.
+      #
+      # @param content [String] the raw document content
+      # @param formatter [String] the formatter to use (default: +'psql'+)
+      # @return [String] the content with any Markdown tables converted
+      def self.call(content, formatter: 'psql')
+        new(formatter:).call(content)
+      end
+
+      def initialize(formatter: 'psql')
+        @formatter = formatter
+      end
+
+      # Scans +content+ line by line, buffering pipe-containing lines and
+      # flushing the buffer through {Parser} and {Formatter} whenever a
+      # non-pipe line (or end of input) is reached.
+      #
+      # @param content [String] the raw document content
+      # @return [String] the content with any Markdown tables converted
+      def call(content)
+        lines = content.lines
+        result = +''
+        buffer = []
+        fenced = false
+
+        lines.each do |line|
+          if fenced || !line.include?('|')
+            flush_buffer(result, buffer, line)
+            fenced = !fenced if fence_line?(line)
+          else
+            buffer << line
+          end
+        end
+
+        flush_buffer(result, buffer)
+        result
+      end
+
+      private
+
+      def fence_line?(line)
+        line.match?(FENCE_PATTERN)
+      end
+
+      def flush_buffer(result, buffer, line = nil)
+        result << process_buffer(buffer)
+        buffer.clear
+        result << line if line
+      end
+
+      def process_buffer(buffer)
+        return buffer.join if buffer.empty?
+
+        table = Parser.parse(buffer)
+
+        if table.nil? && buffer.any? { |l| l.match?(Parser::SEPARATOR_PATTERN) }
+          warn "[jekyll-database-tables] Could not parse table: #{buffer.join}"
+        end
+
+        table ? formatter_instance.render(table) : buffer.join
+      end
+
+      def formatter_instance
+        case @formatter
+        when 'psql' then PsqlFormatter.new
+        else raise ArgumentError, "Unknown formatter: #{@formatter.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/jekyll-database-tables/formatters.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module DatabaseTables
+    # Abstract base class for table formatters.
+    #
+    # Subclasses must implement {#render}, {#format_row}, and {#separator}.
+    # Shared rendering utilities are available via {Formatter::Helpers}.
+    class Formatter
+      # Optional mixin providing geometry utilities for formatter subclasses.
+      #
+      # Include this modules to gain access to {#column_widths}, which is useful
+      # for any formatter that needs to align output by column.
+      module Helpers
+        # Computes the minimum column widths needed to fit all cell values.
+        #
+        # @param table [Table] the table to measure
+        # @return [Array<Integer>] the maximum cell width for each column, in order
+        def column_widths(table)
+          col_count = table.headers.length
+          all_rows  = [table.headers] + table.rows.map(&:cells)
+
+          (0...col_count).map do |index|
+            all_rows.map { |row| row[index].to_s.length }.max
+          end
+        end
+      end
+
+      # Renders a {Table} to a string.
+      #
+      # @param table [Table] the table to render
+      # @param title [String, nil] an optional title to display above headers
+      # @return [String] the rendered output
+      # @raise [NotImplementedError] if the subclass does not implement this method
+      def render(table, title: nil)
+        raise NotImplementedError, "#{self.class} must implement #render"
+      end
+
+      # Formats a single row of cells into a string
+      #
+      # @param cells [Array<#to_s>] the cell values to render
+      # @param widths [Array<Integer>] the column widths to align against
+      # @return [String] the formatted row
+      # @raise [NotImplementedError] if the subclass does not implement this method
+      def format_row(cells, widths)
+        raise NotImplementedError, "#{self.class} must implement #format_row"
+      end
+
+      # Renders the separator line between headers and data rows.
+      #
+      # @param widths [Array<Integer>] the column widths to size the separator against
+      # @return [String] the separator line
+      # @raise [NotImplementedError] if the subclass does not implement this method
+      def separator(widths)
+        raise NotImplementedError, "#{self.class} must implement #separator"
+      end
+    end
+
+    # Renders a {Table} as a psql-style terminal table inside a +<pre>+ block.
+    #
+    # Output uses space-padded columns separated by +|+, with a +-+-+ divider
+    # between the header and data rows. Intended to evoke a database query result.
+    #
+    # @example
+    #   puts PsqlFormatter.new.render(table)
+    #
+    #   <pre class="psql-table">
+    #   Name  | Age
+    #   ------+----
+    #   Alice | 30
+    #   </pre>
+    class PsqlFormatter < Formatter
+      include Formatter::Helpers
+
+      # Renders the table as a +<pre class="psql-table">+ block.
+      #
+      # @param table [Table] the table to render
+      # @param title [String, nil] an optional title, centered above the headers
+      # @return [String] the HTML +<pre>+ block
+      def render(table, title: nil)
+        widths = column_widths(table)
+
+        lines = +''
+        lines << "#{title.center(total_width(widths)).rstrip}\n" if title
+
+        lines << format_row(table.headers, widths)
+        lines << "\n"
+        lines << separator(widths)
+        lines << "\n"
+
+        table.rows.each do |row|
+          lines << format_row(row.cells, widths)
+          lines << "\n"
+        end
+
+        "<pre class=\"psql-table\">\n#{lines}</pre>\n"
+      end
+
+      # Formats a row as space-padded cells joined by +|+.
+      #
+      # @param cells [Array<#to_s>] the cell values to render
+      # @param widths [Array<Integer>] the column widths to left-justify against
+      # @return [String] the formatted row, with trailing whitespace stripped
+      def format_row(cells, widths)
+        cells.each_with_index.map do |cell, i|
+          cell.to_s.ljust(widths[i])
+        end.join(' | ').rstrip
+      end
+
+      # Renders a +-+-+ separator sized to the given column widths.
+      #
+      # @param widths [Array<Integer>] the column widths
+      # @return [String] the separator line
+      def separator(widths)
+        widths.map { |w| '-' * w }.join('-+-')
+      end
+
+      private
+
+      def total_width(widths)
+        widths.sum + ((widths.length - 1) * 3)
+      end
+    end
+  end
+end

data/lib/jekyll-database-tables/parser.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module DatabaseTables
+    # Parsers an array of Markdown table lines into a {Table}.
+    #
+    # Accepts both fenced (`| col |`) and unfenced (`col |`) pipe styles.
+    # Returns +nil+ for any input that does not constitute a valid table.
+    module Parser
+      # Matches a GFM table separator line.
+      SEPARATOR_PATTERN = /^\|?[\s:-]+\|/
+
+      module_function
+
+      # Parses a buffer of lines into a {Table}.
+      #
+      # Expects at least two lines where the second matches {SEPARATOR_PATTERN}.
+      # Any additional lines are treated as data rows.
+      #
+      # @param lines [Array<String>] raw lines from the document buffer
+      # @return [Table, nil] the parsed table, or +nil+ if the input isn't valid
+      def parse(lines)
+        return if lines.length < 2
+        return unless lines[1].match?(SEPARATOR_PATTERN)
+
+        headers = split_cells(lines[0])
+        rows    = lines.drop(2).map { |line| Row.new(split_cells(line)) }
+
+        Table.new(headers:, rows:)
+      end
+
+      def split_cells(line)
+        line
+          .strip
+          .delete_prefix('|')
+          .delete_suffix('|')
+          .split('|')
+          .map(&:strip)
+      end
+    end
+  end
+end

data/lib/jekyll-database-tables/table.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module DatabaseTables
+    # Immutable value object representing a parsed Markdown file.
+    #
+    # @!attribute [r] headers
+    #   @return [Array<String>] the column header labels
+    # @!attribute [r] rows
+    #   @return [Array<Row>] the data rows, in document order
+    Table = Data.define(:headers, :rows)
+
+    # Immutable value object representing a single table row.
+    #
+    # @!attribute [r] cells
+    #   @return [Array<String>] the cell values for this row, in column order
+    Row   = Data.define(:cells)
+  end
+end

data/lib/jekyll-database-tables/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module DatabaseTables
+    VERSION = '0.1.0'
+  end
+end

data/lib/jekyll-database-tables.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'jekyll'
+
+require 'jekyll-database-tables/version'
+require 'jekyll-database-tables/table'
+require 'jekyll-database-tables/parser'
+require 'jekyll-database-tables/formatters'
+require 'jekyll-database-tables/converter'
+
+Jekyll::Hooks.register [:pages, :documents], :pre_render do |doc|
+  formatter = doc.site.config.dig('jekyll_database_tables', 'formatter') || 'psql'
+
+  doc.content = Jekyll::DatabaseTables::Converter.call(doc.content, formatter:)
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-database-tables
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gustavo Aguiar
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+email:
+- gdiasag@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- LICENSE
+- README.md
+- lib/jekyll-database-tables.rb
+- lib/jekyll-database-tables/converter.rb
+- lib/jekyll-database-tables/formatters.rb
+- lib/jekyll-database-tables/parser.rb
+- lib/jekyll-database-tables/table.rb
+- lib/jekyll-database-tables/version.rb
+homepage: https://github.com/gdiasag/jekyll-database-tables
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: A Jekyll plugin to render markdown tables as database-styled terminal outputs
+test_files: []