datalog-theme 0.7.0 → 0.9.0

data/datalog-theme.gemspec

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "lib/datalog/theme/version"
+require_relative "lib/datalog/theme/package"
 
 Gem::Specification.new do |spec|
   spec.name          = "datalog-theme"
@@ -23,7 +24,9 @@ Gem::Specification.new do |spec|
   spec.metadata["plugin_type"]       = "theme"
   spec.metadata["orcid"]             = "https://orcid.org/0009-0001-2022-7072"
 
-  spec.required_ruby_version = ">= 3.0"
+  # The sass-embedded and nokogiri releases the theme is tested with need Ruby
+  # 3.2; the gemspec said 3.0.
+  spec.required_ruby_version = Datalog::Theme::RUBY_REQUIREMENT
   spec.require_paths = ["lib"]
   spec.bindir = "bin"
   spec.executables = ["datalog"]
@@ -31,10 +34,13 @@ Gem::Specification.new do |spec|
   # Ship only theme infrastructure — not demo content (_posts, _pages, _portfolio,
   # _datasets, _packages, _notebooks, tests, docs, scripts, CI configs, frontend
   # tooling, Dockerfiles, etc.). Theme consumers get layouts/includes/sass/assets/
-  # plugins/data/lib/bin and the licensing/changelog metadata.
+  # plugins/data/lib/bin and the licensing/changelog metadata. Within _data and
+  # assets, the demo site's own files (its navigation, social profiles, author
+  # profile, CV and publication exports) stay out: see Datalog::Theme::Package.
   spec.files = Dir.chdir(__dir__) do
     tracked = `git ls-files -z`.split("\x0").select do |f|
-      f.match?(%r{\A(?:_layouts|_includes|_sass|_plugins|_data|assets|lib|bin)/}) ||
+      (f.match?(%r{\A(?:_layouts|_includes|_sass|_plugins|_data|assets|lib|bin)/}) &&
+        Datalog::Theme::Package.theme_file?(f)) ||
         %w[
           LICENSE
           README.md
@@ -47,32 +53,38 @@ Gem::Specification.new do |spec|
     # The browser bundles are build output, so git does not track them, but
     # _data/js_manifest.json points every page at them: a gem without them
     # gives consumers a site whose scripts all 404. Run `npm run build:js`
-    # before packaging; scripts/verify_gem_package.rb checks the result.
-    built = Dir.glob("assets/js/dist/**/*").select { |f| File.file?(f) }
+    # before packaging; scripts/verify_gem_package.rb checks the result. The
+    # esbuild metafile and the copy of the manifest written next to the bundles
+    # are records of the build that no page loads, so they stay out.
+    built = Dir.glob("assets/js/dist/**/*").select { |f| File.file?(f) } -
+            %w[assets/js/dist/manifest.json assets/js/dist/meta.json]
 
     (tracked + built).uniq.sort
   end
 
+  # Each dependency stops below its next major version, so a breaking release
+  # reaches sites through a pull request that updates this file rather than an
+  # untested `bundle update`.
   spec.add_runtime_dependency "jekyll", "~> 4.3"
   spec.add_runtime_dependency "jekyll-sass-converter", "~> 3.0"
-  spec.add_runtime_dependency "jekyll-feed", ">= 0.16"
-  spec.add_runtime_dependency "jekyll-seo-tag", ">= 2.8"
-  spec.add_runtime_dependency "jekyll-sitemap", ">= 1.4"
-  spec.add_runtime_dependency "sass-embedded", ">= 1.71"
-  spec.add_runtime_dependency "jekyll-paginate", ">= 1.1"
-  spec.add_runtime_dependency "jekyll-include-cache", ">= 0.2"
-  spec.add_runtime_dependency "jekyll-archives", ">= 2.2"
-  spec.add_runtime_dependency "jekyll-remote-theme", ">= 0.4"
-  spec.add_runtime_dependency "jekyll-redirect-from", ">= 0.16"
-  spec.add_runtime_dependency "kramdown-parser-gfm", ">= 1.1"
-  spec.add_runtime_dependency "webrick", ">= 1.8"
-  spec.add_runtime_dependency "fastimage", ">= 2.2"
-  spec.add_runtime_dependency "loofah", ">= 2.19"
-  spec.add_runtime_dependency "nokogiri", ">= 1.15"
-  spec.add_runtime_dependency "mini_magick", ">= 4.12"
-  spec.add_runtime_dependency "logger", ">= 1.6"
-  spec.add_runtime_dependency "thor", ">= 1.3"
-  spec.add_runtime_dependency "googleauth", ">= 1.9"
+  spec.add_runtime_dependency "jekyll-feed", "~> 0.16"
+  spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.8"
+  spec.add_runtime_dependency "jekyll-sitemap", "~> 1.4"
+  spec.add_runtime_dependency "sass-embedded", "~> 1.71"
+  spec.add_runtime_dependency "jekyll-paginate", "~> 1.1"
+  spec.add_runtime_dependency "jekyll-include-cache", "~> 0.2"
+  spec.add_runtime_dependency "jekyll-redirect-from", "~> 0.16"
+  spec.add_runtime_dependency "kramdown-parser-gfm", "~> 1.1"
+  spec.add_runtime_dependency "webrick", "~> 1.8"
+  spec.add_runtime_dependency "fastimage", "~> 2.2"
+  spec.add_runtime_dependency "loofah", "~> 2.19"
+  spec.add_runtime_dependency "nokogiri", "~> 1.15"
+  spec.add_runtime_dependency "logger", "~> 1.6"
+  spec.add_runtime_dependency "thor", "~> 1.3"
+  # googleauth, with the Google Cloud gems it brings, is needed only by the
+  # analytics dashboard with a GA4 property configured, and such a site adds it
+  # to its own Gemfile. jekyll-archives and jekyll-remote-theme were listed here
+  # but used by nothing in the theme.
 
   spec.add_development_dependency "bundler", ">= 2.4"
   spec.add_development_dependency "rake", ">= 13.0"

data/lib/datalog/cli.rb

@@ -83,19 +83,27 @@ module Datalog
       branch = options[:branch]
       message = options[:message] || "Publish DataLog site on #{Time.now.utc.strftime('%Y-%m-%d %H:%M UTC')}"
 
-      say_status :build, "bundle exec jekyll build", :blue
-      unless system({ "BUNDLE_GEMFILE" => gemfile_path(root) }, "bundle exec jekyll build", chdir: root)
+      # A deployment is a production build: without JEKYLL_ENV the published
+      # site left out the analytics tag and shipped the development CSP logger.
+      build_env = { "BUNDLE_GEMFILE" => gemfile_path(root), "JEKYLL_ENV" => "production" }
+      say_status :build, "JEKYLL_ENV=production bundle exec jekyll build", :blue
+      unless system(build_env, "bundle exec jekyll build", chdir: root)
         say_error "Jekyll build failed. Resolve the error above and try again."
         exit 1
       end
 
+      published = false
       Dir.mktmpdir("datalog-publish") do |tmp|
         worktree_path = File.join(tmp, "deploy")
         prepare_worktree(root, branch, worktree_path)
-        copy_site_output(root, worktree_path)
-        commit_and_push(worktree_path, branch, message)
-        cleanup_worktree(root, worktree_path)
+        begin
+          copy_site_output(root, worktree_path)
+          published = commit_and_push(worktree_path, branch, message)
+        ensure
+          cleanup_worktree(root, worktree_path)
+        end
       end
+      exit 1 unless published
     end
 
     desc "update", "Update the DataLog theme and related assets to the latest version"
@@ -182,23 +190,26 @@ module Datalog
           exit 1
         end
 
+        # Values go in as JSON strings, which YAML reads as double-quoted scalars.
+        # Interpolated between plain quotes, a title containing a double quote
+        # or a tag containing a colon produced front matter that did not parse.
         tags_yaml = if tags.empty?
                       "[]"
                     else
-                      "\n" + tags.map { |tag| "  - #{tag}" }.join("\n")
+                      "\n" + tags.map { |tag| "  - #{tag.to_json}" }.join("\n")
                     end
         front_matter = <<~YAML
           ---
           layout: post
-          title: "#{title}"
-          description: "#{summary}"
-          author: "#{author}"
+          title: #{title.to_json}
+          description: #{summary.to_json}
+          author: #{author.to_json}
           date: #{date.strftime('%Y-%m-%d')}
           tags:#{tags_yaml}
-          difficulty: "#{difficulty}"
+          difficulty: #{difficulty.to_json}
           hero:
             image: /assets/images/#{slug}.jpg
-            alt: "Hero image for #{title}"
+            alt: #{"Hero image for #{title}".to_json}
           callouts:
             - label: Key takeaway
               content: Highlight the most important insight from the post.
@@ -411,6 +422,14 @@ module Datalog
       end
     end
 
+    desc "critical-css", "Write the critical CSS a production build inlines, into _includes/critical-css"
+    method_option :critical, type: :array,
+                             desc: "Command that runs critical (default: node_modules/.bin/critical or npx critical@8)"
+    def critical_css
+      require_relative "critical_css"
+      CriticalCss.command(site_root, options[:critical], ->(*line) { say_status(*line) })
+    end
+
     register(New, "new", "new COMMAND", "Scaffold posts, notebooks, and portfolio projects")
 
     private
@@ -428,7 +447,7 @@ module Datalog
     end
 
     def ruby_supported?
-      Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.0.0")
+      Gem::Requirement.new(Datalog::Theme::RUBY_REQUIREMENT).satisfied_by?(Gem::Version.new(RUBY_VERSION))
     end
 
     def gemfile_path(root)
@@ -553,17 +572,26 @@ module Datalog
       end
     end
 
+    # Returns whether the branch now holds the site. The exit status of commit
+    # and push used to be ignored, so a rejected push still ended as a publish.
     def commit_and_push(worktree_path, branch, message)
       Dir.chdir(worktree_path) do
         system("git", "add", "--all")
         if system("git", "diff", "--cached", "--quiet")
           say_status :skip, "No changes to publish", :yellow
-          return
+          return true
+        end
+
+        unless system("git", "commit", "-m", message)
+          say_error "git commit failed, so nothing was published."
+          return false
         end
 
-        system("git", "commit", "-m", message)
         say_status :git, "git push origin #{branch}", :blue
-        system("git", "push", "origin", branch)
+        return true if system("git", "push", "origin", branch)
+
+        say_error "git push to #{branch} failed, so the site was not published."
+        false
       end
     end
 

data/lib/datalog/critical_css.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+require "jekyll"
+require "open3"
+require "tmpdir"
+require "yaml"
+
+module Datalog
+  # Writes the critical CSS a production build inlines. head.html inlines
+  # _includes/critical-css/<target>.html for a page's layout (home, post, or
+  # default for every other layout) and then loads main.css without blocking
+  # rendering. Critical CSS depends on a site's own pages and styles, so the
+  # theme ships those files empty and each site writes its own with
+  # `datalog critical-css`.
+  class CriticalCss
+    TARGETS = %w[home post default].freeze
+    DEFAULT_DIMENSIONS = [{ "width" => 1920, "height" => 1080 }, { "width" => 375, "height" => 667 }].freeze
+    PACKAGE = "critical@8"
+
+    class Error < StandardError; end
+
+    attr_reader :root, :settings
+
+    # `datalog critical-css`. status reports a line as the command's shell
+    # does; an error ends the command with exit status 1.
+    def self.command(root, critical, status)
+      config = YAML.safe_load_file(File.join(root, "_config.yml"), permitted_classes: [Date, Time]) || {}
+      log = ->(message) { status.call(:critical, message, :blue) }
+      written = new(root, config["critical_css"], critical: critical, log: log).run
+      written.each_value { |path| status.call(:write, path, :green) }
+    rescue Error, Jekyll::Errors::FatalException, SystemCallError => e
+      status.call(:error, e.message, :red)
+      exit 1
+    end
+
+    # critical: the command that runs critical, as a list of words. By default
+    # the site's own node_modules/.bin/critical, or `npx --yes critical@8`.
+    def initialize(root, settings, critical: nil, log: ->(_message) {})
+      @root = File.expand_path(root)
+      @settings = settings || {}
+      @critical = critical
+      @log = log
+    end
+
+    # Returns the files written, by target. A target with no page to extract
+    # from, such as post on a site without posts, is left as it is.
+    def run
+      unless settings["enabled"] == true
+        raise Error, "critical_css.enabled is not true in _config.yml, so no page would inline critical CSS"
+      end
+
+      Dir.mktmpdir("datalog-critical") do |site_dir|
+        @log.call("Building the site for production into a temporary directory")
+        build(site_dir)
+        pages_for(site_dir).each_with_object({}) do |(target, page), written|
+          if page.nil?
+            @log.call("No page uses the #{target} layout; _includes/critical-css/#{target}.html is left as it is")
+            next
+          end
+
+          @log.call("Extracting critical CSS for #{target} from #{page}")
+          written[target] = write(target, extract(site_dir, page))
+        end
+      end
+    end
+
+    # A production build, with critical CSS turned off for it: pages then link
+    # main.css as usual, and CSS inlined by an earlier run cannot skew the result.
+    def build(destination)
+      previous = ENV.fetch("JEKYLL_ENV", nil)
+      ENV["JEKYLL_ENV"] = "production"
+      config = Jekyll.configuration(
+        "source" => root, "destination" => destination, "quiet" => true,
+        "critical_css" => settings.merge("enabled" => false)
+      )
+      Jekyll::Site.new(config).process
+    ensure
+      ENV["JEKYLL_ENV"] = previous
+    end
+
+    # The page each target extracts from: the one critical_css.pages names, or
+    # the first built page with that layout, nearest the site root first.
+    def pages_for(site_dir)
+      configured = settings["pages"] || {}
+      found = TARGETS.to_h { |target| [target, configured[target] && page_file(site_dir, configured[target])] }
+      missing = TARGETS.reject { |target| found[target] }
+
+      html_files(site_dir).each do |page|
+        break if missing.empty?
+
+        target = target_of(File.read(File.join(site_dir, page), encoding: "utf-8"))
+        next unless missing.delete(target)
+
+        found[target] = page
+      end
+      found
+    end
+
+    # Mirrors head.html: the home and post layouts have their own file, and
+    # every other page the theme's default layout renders uses default. Pages
+    # kept out of search engines, such as the search page, are not typical.
+    def target_of(html)
+      classes = html[/<body\b[^>]*\bclass="([^"]*)"/, 1].to_s.split
+      return unless classes.include?("site-body")
+      return "home" if classes.include?("layout-home")
+      return "post" if classes.include?("layout-post")
+
+      "default" unless html.match?(/<meta name="robots" content="noindex/)
+    end
+
+    # Only the site's stylesheet: the Google Fonts stylesheet would inline
+    # @font-face rules for the font files headless Chrome is served (TrueType),
+    # and fetching it made each page take over a minute.
+    def extract(site_dir, page)
+      arguments = [page, "--base", site_dir, "--css", File.join(site_dir, "assets", "css", "main.css"),
+                   *dimension_arguments, *penthouse_arguments]
+      output, errors, status = Open3.capture3(*critical_command, *arguments, chdir: site_dir)
+      unless status.success?
+        raise Error, "critical could not extract CSS from #{page}: #{errors.strip.lines.last(5).join.strip}"
+      end
+
+      css = output.strip
+      raise Error, "critical found no critical CSS in #{page}" if css.empty?
+
+      css
+    end
+
+    def write(target, css)
+      path = File.join(root, "_includes", "critical-css", "#{target}.html")
+      FileUtils.mkdir_p(File.dirname(path))
+      # The include is rendered as Liquid; raw keeps a "{{" in CSS from being read as a tag.
+      File.write(path, "{% raw %}\n#{css}\n{% endraw %}\n")
+      path
+    end
+
+    def critical_command
+      return @critical if @critical
+
+      local = File.join(root, "node_modules", ".bin", Gem.win_platform? ? "critical.cmd" : "critical")
+      File.file?(local) ? [local] : ["npx", "--yes", PACKAGE]
+    end
+
+    def dimension_arguments
+      dimensions = Array(settings["dimensions"]).grep(Hash)
+      dimensions = DEFAULT_DIMENSIONS if dimensions.empty?
+      dimensions.flat_map { |entry| ["--dimensions", "#{entry['width']}x#{entry['height']}"] }
+    end
+
+    def penthouse_arguments
+      options = settings["penthouse_options"]
+      return [] unless options.is_a?(Hash)
+
+      options.flat_map { |key, value| ["--penthouse-#{key}", value.to_s] }
+    end
+
+    def page_file(site_dir, url)
+      path = url.to_s.sub(%r{\A/+}, "")
+      path = File.join(path, "index.html") if path.empty? || path.end_with?("/")
+      path if File.file?(File.join(site_dir, path))
+    end
+
+    def html_files(site_dir)
+      Dir.glob("**/*.html", base: site_dir).sort_by { |page| [page.count("/"), page] }
+    end
+  end
+end

data/lib/datalog/plugin_system/dependency_resolver.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "set"
-
 module Datalog
   module PluginSystem
     class DependencyResolver

data/lib/datalog/plugins/comments.rb

@@ -19,16 +19,23 @@ module Datalog
       REQUIRED_FIELDS = {
         "giscus" => %w[repo repo_id category category_id],
         "utterances" => %w[repo],
-        "disqus" => %w[shortname]
+        "disqus" => %w[shortname],
+        "api" => []
       }.freeze
 
+      # The api provider's thread (components/comments-thread.html) is a Liquid
+      # include, so it shares the service forms' labels and states.
+      API_INCLUDE = "{% include components/comments-thread.html %}"
+
       def initialize(site, config = {})
         super
         @defaults = {
           "provider" => "giscus",
           "mapping" => "pathname",
           "theme" => "light",
-          "enabled_by_default" => false
+          "enabled_by_default" => false,
+          "replies" => true,
+          "moderation" => true
         }.merge(@config)
         @memo = {}
       end
@@ -67,9 +74,12 @@ module Datalog
         settings = @memo[key]
         return "" unless settings
 
+        embed = settings["embed"]
+        embed = render_api(context) if settings["provider"] == "api" && embed.to_s.empty?
+
         <<~HTML
           <div class="datalog-comments" aria-label="Comments">
-            #{settings['embed']}
+            #{embed}
           </div>
         HTML
       end
@@ -109,6 +119,8 @@ module Datalog
           render_utterances(settings)
         when "disqus"
           render_disqus(document, settings)
+        when "api"
+          "" # the thread is rendered by the tag, in its own context
         else
           %(<p class="datalog-comments-unsupported">Comments provider "#{settings['provider']}" is not supported.</p>)
         end
@@ -140,6 +152,12 @@ module Datalog
           async></script>)
       end
 
+      # The thread of the site's own backend (#253), rendered in the tag's own
+      # context so the include sees the page and the site.
+      def render_api(context)
+        Liquid::Template.parse(API_INCLUDE).render(context)
+      end
+
       def render_disqus(document, settings)
         shortname = settings["shortname"] || ""
         nonce = nonce_attribute(document)
@@ -171,10 +189,22 @@ module Datalog
       end
 
       def missing_required_fields(provider, settings)
+        return api_missing(settings) if provider.to_s == "api"
+
         required = REQUIRED_FIELDS.fetch(provider.to_s, [])
         required.select { |key| settings[key].to_s.strip.empty? }
       end
 
+      # The api provider needs a backend: its own endpoint, or the site's
+      # dynamic services (docs/dynamic-services.md).
+      def api_missing(settings)
+        services = site.config["dynamic_services"]
+        base = services.is_a?(Hash) ? services["base_url"].to_s.strip : ""
+        return [] unless settings["endpoint"].to_s.strip.empty? && base.empty?
+
+        ["endpoint (or dynamic_services.base_url)"]
+      end
+
       def logger
         Jekyll.logger
       end

data/lib/datalog/theme/installed_files.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "jekyll"
+require "json"
+require_relative "package"
+require_relative "repository_checkout"
+
+module Datalog
+  module Theme
+    # Stops a build that would serve a mix of theme versions. A site that uses
+    # the theme from a Git submodule or another checkout reads every theme file
+    # from it, but the script bundles are build output and have to be built
+    # again whenever the checkout moves. Any site can also hold copies of files
+    # the theme provides, left from copying the theme in by hand; a site's file
+    # takes the place of the theme's, and the copies fall behind on the next
+    # update.
+    module InstalledFiles
+      module_function
+
+      BUNDLE_SOURCES = "assets/js/dist/sources.json"
+      # Theme data a site has no reason to replace: the script manifest names
+      # the bundles this version of the theme ships, and the integrity hashes
+      # belong to the CDN files its layouts load. Translations are left out,
+      # since a site may change them.
+      DATA_FILES = %w[_data/js_manifest.json _data/cdn-integrity.yml].freeze
+
+      # Jekyll prints an error on one line, so the messages are written as
+      # sentences rather than laid out in lines.
+      def check_bundles(site)
+        return unless RepositoryCheckout.applies_to?(site)
+
+        root = site.theme.root
+        reasons = stale_bundle_reasons(root)
+        return if reasons.empty?
+
+        listed = reasons.first(5).join("; ")
+        listed += "; and #{reasons.size - 5} more" if reasons.size > 5
+        raise Jekyll::Errors::FatalException,
+              "The script bundles in #{File.join(root, 'assets', 'js', 'dist')} were not built from the theme " \
+              "files beside them (#{listed}). Pages would run scripts from another version of the theme. Build " \
+              "them again by running `npm ci && npm run build:js` in #{root}."
+      end
+
+      # scripts/build_js.mjs records a SHA-256 of each file it builds from.
+      def stale_bundle_reasons(root)
+        record = File.join(root, BUNDLE_SOURCES)
+        unless File.file?(record)
+          return ["#{BUNDLE_SOURCES} is missing: the bundles were never built, or built before it was recorded"]
+        end
+
+        JSON.parse(File.read(record)).fetch("sources").filter_map do |path, digest|
+          file = File.join(root, path)
+          if !File.file?(file)
+            "#{path} is gone"
+          elsif Digest::SHA256.file(file).hexdigest != digest
+            "#{path} has changed"
+          end
+        end
+      end
+
+      def check_site_copies(site)
+        theme = site.theme
+        return unless theme && theme.name == "datalog-theme"
+
+        copies = stale_asset_copies(site, theme.root) + stale_data_copies(site, theme.root)
+        return if copies.empty?
+
+        raise Jekyll::Errors::FatalException,
+              "Your site has its own copies of files datalog-theme provides, and they differ from the theme's: " \
+              "#{copies.join(', ')}. A site's file takes the place of the theme's, so pages would load scripts, " \
+              "or check their integrity, for another version of the theme. Delete these files: the theme " \
+              "provides them."
+      end
+
+      # The site's static files that stand in for theme files pages load. Jekyll
+      # leaves the theme's file out when the site has one at the same path.
+      def stale_asset_copies(site, root)
+        source = File.join(site.source, "")
+        site.static_files.filter_map do |file|
+          next unless file.path.start_with?(source)
+
+          relative = file.relative_path.delete_prefix("/")
+          next unless Package::SCRIPTS_PAGES_LOAD.any? { |entry| Package.inside?(relative, entry) }
+
+          theme_file = File.join(root, relative)
+          relative if File.file?(theme_file) && !FileUtils.identical?(file.path, theme_file)
+        end
+      end
+
+      def stale_data_copies(site, root)
+        reader = Jekyll::DataReader.new(site)
+        own = reader.read(site.config["data_dir"])
+        DATA_FILES.filter_map do |entry|
+          key = File.basename(entry, ".*")
+          theme_file = File.join(root, entry)
+          next unless own.key?(key) && File.file?(theme_file)
+          next if own[key] == reader.read_data_file(theme_file)
+
+          Dir.glob("#{key}.*", base: site.in_source_dir(site.config["data_dir"])).map do |name|
+            File.join(site.config["data_dir"], name)
+          end.first
+        end
+      end
+    end
+  end
+end
+
+Jekyll::Hooks.register :site, :post_read do |site|
+  Datalog::Theme::InstalledFiles.check_bundles(site)
+  Datalog::Theme::InstalledFiles.check_site_copies(site)
+end

data/lib/datalog/theme/package.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Datalog
+  module Theme
+    # The repository is both the theme and the theme's demo site, and the demo
+    # keeps some of its files in directories a theme also uses. These lists say
+    # which of those files belong to the theme. The gemspec packages only those,
+    # and RepositoryCheckout applies the same split to sites that install the
+    # theme from a Git checkout or a local path, which see the whole repository.
+    module Package
+      # The _data files the layouts need in order to render. The rest of _data
+      # (navigation, social profiles, publications, the author profile) is the
+      # demo site's own; a site using the theme supplies its own versions.
+      DATA_FILES = %w[
+        _data/i18n
+        _data/js_manifest.json
+        _data/cdn-integrity.yml
+      ].freeze
+
+      # Downloads the demo site links to from assets/: the maintainer's CV
+      # templates and publication exports.
+      DEMO_ASSETS = %w[
+        assets/publications
+        assets/templates
+      ].freeze
+
+      # Pages load the bundles in assets/js/dist, which scripts/build_js.mjs
+      # builds from the sources beside them, and the loader that picks among
+      # the bundles. No page loads the sources themselves, and a site copies
+      # every theme asset into its output, so the gem leaves them out.
+      SCRIPTS_PAGES_LOAD = %w[
+        assets/js/dist
+        assets/js/loader.js
+      ].freeze
+
+      module_function
+
+      # Whether a repository-relative path is part of the theme rather than
+      # demo content that happens to live in a theme directory.
+      def theme_file?(path)
+        return DATA_FILES.any? { |entry| inside?(path, entry) } if inside?(path, "_data")
+        return SCRIPTS_PAGES_LOAD.any? { |entry| inside?(path, entry) } if inside?(path, "assets/js")
+
+        DEMO_ASSETS.none? { |entry| inside?(path, entry) }
+      end
+
+      # The site.data keys the theme's own data files are read into.
+      def data_keys
+        DATA_FILES.map { |entry| File.basename(entry, ".*") }
+      end
+
+      def inside?(path, entry)
+        path == entry || path.start_with?("#{entry}/")
+      end
+    end
+  end
+end