datalog-theme 0.8.0 → 0.9.0

data/_plugins/authors.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Datalog
+  # One list of a page's authors, and one of its contributors, which the
+  # byline, the author cards, the JSON-LD, the citation meta tags and the
+  # citation exports all read. Each used to work the author out on its own: a
+  # post named one author, `author: john_doe` put "john_doe" in the byline while
+  # the card looked the key up in _data/authors.yml, the research layout gave
+  # every author the site author's ORCID and affiliation, and the JSON-LD listed
+  # the site author's profiles only when an ORCID was set.
+  #
+  # An entry is a name, a key of _data/authors.yml, or a map with `name` (or
+  # `id`, a key of _data/authors.yml). The data record and, for the site's own
+  # author, `author` in _config.yml fill in what the entry leaves out.
+  module Authors
+    module_function
+
+    PROFILE_URLS = {
+      "github" => "https://github.com/%s",
+      "twitter" => "https://twitter.com/%s",
+      "linkedin" => "https://linkedin.com/in/%s"
+    }.freeze
+    PROFILE_LINKS = %w[researchgate google_scholar].freeze
+    ORCID_ID = /\A\d{4}-\d{4}-\d{4}-\d{3}[\dX]\z/
+
+    # `authors:`, else `author:`, else the site's author.
+    def authors(page, site)
+      entries = entries(value(page, "authors"))
+      entries = entries(value(page, "author")) if entries.empty?
+      records = entries.filter_map { |entry| resolve(entry, site) }
+      records = [site_author(site)].compact if records.empty?
+      apply_page_affiliation(records, page)
+    end
+
+    def contributors(page, site)
+      entries(value(page, "contributors")).filter_map { |entry| resolve(entry, site) }
+    end
+
+    # A list, one entry, or names in a string separated by semicolons.
+    def entries(value)
+      list = if value.is_a?(String) then value.split(";")
+             elsif value.is_a?(Hash) then [value]
+             else Array(value)
+             end
+      list.reject { |entry| entry.nil? || (entry.is_a?(String) && entry.strip.empty?) }
+    end
+
+    # A plain entry is a key or a name; a map's own fields win over the record's.
+    def resolve(entry, site)
+      own = entry.is_a?(Hash) ? present(entry) : {}
+      key = own["id"] || own["name"] || entry.to_s.strip
+      record = known(key, site).merge(own)
+      record["name"] ||= key
+      return if record["name"].to_s.strip.empty?
+
+      finish(record, site)
+    end
+
+    # The _data/authors.yml record for a key, or the site author's profile
+    # when the key is the site author's name.
+    def known(key, site)
+      data = value(value(site, "data"), "authors")
+      record = value(data, key.to_s)
+      return present(record) if record.is_a?(Hash)
+
+      author = site_author_profile(site)
+      author && author["name"] == key ? author : {}
+    end
+
+    def site_author(site)
+      profile = site_author_profile(site)
+      profile && finish(profile, site)
+    end
+
+    def site_author_profile(site)
+      author = value(site, "author")
+      return { "name" => author.strip } if author.is_a?(String) && !author.strip.empty?
+
+      present(author) if author.is_a?(Hash) && author["name"]
+    end
+
+    def finish(record, site)
+      record["affiliation"] ||= record["institution"]
+      record["bio"] ||= record["biography"]
+      record["image"] ||= record["avatar"] || record["photo"]
+      record["orcid"] = "https://orcid.org/#{record['orcid']}" if record["orcid"].to_s.match?(ORCID_ID)
+      record["site_author"] = record["name"] == site_author_profile(site)&.fetch("name")
+      record["same_as"] = profiles(record)
+      record
+    end
+
+    def profiles(record)
+      urls = [record["orcid"]]
+      urls += PROFILE_URLS.map { |key, template| format(template, record[key]) if record[key] }
+      urls += PROFILE_LINKS.map { |key| record[key] }
+      urls.compact.map(&:to_s).reject(&:empty?).uniq
+    end
+
+    # `author_affiliation` in front matter names the affiliation of a page's
+    # only author; an empty one removes it.
+    def apply_page_affiliation(records, page)
+      affiliation = value(page, "author_affiliation")
+      return records if affiliation.nil? || records.size != 1
+
+      affiliation.to_s.strip.empty? ? records.first.delete("affiliation") : records.first["affiliation"] = affiliation
+      records
+    end
+
+    # String keys, without the blank values an entry leaves for its record to fill.
+    def present(hash)
+      hash.to_h.each_with_object({}) do |(key, entry), result|
+        result[key.to_s] = entry unless entry.nil? || (entry.is_a?(String) && entry.strip.empty?)
+      end
+    end
+
+    # Pages are hashes in Liquid, documents and the site are drops; both answer [].
+    def value(object, key)
+      object[key] if object.respond_to?(:[]) && !object.is_a?(String) && !object.is_a?(Array)
+    end
+  end
+
+  module AuthorFilters
+    def page_authors(page)
+      Authors.authors(page, @context["site"])
+    end
+
+    def page_contributors(page)
+      Authors.contributors(page, @context["site"])
+    end
+  end
+end
+
+Liquid::Template.register_filter(Datalog::AuthorFilters)

data/_plugins/config_validator.rb

@@ -3,11 +3,66 @@
 require "uri"
 
 module Datalog
+  # The dynamic-services settings are inlined into every page for the
+  # browser (docs/dynamic-services.md), so a key that names a secret is a
+  # leak whatever its value; the validator reports each one.
+  module PublicConfiguration
+    module_function
+
+    # `credentials` is fetch's cookie mode, not a secret, so "credential" is not in the list.
+    SECRET_KEY = /secret|token|password|passwd|api_key|apikey|private_key/i
+
+    # The blocks of _config.yml that reach the browser as they are. `moderation`
+    # is where an admin password is most tempting and least use: a static page
+    # cannot keep one (docs/moderation.md).
+    PUBLIC_BLOCKS = %w[dynamic_services moderation].freeze
+
+    def errors(config)
+      PUBLIC_BLOCKS.flat_map do |block|
+        settings = config[block]
+        next [] unless settings.is_a?(Hash)
+
+        secret_keys(settings, [block]).map { |path| secret_error(block, path) }
+      end
+    end
+
+    def secret_error(block, path)
+      {
+        headline: "Secret in public configuration '#{path.join('.')}'",
+        path: path,
+        expected: "no credential: #{block} is sent to every reader's browser, so a key, token or " \
+                  "password belongs on the server, never in _config.yml",
+        actual: "a key named '#{path.last}'"
+      }
+    end
+
+    def secret_keys(hash, path)
+      hash.flat_map do |key, value|
+        here = path + [key.to_s]
+        found = key.to_s.match?(SECRET_KEY) ? [here] : []
+        value.is_a?(Hash) ? found + secret_keys(value, here) : found
+      end
+    end
+  end
+
   class ConfigValidator < Jekyll::Generator
     safe true
     priority :highest
 
-    DOCUMENTATION_BASE_URL = "https://datalog-theme.github.io/docs/configuration-reference"
+    # docs/ is not part of the built site, so errors link to the file on GitHub.
+    DOCUMENTATION_URL = "https://github.com/DiogoRibeiro7/analytics-blog-jekyll/blob/main/docs/configuration-reference.md"
+
+    # A licence: an identifier such as CC-BY-4.0 or MIT, or a map naming one.
+    LICENSE = {
+      type: %i[string hash],
+      schema: {
+        id: { type: :string },
+        name: { type: :string },
+        url: { type: :string },
+        holder: { type: %i[string array] },
+        year: { type: %i[integer string] }
+      }
+    }.freeze
 
     SCHEMA = {
       title: { type: :string, required: true },
@@ -21,6 +76,68 @@ module Datalog
           email: { type: :string, format: :email }
         }
       },
+      # Who publishes the site in structured data and citations. Without it, the author does.
+      publisher: {
+        type: :hash,
+        schema: {
+          type: { type: :string, enum: %w[Person Organization] },
+          name: { type: :string },
+          url: { type: :string },
+          logo: { type: :string }
+        }
+      },
+      # The licence of the site's articles (text and figures) and of their code samples.
+      content_license: LICENSE,
+      code_license: LICENSE,
+      # Which pages get scholarly discovery metadata: true for every post, or a list of collections and layouts.
+      scholarly: { type: %i[boolean array string] },
+      dynamic_services: {
+        type: :hash,
+        schema: {
+          base_url: { type: :string, format: :url }, api_version: { type: %i[string integer] },
+          timeout_ms: { type: :integer }, credentials: { type: :string, enum: %w[omit same-origin include] },
+          features: { type: :hash }, paths: { type: :hash }, csrf_header: { type: :string }, csrf_cookie: { type: :string }
+        }
+      },
+      # The correction-report form on posts (components/correction-report.html).
+      corrections: {
+        type: :hash,
+        schema: { enabled: { type: :boolean }, categories: { type: :array } }
+      },
+      # The contact and collaboration form (components/contact-form.html).
+      contact: {
+        type: :hash,
+        schema: {
+          enabled: { type: :boolean }, categories: { type: :array }, prompts: { type: :hash },
+          privacy_notice: { type: :string }, retention: { type: :string }
+        }
+      },
+      # "Was this useful?" after a post (components/reactions.html).
+      reactions: {
+        type: :hash,
+        schema: { enabled: { type: :boolean }, counts: { type: :boolean }, types: { type: :array } }
+      },
+      # Webmentions: the receiver advertised in the head, the mentions shown under a post.
+      webmentions: {
+        type: :hash,
+        schema: { enabled: { type: :boolean }, endpoint: { type: :string }, types: { type: :array } }
+      },
+      # The moderation inbox (docs/moderation.md): public settings only, never a credential.
+      moderation: {
+        type: :hash,
+        schema: {
+          enabled: { type: :boolean }, endpoint: { type: :string }, sign_in_url: { type: :string },
+          credentials: { type: :string, enum: %w[omit same-origin include] }
+        }
+      },
+      # The newsletter form and the page its emails link to (components/subscribe-form.html).
+      subscriptions: {
+        type: :hash,
+        schema: {
+          enabled: { type: :boolean }, double_opt_in: { type: :boolean }, placement: { type: :array },
+          topics: { type: :array }, privacy_url: { type: :string }
+        }
+      },
       markdown: { type: :string, enum: %w[kramdown commonmark] },
       highlighter: { type: :string, enum: %w[rouge pygments] },
       permalink: { type: :string },
@@ -69,6 +186,25 @@ module Datalog
               engine: { type: :string, enum: %w[mathjax katex] },
               enabled: { type: :boolean }
             }
+          },
+          # The "Reading mode" control on posts, and whether a reader's choice is kept.
+          reading_mode: {
+            type: :hash,
+            schema: {
+              enabled: { type: :boolean },
+              remember: { type: :boolean }
+            }
+          },
+          # Bookmarks, reading progress and private highlights, kept in the reader's browser.
+          reading_state: {
+            type: :hash,
+            schema: {
+              enabled: { type: :boolean },
+              bookmarks: { type: :boolean },
+              progress: { type: :boolean },
+              highlights: { type: :boolean },
+              list_url: { type: :string }
+            }
           }
         }
       }
@@ -83,6 +219,11 @@ module Datalog
       "theme_options.syntax_highlighting" => {
         message: "Code is highlighted by Rouge when the site builds and the theme no longer loads Prism, " \
                  "so these settings have no effect. Remove them."
+      },
+      # The user guide's troubleshooting table sent readers here.
+      "theme_options.math.enabled" => {
+        message: "Nothing reads it: theme_options.math.render_on_load decides which pages load the math engine, " \
+                 "and a page's `math` front matter overrides that. Remove it."
       }
     }.freeze
 
@@ -93,6 +234,32 @@ module Datalog
       }
     }.freeze
 
+    # Pointing layouts_dir and the rest into a copy of the theme is how a site
+    # used a Git submodule before the theme loaded its own plugins. Jekyll
+    # cannot read the theme's assets or _data that way, so those were copied
+    # into the site, and the copies fall behind the theme on every update.
+    module ThemeDirectories
+      module_function
+
+      URL = "https://github.com/DiogoRibeiro7/analytics-blog-jekyll/blob/main/docs/install.md#keep-the-theme-in-a-git-submodule"
+      KEYS = [%w[layouts_dir], %w[includes_dir], %w[plugins_dir], %w[sass sass_dir]].freeze
+
+      def warnings(config)
+        source = File.expand_path(config["source"] || Dir.pwd)
+        keys = KEYS.select { |path| Array(config.dig(*path)).any? { |dir| theme_checkout?(dir, source) } }
+        return [] if keys.empty?
+
+        ["#{keys.map { |path| path.join('.') }.join(', ')} point into a copy of datalog-theme. Jekyll cannot " \
+         "read the theme's assets and _data that way, so a site copies them in, and the copies fall behind " \
+         "the theme. Use the copy as the theme instead: #{URL}"]
+      end
+
+      def theme_checkout?(dir, source)
+        checkout = File.dirname(File.expand_path(dir.to_s, source))
+        checkout != source && File.file?(File.join(checkout, "datalog-theme.gemspec"))
+      end
+    end
+
     class Validator
       attr_reader :errors, :warnings
 
@@ -108,6 +275,7 @@ module Datalog
 
         apply_deprecated_migrations
         validate_schema(@config, SCHEMA)
+        check_math_defaults
 
         self
       end
@@ -143,6 +311,36 @@ module Datalog
         end
       end
 
+      # With render_on_load: auto, only the pages with math load the math
+      # engine. `math: true` or `mathjax: true` in front matter defaults loads it
+      # on every page in their scope instead, and nothing in the build said so.
+      def check_math_defaults
+        return unless dig_value(@config, %w[theme_options math render_on_load]) == "auto"
+
+        Array(@config["defaults"]).each do |entry|
+          values = entry["values"] if entry.is_a?(Hash)
+          next unless values.is_a?(Hash)
+
+          %w[math mathjax].each do |key|
+            next unless values[key] == true
+
+            @warnings << "Front matter defaults set '#{key}: true' for #{describe_scope(entry['scope'])}, so they all " \
+                         "load the math engine, whatever theme_options.math.render_on_load: auto finds. " \
+                         "Remove it, and set 'math: true' on the pages that need the engine."
+          end
+        end
+      end
+
+      def describe_scope(scope)
+        scope = {} unless scope.is_a?(Hash)
+        type = scope["type"].to_s
+        path = scope["path"].to_s
+        return "every page" if type.empty? && path.empty?
+
+        pages = type.empty? ? "the pages" : "the pages of type '#{type}'"
+        path.empty? ? pages : "#{pages} under '#{path}'"
+      end
+
       def validate_schema(data, schema, path = [])
         schema.each do |key, rules|
           key_path = path + [key.to_s]
@@ -167,6 +365,10 @@ module Datalog
       end
 
       def validate_type(path, value, rules)
+        # YAML never yields a Symbol, but converters rewrite the site's own
+        # configuration: jekyll-sass-converter turns sass.style into one.
+        value = value.to_s if value.is_a?(Symbol)
+
         expected_type = rules[:type]
         if expected_type && !type_valid?(value, expected_type)
           errors << build_type_error(path, expected_type, value)
@@ -244,8 +446,7 @@ module Datalog
           headline: "Missing required configuration '#{identifier}'",
           path: path,
           expected: "Value required",
-          actual: "nil",
-          doc_url: documentation_url(path)
+          actual: "nil"
         }
       end
 
@@ -255,8 +456,7 @@ module Datalog
           headline: "Invalid type for '#{identifier}'",
           path: path,
           expected: human_type(expected_type),
-          actual: value.inspect,
-          doc_url: documentation_url(path)
+          actual: value.inspect
         }
       end
 
@@ -268,8 +468,7 @@ module Datalog
           path: path,
           expected: enum_values.map { |v| "\"#{v}\"" }.join(" or "),
           actual: value.inspect,
-          suggestion: suggestion,
-          doc_url: documentation_url(path)
+          suggestion: suggestion
         }
       end
 
@@ -279,8 +478,7 @@ module Datalog
           headline: "Invalid value for '#{identifier}'",
           path: path,
           expected: expectation,
-          actual: value.inspect,
-          doc_url: documentation_url(path)
+          actual: value.inspect
         }
       end
 
@@ -303,16 +501,11 @@ module Datalog
         lines << "  Received: #{error[:actual]}" if error[:actual]
         lines << ""
         lines << "  #{error[:suggestion]}" if error[:suggestion]
-        lines << "  Documentation: #{error[:doc_url]}"
+        lines << "  Documentation: #{DOCUMENTATION_URL}"
         lines.compact!
         lines.join("\n")
       end
 
-      def documentation_url(path)
-        anchor = path.map { |segment| segment.gsub(/[^a-z0-9]+/i, "-") }.join("-").downcase
-        "#{DOCUMENTATION_BASE_URL}##{anchor}"
-      end
-
       def human_type(type)
         return type.map { |entry| human_type(entry) }.join(" or ") if type.is_a?(Array)
 
@@ -344,7 +537,8 @@ module Datalog
         head, *tail = path
         return nil if head.nil?
 
-        value = data[head] || data[head.to_sym]
+        # `data[head] || data[head.to_sym]` turned a `false` into nil.
+        value = data.key?(head) ? data[head] : data[head.to_sym]
         return value if tail.empty?
 
         dig_value(value, tail)
@@ -380,17 +574,26 @@ module Datalog
       end
     end
 
+    # `jekyll serve` processes the same site again on every change, without
+    # reading _config.yml again, and by then converters have rewritten parts of
+    # the configuration: jekyll-sass-converter turns sass.style into a Symbol.
+    # Checking on every build stopped each rebuild, so a site is checked on its
+    # first build. A `:site, :after_init` hook would also run once, but Jekyll's
+    # command line reports an error raised there as a backtrace, not a message.
     def generate(site)
+      return if @validated
+
       validator = Validator.new(site.config)
       validator.run
+      # The Validator class is at its length limit; the public-configuration check lives beside it.
+      validator.errors.concat(PublicConfiguration.errors(site.config))
 
-      validator.warnings.each do |warning|
+      (validator.warnings + ThemeDirectories.warnings(site.config)).each do |warning|
         logger.warn("config", warning)
       end
 
-      return if validator.errors.empty?
-
-      raise Jekyll::Errors::FatalException, validator.formatted_errors
+      @validated = validator.errors.empty?
+      raise Jekyll::Errors::FatalException, validator.formatted_errors unless @validated
     end
 
     private

data/_plugins/critical_css_check.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Datalog
+  # The theme ships _includes/critical-css/*.html empty, since critical CSS
+  # depends on a site's own pages. A production build with critical_css.enabled
+  # and no critical CSS written inlined nothing and kept main.css blocking
+  # rendering, and nothing said so.
+  module CriticalCssCheck
+    module_function
+
+    TARGETS = %w[home post default].freeze
+
+    def warning(site)
+      return unless Jekyll.env == "production"
+
+      settings = site.config["critical_css"]
+      return unless settings.is_a?(Hash) && settings["enabled"] == true
+
+      empty = TARGETS.select { |target| fragment(site, target).strip.empty? }
+      return if empty.empty?
+
+      files = empty.map { |target| "_includes/critical-css/#{target}.html" }.join(", ")
+      "critical_css.enabled is true, but #{files} #{empty.size == 1 ? 'is' : 'are'} empty, so pages with " \
+        "#{empty.size == 1 ? 'that layout' : 'those layouts'} inline no critical CSS and main.css blocks rendering. " \
+        "Run `bundle exec datalog critical-css` before building."
+    end
+
+    # The site's file, or the theme's when the site has none.
+    def fragment(site, target)
+      name = File.join("critical-css", "#{target}.html")
+      directories = [site.in_source_dir(site.config["includes_dir"].to_s)]
+      directories << site.theme.includes_path if site.theme&.includes_path
+      path = directories.map { |directory| File.join(directory, name) }.find { |candidate| File.file?(candidate) }
+      path ? File.read(path) : ""
+    end
+  end
+end
+
+Jekyll::Hooks.register :site, :post_read do |site|
+  warning = Datalog::CriticalCssCheck.warning(site)
+  Jekyll.logger.warn("Critical CSS:", warning) if warning
+end

data/_plugins/i18n.rb

@@ -5,11 +5,13 @@ module Datalog
     module_function
 
     def locale(context)
-      page_lang = context["page"] && context["page"]["lang"]
-      site = context.registers[:site]
+      locale_code(context.registers[:site], context["page"] && context["page"]["lang"])
+    end
+
+    # A page's language, or the site's, as a code such as "pt".
+    def locale_code(site, page_lang)
       site_locale = site.config.dig("theme_options", "localization", "default_locale") || site.config["locale"] || "en"
-      lang = page_lang || site_locale
-      lang.to_s.split(/[-_]/).first
+      (page_lang || site_locale).to_s.split(/[-_]/).first
     end
 
     def data_for(site)