shoreditch 1.1.0

data/components/shoreditch/comments.erb

@@ -0,0 +1,25 @@
+<section class="sd-comments">
+  <h2>Comments</h2>
+
+  <%# data-theme follows the OS preference on load; shoreditch.js re-syncs it
+      through Giscus's postMessage API when the reader uses the theme toggle,
+      so the comment thread does not stay light on a dark page. %>
+  <script
+    src="https://giscus.app/client.js"
+    data-repo="<%= repo %>"
+    data-repo-id="<%= repo_id %>"
+    data-category="<%= category %>"
+    data-category-id="<%= category_id %>"
+    data-mapping="pathname"
+    data-strict="1"
+    data-reactions-enabled="1"
+    data-emit-metadata="0"
+    data-input-position="bottom"
+    data-theme="preferred_color_scheme"
+    data-lang="en"
+    crossorigin="anonymous"
+    async
+  ></script>
+
+  <noscript>Comments need JavaScript. They are also readable as GitHub Discussions on the repository.</noscript>
+</section>

data/components/shoreditch/comments.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# The comments slot.
+#
+# The theme ships Giscus (comments stored as GitHub Discussions) as the one
+# provider it knows how to configure, but nothing here is Giscus-specific from
+# a consuming site's point of view: a site that wants something else overrides
+# this component by putting its own `components/shoreditch/comments.erb` in
+# place. Site files take precedence over the gem's source manifest, so no fork
+# and no layout copy is needed.
+#
+# Off unless configured. Set in config/initializers.rb:
+#
+#   init :shoreditch do
+#     comments({
+#       repo: "you/your-repo", repo_id: "R_...",
+#       category: "Comments",  category_id: "DIC_...",
+#     })
+#   end
+#
+# The four values come from https://giscus.app after enabling Discussions on
+# the repository. A single post opts out with `comments: false` in front matter.
+class Shoreditch::Comments < Bridgetown::Component
+  def initialize(site:, resource:)
+    @site = site
+    @resource = resource
+  end
+
+  attr_reader :site, :resource
+
+  def render?
+    resource.data.comments != false && settings.is_a?(Hash) && required_keys_present?
+  end
+
+  def settings
+    site.config.shoreditch[:comments]
+  end
+
+  # Giscus silently renders nothing if any of these are missing, which is a
+  # miserable thing to debug, so treat a partial config as "off".
+  def required_keys_present?
+    %i[repo repo_id category category_id].all? { |key| settings[key].to_s.strip != "" }
+  end
+
+  def repo = settings[:repo].to_s
+  def repo_id = settings[:repo_id].to_s
+  def category = settings[:category].to_s
+  def category_id = settings[:category_id].to_s
+end

data/components/shoreditch/details.erb

@@ -0,0 +1,52 @@
+<ul class="sd-details">
+  <% links.each do |key, icon_name, href, text| %>
+    <li data-network="<%= key %>">
+      <a href="<%= href %>" rel="me noopener">
+        <svg class="sd-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+          <path d="<%= icon(icon_name) %>" />
+        </svg>
+        <%= text %>
+      </a>
+    </li>
+  <% end %>
+
+  <% if phone != "" %>
+    <li data-network="phone">
+      <a href="tel:<%= phone.gsub(/[^0-9+]/, "") %>">
+        <svg class="sd-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+          <path d="<%= icon(:phone) %>" />
+        </svg>
+        <%= phone %>
+      </a>
+    </li>
+  <% end %>
+
+  <% if email? %>
+    <%# The two halves are only joined in the browser — see shoreditch.js. %>
+    <li data-network="email">
+      <a
+        class="sd-email"
+        href="#"
+        hidden
+        data-sd-email-user="<%= email_parts.first %>"
+        data-sd-email-host="<%= email_parts.last %>"
+      >
+        <svg class="sd-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+          <path d="<%= icon(:email) %>" />
+        </svg>
+        Email
+      </a>
+    </li>
+  <% end %>
+
+  <% if file_url != "" %>
+    <li data-network="file">
+      <a href="<%= file_url %>" rel="noopener">
+        <svg class="sd-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+          <path d="<%= icon(:file) %>" />
+        </svg>
+        <%= file_link_text %>
+      </a>
+    </li>
+  <% end %>
+</ul>

data/components/shoreditch/details.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# The contact panel: how to reach the author, and where else they are.
+#
+# Restored from the Jekyll theme's `_includes/details.html`, with two changes.
+# Icons are inlined from the vendored Simple Icons set rather than pulled from
+# a Font Awesome CDN kit on every page load, and the markup is a definition of
+# links rather than a list of hard-coded network blocks, so adding a network is
+# one entry in ENTRIES.
+#
+# Everything is driven by `author` in src/_data/site_metadata.yml. A page opts
+# in with `include_details: true` in its front matter — off elsewhere, since a
+# blog post has no use for a phone number.
+class Shoreditch::Details < Bridgetown::Component
+  # network key => [icon, url template, label]. `%s` takes the handle.
+  ENTRIES = [
+    [:github,     :github,     "https://github.com/%s",         "%s"],
+    [:mastodon,   :mastodon,   "%s",                            "Mastodon"],
+    [:linkedin,   :link,       "https://linkedin.com/in/%s",    "%s"],
+    [:twitter,    :x,          "https://x.com/%s",              "@%s"],
+    [:instagram,  :instagram,  "https://instagram.com/%s",      "%s"],
+    [:reddit,     :reddit,     "https://reddit.com/user/%s",    "%s"],
+    [:youtube,    :youtube,    "%s",                            "YouTube"],
+    [:tiktok,     :tiktok,     "https://tiktok.com/@%s",        "%s"],
+    [:lastfm,     :lastfm,     "https://last.fm/user/%s",       "%s"],
+    [:deviantart, :deviantart, "https://deviantart.com/%s",     "%s"],
+    [:artstation, :artstation, "https://artstation.com/%s",     "%s"],
+  ].freeze
+
+  def initialize(site:, resource:)
+    @site = site
+    @resource = resource
+  end
+
+  attr_reader :site, :resource
+
+  # Not `author.present?`: site.metadata is a HashWithDotAccess::Hash, which
+  # routes unknown methods to key lookups, so `present?` returns nil for a
+  # missing "present" key rather than calling ActiveSupport. Only methods Hash
+  # genuinely defines are safe to call on it.
+  def render?
+    resource.data.include_details == true && author.is_a?(Hash) && !author.empty?
+  end
+
+  def author
+    site.metadata.author
+  end
+
+  # [key, icon, href, text] for each network the site actually filled in. The
+  # key and the icon are separate because they diverge: LinkedIn is styled as
+  # linkedin but drawn with the generic `link` mark.
+  def links
+    ENTRIES.filter_map do |key, icon, url, label|
+      handle = author[key.to_s].to_s.strip
+      next if handle.empty?
+
+      [key, icon, format(url, handle), format(label, handle)]
+    end
+  end
+
+  def phone = author["phone"].to_s.strip
+
+  def file_url = author["file_url"].to_s.strip
+
+  def file_link_text
+    text = author["file_link_text"].to_s.strip
+    text.empty? ? "Download" : text
+  end
+
+  # Kept split across two metadata keys, as the Jekyll version had it, so the
+  # address never appears whole in the HTML for a crawler to lift. Assembled by
+  # shoreditch.js. Without JavaScript the address is simply not shown, which is
+  # the trade the original made too.
+  def email_parts
+    [author["email_1"].to_s.strip, author["email_2"].to_s.strip]
+  end
+
+  def email? = email_parts.none?(&:empty?)
+
+  def icon(name)
+    Shoreditch::ICONS[name]
+  end
+end

data/components/shoreditch/head_icons.erb

@@ -0,0 +1,12 @@
+<% if favicon %>
+  <link rel="shortcut icon" href="<%= favicon %>" />
+<% end %>
+<% apple_icons.each do |size, path| %>
+  <link rel="apple-touch-icon" sizes="<%= size %>" href="<%= path %>" />
+<% end %>
+<% png_icons.each do |size, path| %>
+  <link rel="icon" type="image/png" sizes="<%= size %>" href="<%= path %>" />
+<% end %>
+<% if manifest %>
+  <link rel="manifest" href="<%= manifest %>" />
+<% end %>

data/components/shoreditch/head_icons.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Favicon and touch-icon links.
+#
+# Only emitted for files the site actually has. The Jekyll theme hard-coded the
+# full apple-touch-icon set, which meant every site using the theme requested a
+# dozen icons whether or not they existed.
+class Shoreditch::HeadIcons < Bridgetown::Component
+  APPLE_SIZES = %w[57x57 60x60 72x72 76x76 114x114 120x120 144x144 152x152 180x180].freeze
+  PNG_SIZES = %w[16x16 32x32 96x96 192x192].freeze
+
+  def initialize(site:, prefix: "")
+    @site = site
+    @prefix = prefix
+  end
+
+  def apple_icons
+    APPLE_SIZES.filter_map do |size|
+      path = "#{@prefix}/apple-icon-#{size}.png"
+      [size, path] if exists?(path)
+    end
+  end
+
+  def png_icons
+    PNG_SIZES.filter_map do |size|
+      # The 192px icon is named for Android; the rest are plain favicons.
+      name = size == "192x192" ? "android-icon-192x192" : "favicon-#{size}"
+      path = "#{@prefix}/#{name}.png"
+      [size, path] if exists?(path)
+    end
+  end
+
+  def favicon
+    path = "#{@prefix}/favicon.ico"
+    path if exists?(path)
+  end
+
+  def manifest
+    path = "#{@prefix}/manifest.json"
+    path if exists?(path)
+  end
+
+  private
+
+  def exists?(path)
+    File.exist?(File.join(@site.config.source, path))
+  end
+end

data/components/shoreditch/post_summary.erb

@@ -0,0 +1,19 @@
+<article class="sd-post-summary">
+  <% if thumbnail %>
+    <a class="sd-post-thumbnail" href="<%= post.relative_url %>" tabindex="-1" aria-hidden="true">
+      <img src="<%= thumbnail %>" alt="" loading="lazy" />
+    </a>
+  <% end %>
+
+  <div class="sd-post-detail">
+    <p class="sd-post-dates">
+      <time datetime="<%= date_attr %>"><%= date_text %></time>
+    </p>
+    <h2><a href="<%= post.relative_url %>"><%= post.data.title %></a></h2>
+    <%# Wrapped so the excerpt can be clamped and flattened as a unit: the
+        summary is whatever block the post opens with, which may be a
+        blockquote or a {:.message}, and an index preview has to read the same
+        whichever it is. %>
+    <div class="sd-post-excerpt"><%= summary %></div>
+  </div>
+</article>

data/components/shoreditch/post_summary.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# One entry in an index listing — used by both the home page and tag pages.
+class Shoreditch::PostSummary < Bridgetown::Component
+  def initialize(post:)
+    @post = post
+  end
+
+  attr_reader :post
+
+  def thumbnail
+    post.data.thumbnail
+  end
+
+  def date_text
+    post.date.strftime("%-d %B %Y")
+  end
+
+  def date_attr
+    post.date.strftime("%Y-%m-%d")
+  end
+
+  # Bridgetown's own summary is the first *source line*. The demo's markdown is
+  # hard-wrapped at 80 columns, so that cut three of four excerpts off
+  # mid-clause and left the paragraph unclosed. An explicit <!--more--> marker
+  # wins; otherwise take the first complete paragraph.
+  def summary
+    html = post.content.to_s
+    excerpt =
+      if (marker = html.index("<!--more-->"))
+        html[0...marker]
+      else
+        html[%r{\A.*?</p>}m] || html
+      end
+    excerpt.strip.html_safe
+  end
+end

data/components/shoreditch/sidebar.erb

@@ -0,0 +1,64 @@
+<aside class="sd-sidebar">
+  <div class="sd-logo-area">
+    <% if logo_source %>
+      <a href="<%= site.metadata.logo_link || "/" %>">
+        <img
+          class="sd-logo"
+          data-shape="<%= logo_shape %>"
+          data-flashy="<%= flashy_logo? %>"
+          src="<%= logo_source %>"
+          alt="<%= site.metadata.title %>"
+        />
+      </a>
+    <% end %>
+
+    <% if logo_legend %>
+      <span class="sd-logo-legend" data-shape="<%= logo_legend_shape %>"><%= logo_legend %></span>
+    <% end %>
+
+    <%# `include_sticky: false` in front matter drops the site identity and the
+        navigation, leaving the logo and badge to introduce a person instead. %>
+    <% if sticky? %>
+      <div class="sd-site-identity">
+        <p class="sd-site-title"><a href="/"><%= site.metadata.title %></a></p>
+        <% if site.metadata.tagline %>
+          <p class="sd-site-tagline"><%= site.metadata.tagline %></p>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+
+  <%# The contact panel belongs with the identity above it, not with the
+      navigation — on a CV the logo, name and contact details read as one block. %>
+  <%= render Shoreditch::Details.new(site: site, resource: resource) %>
+
+  <%# Everything from here sits at the foot of the column: the identity stays
+      at the top where the eye starts, the menu and the footer drop to the
+      bottom. One auto margin on this wrapper does it, which is why the nav and
+      footer are grouped rather than each pushed down separately — two auto
+      margins would split the free space and strand the nav in the middle. %>
+  <div class="sd-sidebar-bottom">
+    <% if sticky? && nav_pages.any? %>
+      <nav class="sd-nav" aria-label="Main">
+        <% nav_pages.each do |page| %>
+          <%# The attribute is always present and only its value varies, because
+              ERB escapes interpolated output — injecting the whole attribute
+              rendered it as aria-current=&quot;page&quot; and the
+              a[aria-current="page"] rule never matched. "false" is the value
+              ARIA defines for "not the current item". %>
+          <a
+            href="<%= page.relative_url %>"
+            aria-current="<%= current?(page) ? "page" : "false" %>"
+          ><%= page.data.title %></a>
+        <% end %>
+      </nav>
+    <% end %>
+
+    <div class="sd-sidebar-footer">
+      <button class="sd-theme-toggle" type="button" data-shoreditch-theme-toggle>
+        Switch theme
+      </button>
+      <p>&copy; <%= Time.now.year %> <%= site.metadata.author&.name || site.metadata.title %></p>
+    </div>
+  </div>
+</aside>

data/components/shoreditch/sidebar.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# The fixed left column: logo, site identity, navigation and footer.
+#
+# Navigation is drawn from pages that opt in with `nav_order` in their front
+# matter, so a site controls the menu from its content rather than from theme
+# configuration. Pages with `exclude: true` never appear.
+class Shoreditch::Sidebar < Bridgetown::Component
+  def initialize(site:, resource:)
+    @site = site
+    @resource = resource
+  end
+
+  # Components get no implicit access to the site, so it is passed in and
+  # exposed for the template.
+  attr_reader :site
+
+  def options
+    @site.config.shoreditch
+  end
+
+  def nav_pages
+    @site.collections.pages.resources
+      .reject { |page| page.data.exclude }
+      .select { |page| page.data.nav_order }
+      .sort_by { |page| [page.data.nav_order, page.data.title.to_s] }
+  end
+
+  def current?(page)
+    page.relative_url == @resource.relative_url
+  end
+
+  attr_reader :resource
+
+  def logo_source
+    return nil if @resource.data.include_logo == false
+
+    @resource.data.logo_location || @site.metadata.logo
+  end
+
+  # `include_sticky: false` drops the site title, tagline and navigation. The
+  # CV page used it so its sidebar introduced a person rather than a site.
+  def sticky?
+    @resource.data.include_sticky != false
+  end
+
+  # A page can override the logo's shape, as the Jekyll version allowed.
+  def logo_shape
+    @resource.data.logo_shape || options[:logo_shape]
+  end
+
+  # "round" or "straight" — the badge under the logo, shaped independently.
+  def logo_legend_shape
+    @resource.data.logo_legend_shape || options[:logo_legend_shape] || "round"
+  end
+
+  def flashy_logo?
+    @resource.data.flashy_logo == true
+  end
+
+  def logo_legend
+    # A page can override the badge, or suppress it by setting it to false.
+    return @resource.data.logo_legend if @resource.data.key?("logo_legend")
+
+    options[:logo_legend]
+  end
+end