jekyll-theme-rop 2.1.16 → 2.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5ca589928f59066599cc23eaab6d2a531421e298580919882442e1c06bc6514
-  data.tar.gz: db394788b665713c6f3b6a4c8029c580fd48b15c2334b1f7c48fa3afad7f8fb8
+  metadata.gz: 1f3b4046ce7aac2a41e6143ce8fcc59d7c5ac8fe1e04a5b2a530f848ec8ea511
+  data.tar.gz: 0e7bf2129e42f44eb9afa6059c9c9f04d48ed7c2bb55bf04009420a08ce10423
 SHA512:
-  metadata.gz: 8d82cac252411ac27824fbe3665b1d4c665f988fdd7dd649f3ac1fdc0c556fbcc6e8669fb66bfe12375beb52eccfabdd2bb0482a88dbf90cde87e0b9be3d16f4
-  data.tar.gz: d84773145c94411c49b292359d0b9cc48983c0b6e3cb30697a6cdfd8347adcbd7d717e5fe3b1e1eb21e4bcc17b7d751d697f21a9040c2d9b0991bb73f2d6f31b
+  metadata.gz: de88ee1833cc4d4438234b4e8f3cf28ece3a5449aeb14385be648d15d44346b94bea1dad7bc8f3529378f1f897450e5d9844f1949704144d61ff5e20f6f235e0
+  data.tar.gz: 071e47f509c25185e7ec639fadcbb838cc8ea80ac3991b138f3700fffff55c136e282ac1219fa6dde800976590bdc970e05748e98dcc4a0613921b0421faf921

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+# require "rspec/core/rake_task"
+
+# Uncomment to enable the "spec" task
+# RSpec::Core::RakeTask.new(:spec)
+#
+# task :default => :spec

data/lib/jekyll-theme-open-project.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Compatibility file for old name
+require_relative 'jekyll-theme-rop'

data/lib/jekyll-theme-rop.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+puts '[jekyll-theme-rop] Loaded.'
+
+require 'jekyll'
+require_relative 'rop'
+
+Jekyll::Hooks.register :site, :after_init do |site|
+  site.reader = Rop::ProjectReader.new(site) if site.theme # TODO: Check theme name
+end
+
+# This is a fix for static files
+require 'fileutils'
+Jekyll::Hooks.register :pages, :post_write do |page|
+  if (page.path == 'robots.txt') || (page.path == 'sitemap.xml')
+    File.write(page.site.in_dest_dir(page.path), page.content,
+               mode: 'wb')
+  end
+end

data/lib/rop/_plugins

@@ -0,0 +1 @@
+_plugins/

data/lib/rop/blog_index.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'digest/md5'
+
+module Rop
+  #
+  # Adds a variable holding the array of posts of open hub blog
+  # and from each individual project blog, combined and sorted by date.
+  #
+  # It also does some processing on the posts
+  # as required by the Open Project theme.
+  #
+  class CombinedPostArrayGenerator < ::Jekyll::Generator
+    safe true
+
+    def generate(site)
+      site_posts = site.posts.docs
+
+      if site.config['is_hub']
+        # Get documents representing projects
+        projects = site.collections['projects'].docs.select do |item|
+          pieces = item.url.split('/')
+          pieces.length == 4 && pieces[-1] == 'index' && pieces[1] == 'projects'
+        end
+        # Add project name (matches directory name, may differ from title)
+        projects = projects.map do |project|
+          project.data['name'] = project.url.split('/')[2]
+          project
+        end
+
+        # Get documents representnig posts from each project’s blog
+        project_posts = site.collections['projects'].docs.select { |item| item.url.include? '_posts' }
+
+        # Add parent project’s data hash onto each
+        project_posts = project_posts.map do |post|
+          project_name = post.url.split('/')[2]
+          post.data['parent_project'] = projects.detect { |p| p.data['name'] == project_name }
+          post.content = ''
+          post
+        end
+
+        posts_combined = (project_posts + site_posts)
+
+      else
+        posts_combined = site_posts
+
+      end
+
+      # On each post, replace authors’ emails with corresponding md5 hashes
+      # suitable for hotlinking authors’ Gravatar profile pictures.
+      posts_combined = posts_combined.sort_by(&:date).reverse.map do |post|
+        process_author(post.data['author']) if post.data.key? 'author'
+
+        if post.data.key? 'authors'
+          post.data['authors'].map do |author|
+            process_author(author)
+          end
+        end
+
+        post
+      end
+
+      # Make combined blog post array available site-wide
+      site.config['posts_combined'] = posts_combined
+      site.config['num_posts_combined'] = posts_combined.size
+    end
+
+    private
+
+    def process_author(author)
+      email = author['email']
+      hash = Digest::MD5.hexdigest(email)
+      author['email'] = hash
+      author['plaintext_email'] = email
+      author
+    end
+  end
+end

data/lib/rop/filterable_index.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Rop
+  # On an open hub site, Jekyll Open Project theme assumes the existence of two types
+  # of item indexes: software and specs, where items are gathered
+  # from across open projects in the hub.
+  #
+  # The need for :item_test arises from our data structure (see Jekyll Open Project theme docs)
+  # and the fact that Jekyll doesn’t intuitively handle nested collections.
+  INDEXES = {
+    'software' => {
+      item_test: ->(item) { item.path.include? '/_software' and !item.path.include? '/docs' }
+    },
+    'specs' => {
+      item_test: ->(item) { item.path.include? '/_specs' and !item.path.include? '/docs' }
+    }
+  }.freeze
+
+  # Below passes the `items` variable to normal (unfiltered)
+  # index page layout.
+
+  class IndexPageGenerator < ::Jekyll::Generator
+    safe true
+
+    def generate(site)
+      site.config['max_featured_software'] = 3
+      site.config['max_featured_specs'] = 3
+      site.config['max_featured_posts'] = 3
+
+      INDEXES.each do |index_name, params|
+        collection_name = if site.config['is_hub']
+                            'projects'
+                          else
+                            index_name
+                          end
+
+        next unless site.collections.key? collection_name
+
+        # Filters items from given collection_name through item_test function
+        # and makes items available in templates via e.g. site.all_specs, site.all_software
+
+        items = get_all_items(site, collection_name, params[:item_test])
+
+        site.config["one_#{index_name}"] = items[0] if items.length == 1
+
+        site.config["all_#{index_name}"] = items
+        site.config["num_all_#{index_name}"] = items.size
+
+        featured_items = items.reject { |item| item.data['feature_with_priority'].nil? }
+        site.config["featured_#{index_name}"] = featured_items.sort_by { |item| item.data['feature_with_priority'] }
+        site.config["num_featured_#{index_name}"] = featured_items.size
+
+        non_featured_items = items.select { |item| item.data['feature_with_priority'].nil? }
+        site.config["non_featured_#{index_name}"] = non_featured_items
+        site.config["num_non_featured_#{index_name}"] = non_featured_items.size
+      end
+    end
+
+    def get_all_items(site, collection_name, filter_func)
+      # Fetches items of specified type, ordered and prepared for usage in index templates
+
+      collection = site.collections[collection_name]
+
+      raise "Collection does not exist: #{collection_name}" if collection.nil?
+
+      items = collection.docs.select do |item|
+        filter_func.call(item)
+      end
+
+      default_time = Time.new(1989, 12, 31, 0, 0, 0, '+00:00')
+
+      items.sort! do |i1, i2|
+        val1 = i1.data.fetch('last_update', default_time) || default_time
+        val2 = i2.data.fetch('last_update', default_time) || default_time
+        (val2 <=> val1) || 0
+      end
+
+      if site.config['is_hub']
+        items.map! do |item|
+          project_name = item.url.split('/')[2]
+          project_path = "_projects/#{project_name}/index.md"
+
+          item.data['project_name'] = project_name
+          item.data['project_data'] = site.collections['projects'].docs.select do |proj|
+            proj.path.end_with? project_path
+          end [0]
+
+          item
+        end
+      end
+
+      items
+    end
+  end
+  # Each software or spec item can have its tags,
+  # and the theme allows to filter each index by a tag.
+  # The below generates an additional index page
+  # for each tag in an index, like software/Ruby.
+  #
+  # Note: this expects "_pages/<index page>.html" to be present in site source,
+  # so it would fail if theme setup instructions were not followed fully.
+
+  class FilteredIndexPage < ::Jekyll::Page
+    def initialize(site, base, dir, tag, items, index_page)
+      @site = site
+      @base = base
+      @dir = dir
+      @name = 'index.html'
+
+      process(@name)
+      read_yaml(File.join(base, '_pages'), "#{index_page}.html")
+      data['tag'] = tag
+      data['items'] = items
+    end
+  end
+
+  class FilteredIndexPageGenerator < IndexPageGenerator
+    safe true
+
+    def generate(site)
+      INDEXES.each do |index_name, params|
+        collection_name = if site.config['is_hub']
+                            'projects'
+                          else
+                            index_name
+                          end
+
+        items = get_all_items(site, collection_name, params[:item_test])
+
+        # Creates a data structure like { tag1: [item1, item2], tag2: [item2, item3] }
+        tags = {}
+        items.each do |item|
+          (item.data['tags'] or []).each do |tag|
+            tags[tag] = [] unless tags.key? tag
+            tags[tag].push(item)
+          end
+        end
+
+        # Creates a filtered index page for each tag
+        tags.each do |tag, tagged_items|
+          site.pages << FilteredIndexPage.new(
+            site,
+            site.source,
+            # The filtered page will be nested under /<index page>/<tag>.html
+            File.join(index_name, tag),
+            tag,
+            tagged_items,
+            index_name
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rop/png_diagram.html

@@ -0,0 +1,31 @@
+{% comment %}Page stub.{% endcomment %}
+
+<div id="diagramContainer" style="height: 400px"></div>
+
+<style>
+  .leaflet-container {
+    background-color: transparent;
+  }
+  .documentation.with-expandable-toc > article {
+    max-width: none;
+  }
+</style>
+
+<script>
+  (function () {
+    var map = L.map('diagramContainer', {
+      crs: L.CRS.Simple,
+      attributionControl: false,
+      scrollWheelZoom: false,
+      zoomControl: false,
+      minZoom: -10,
+    }).
+    setView([{{ page.image_height }}/2, {{ page.image_width }}/2]);
+
+    map.addControl(L.control.zoom({ position: 'bottomleft' }));
+
+    var bounds = [[0,0], [{{ page.image_height }}, {{ page.image_width }}]];
+    var image = L.imageOverlay('{{ page.image_path }}', bounds).addTo(map);
+    map.fitBounds(bounds);
+  }());
+</script>

data/lib/rop/png_diagram_page.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Rop
+  class PngDiagramPage < ::Jekyll::Page
+    EXTRA_STYLESHEETS = [{
+      'href' => 'https://unpkg.com/leaflet@1.3.4/dist/leaflet.css',
+      'integrity' => 'sha512-puBpdR0798OZvTTbP4A8Ix/l+A4dHDD0DGqYW6RQ+9jxkRFclaxxQb/SJAWZfWAkuyeQUytO7+7N4QKrDh+drA==',
+      'crossorigin' => ''
+    }].freeze
+
+    EXTRA_SCRIPTS = [{
+      'src' => 'https://unpkg.com/leaflet@1.3.4/dist/leaflet.js',
+      'integrity' => 'sha512-nMMmRyTVoLYqjP9hrbed9S+FzjZHW5gY1TWCHA5ckwXZBadntCNs8kEqAWdrb9O7rxbCaA4lKTIWjDXZxflOcA==',
+      'crossorigin' => ''
+    }].freeze
+
+    def initialize(site, base, dir, data)
+      @site = site
+      @base = base
+      @dir = dir
+      @name = 'index.html'
+
+      process(@name)
+      self.data ||= data
+
+      self.data['extra_stylesheets'] = EXTRA_STYLESHEETS
+      self.data['extra_scripts'] = EXTRA_SCRIPTS
+      self.data['layout'] = 'spec'
+    end
+  end
+end

data/lib/rop/project_reader.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'git'
+require 'jekyll-data/reader'
+
+module Rop
+  DEFAULT_DOCS_SUBTREE = 'docs'
+  DEFAULT_REPO_REMOTE_NAME = 'origin'
+  DEFAULT_REPO_BRANCH = 'main'
+  # Can be overridden by default_repo_branch in site config.
+  # Used by shallow_git_checkout.
+
+  class NonLiquidDocument < ::Jekyll::Document
+    def render_with_liquid?
+      false
+    end
+  end
+
+  class CollectionDocReader < ::Jekyll::DataReader
+    def read(dir, collection)
+      read_project_subdir(dir, collection)
+    end
+
+    def read_project_subdir(dir, collection, nested: false)
+      return unless File.directory?(dir) && !@entry_filter.symlink?(dir)
+
+      entries = Dir.chdir(dir) do
+        Dir['*.{adoc,md,markdown,html,svg,png}'] + Dir['*'].select { |fn| File.directory?(fn) }
+      end
+
+      entries.each do |entry|
+        path = File.join(dir, entry)
+
+        Jekyll.logger.debug('OPF:', "Reading entry #{path}")
+
+        if File.directory?(path)
+          read_project_subdir(path, collection, nested: true)
+
+        elsif nested || (File.basename(entry, '.*') != 'index')
+          ext = File.extname(path)
+          if ['.adoc', '.md', '.markdown'].include? ext
+            doc = NonLiquidDocument.new(path, site: @site, collection: collection)
+            doc.read
+
+            # Add document to Jekyll document database if it refers to software or spec
+            # (as opposed to be some random nested document within repository source, like a README)
+            doc_url_parts = doc.url.split('/')
+            Jekyll.logger.debug('OPF:',
+                                "Reading document in collection #{collection.label} with URL #{doc.url} (#{doc_url_parts.size} parts)")
+            if (collection.label != 'projects') || (doc_url_parts.size == 5)
+              Jekyll.logger.debug('OPF:', "Adding document with URL: #{doc.url}")
+              collection.docs << doc
+            else
+              Jekyll.logger.debug('OPF:',
+                                  "Did NOT add document with URL (possibly nesting level doesn’t match): #{doc.url}")
+            end
+          else
+            Jekyll.logger.debug('OPF:', "Adding static file: #{path}")
+            collection.files << ::Jekyll::StaticFile.new(
+              @site,
+              @site.source,
+              Pathname.new(File.dirname(path)).relative_path_from(Pathname.new(@site.source)).to_s,
+              File.basename(path),
+              collection
+            )
+          end
+        end
+      end
+    end
+  end
+
+  #
+  # Below deals with fetching each open project’s data from its site’s repo
+  # (such as posts, template includes, software and specs)
+  # and reading it into 'projects' collection docs.
+  #
+
+  class ProjectReader < ::JekyllData::Reader
+    # TODO: Switch to @site.config?
+    @@siteconfig = Jekyll.configuration({})
+
+    def read
+      super
+      if @site.config['is_hub']
+        fetch_and_read_projects
+      else
+        fetch_and_read_software('software')
+        fetch_and_read_specs('specs', build_pages: true)
+        fetch_hub_logo
+      end
+    end
+
+    private
+
+    def fetch_hub_logo
+      return unless @site.config.key?('parent_hub') && @site.config['parent_hub'].key?('git_repo_url')
+
+      git_shallow_checkout(
+        File.join(@site.source, 'parent-hub'),
+        @site.config['parent_hub']['git_repo_url'],
+        ['assets', 'title.html'],
+        @site.config['parent_hub']['git_repo_branch']
+      )
+    end
+
+    def fetch_and_read_projects
+      project_indexes = @site.collections['projects'].docs.select do |doc|
+        pieces = doc.id.split('/')
+        pieces.length == 4 and pieces[1] == 'projects' and pieces[3] == 'index'
+      end
+      project_indexes.each do |project|
+        project_path = project.path.split('/')[0..-2].join('/')
+
+        git_shallow_checkout(
+          project_path,
+          project['site']['git_repo_url'],
+          %w[assets _posts _software _specs],
+          project['site']['git_repo_branch']
+        )
+
+        Jekyll.logger.debug('OPF:', "Reading files in project #{project_path}")
+
+        CollectionDocReader.new(site).read(
+          project_path,
+          @site.collections['projects']
+        )
+
+        fetch_and_read_software('projects')
+        fetch_and_read_specs('projects')
+      end
+    end
+
+    def build_and_read_spec_pages(collection_name, index_doc, build_pages: false)
+      spec_config = extract_spec_config(index_doc)
+      repo_checkout = git_shallow_checkout(
+        spec_config[:checkout_path],
+        spec_config[:repo_url],
+        [spec_config[:repo_subtree]],
+        spec_config[:repo_branch]
+      )
+
+      return unless repo_checkout[:success]
+
+      build_spec_pages(collection_name, index_doc, spec_config) if build_pages
+
+      index_doc.merge_data!({ 'last_update' => repo_checkout[:modified_at] })
+    end
+
+    def extract_spec_config(index_doc)
+      item_name = index_doc.id.split('/')[-1]
+      src = index_doc.data['spec_source']
+      build = src['build']
+
+      spec_checkout_path = "#{index_doc.path.split('/')[0..-2].join('/')}/#{item_name}"
+      spec_root = src['git_repo_subtree'] ? "#{spec_checkout_path}/#{src['git_repo_subtree']}" : spec_checkout_path
+
+      {
+        item_name: item_name,
+        repo_url: src['git_repo_url'],
+        repo_subtree: src['git_repo_subtree'],
+        repo_branch: src['git_repo_branch'],
+        engine: build['engine'],
+        engine_opts: build['options'] || {},
+        checkout_path: spec_checkout_path,
+        spec_root: spec_root
+      }
+    end
+
+    def build_spec_pages(collection_name, index_doc, spec_config)
+      builder = Rop::SpecBuilder.new(
+        @site,
+        index_doc,
+        spec_config[:spec_root],
+        "specs/#{spec_config[:item_name]}",
+        spec_config[:engine],
+        spec_config[:engine_opts]
+      )
+
+      builder.build
+      builder.built_pages.each do |page|
+        @site.pages << page
+      end
+
+      CollectionDocReader.new(site).read(
+        spec_config[:checkout_path],
+        @site.collections[collection_name]
+      )
+    end
+
+    def fetch_and_read_specs(collection_name, build_pages: false)
+      # collection_name would be either specs or (for hub site) projects
+
+      Jekyll.logger.debug('OPF:', "Fetching specs for items in collection #{collection_name} (if it exists)")
+
+      return unless @site.collections.key?(collection_name)
+
+      Jekyll.logger.debug('OPF:', "Fetching specs for items in collection #{collection_name}")
+
+      # Get spec entry points
+      entry_points = @site.collections[collection_name].docs.select do |doc|
+        doc.data['spec_source']
+      end
+
+      if entry_points.empty?
+        Jekyll.logger.info('OPF:',
+                           "Fetching specs for items in collection #{collection_name}: No entry points")
+      end
+
+      entry_points.each do |index_doc|
+        Jekyll.logger.debug('OPF:', "Fetching specs: entry point #{index_doc.id} in collection #{collection_name}")
+        build_and_read_spec_pages(collection_name, index_doc, build_pages: build_pages)
+      end
+    end
+
+    def fetch_and_read_software(collection_name)
+      # collection_name would be either software or (for hub site) projects
+
+      Jekyll.logger.debug('OPF:', "Fetching software for items in collection #{collection_name} (if it exists)")
+
+      return unless @site.collections.key?(collection_name)
+
+      Jekyll.logger.debug('OPF:', "Fetching software for items in collection #{collection_name}")
+
+      entry_points = @site.collections[collection_name].docs.select do |doc|
+        doc.data['repo_url']
+      end
+
+      if entry_points.empty?
+        Jekyll.logger.info('OPF:',
+                           "Fetching software for items in collection #{collection_name}: No entry points")
+      end
+
+      entry_points.each do |index_doc|
+        item_name = index_doc.id.split('/')[-1]
+        Jekyll.logger.debug('OPF:', "Fetching software: entry point #{index_doc.id} in collection #{collection_name}")
+
+        docs = index_doc.data['docs']
+        main_repo = index_doc.data['repo_url']
+        main_repo_branch = index_doc.data['repo_branch']
+
+        sw_docs_repo = (docs['git_repo_url'] if docs) || main_repo
+        sw_docs_subtree = (docs['git_repo_subtree'] if docs) || DEFAULT_DOCS_SUBTREE
+        sw_docs_branch = (docs['git_repo_branch'] if docs) || main_repo_branch
+
+        docs_path = "#{index_doc.path.split('/')[0..-2].join('/')}/#{item_name}"
+
+        sw_docs_checkout = git_shallow_checkout(docs_path, sw_docs_repo, [sw_docs_subtree], sw_docs_branch)
+
+        if sw_docs_checkout[:success]
+          CollectionDocReader.new(site).read(
+            docs_path,
+            @site.collections[collection_name]
+          )
+        end
+
+        # Get last repository modification timestamp.
+        # Fetch the repository for that purpose,
+        # unless it’s the same as the repo where docs are.
+        if !sw_docs_checkout[:success] || (sw_docs_repo != main_repo)
+          repo_path = "#{index_doc.path.split('/')[0..-2].join('/')}/_#{item_name}_repo"
+          repo_checkout = git_shallow_checkout(repo_path, main_repo, [], main_repo_branch)
+          index_doc.merge_data!({ 'last_update' => repo_checkout[:modified_at] })
+        else
+          index_doc.merge_data!({ 'last_update' => sw_docs_checkout[:modified_at] })
+        end
+      end
+    end
+
+    def git_shallow_checkout(repo_path, remote_url, sparse_subtrees, branch_name)
+      # Returns hash with timestamp of latest repo commit
+      # and boolean signifying whether new repo has been initialized
+      # in the process of pulling the data.
+
+      newly_initialized = false
+      repo = nil
+
+      git_dir = File.join(repo_path, '.git')
+      git_info_dir = File.join(git_dir, 'info')
+      git_sparse_checkout_file = File.join(git_dir, 'info', 'sparse-checkout')
+      if File.exist? git_dir
+        repo = Git.open(repo_path)
+
+      else
+        newly_initialized = true
+
+        repo = Git.init(repo_path)
+
+        repo.config(
+          'core.sshCommand',
+          'ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no'
+        )
+
+        repo.add_remote(DEFAULT_REPO_REMOTE_NAME, remote_url)
+
+        if sparse_subtrees.size.positive?
+          repo.config('core.sparseCheckout', true)
+
+          FileUtils.mkdir_p git_info_dir
+          File.open(git_sparse_checkout_file, 'a') do |f|
+            sparse_subtrees.each { |path| f << "#{path}\n" }
+          end
+        end
+
+      end
+
+      refresh_condition = @@siteconfig['refresh_remote_data'] || 'last-resort'
+      repo_branch = branch_name || @@siteconfig['default_repo_branch'] || DEFAULT_REPO_BRANCH
+
+      raise 'Invalid refresh_remote_data value in site’s _config.yml!' unless %w[always last-resort
+                                                                                 skip].include?(refresh_condition)
+
+      if refresh_condition == 'always'
+        repo.fetch(DEFAULT_REPO_REMOTE_NAME, { depth: 1 })
+        repo.reset_hard
+        repo.checkout("#{DEFAULT_REPO_REMOTE_NAME}/#{repo_branch}", { f: true })
+
+      elsif refresh_condition == 'last-resort'
+        # This is the default case.
+
+        begin
+          # Let’s try in case this repo has been fetched before (this would never be the case on CI though)
+          repo.checkout("#{DEFAULT_REPO_REMOTE_NAME}/#{repo_branch}", { f: true })
+        rescue StandardError => e
+          if is_sparse_checkout_error(e, sparse_subtrees)
+            # Silence errors caused by nonexistent sparse checkout directories
+            return {
+              success: false,
+              newly_initialized: nil,
+              modified_at: nil
+            }
+          else
+            # In case of any other error, presume repo has not been fetched and do that now.
+            Jekyll.logger.debug('OPF:', "Fetching & checking out #{remote_url} for #{repo_path}")
+            repo.fetch(DEFAULT_REPO_REMOTE_NAME, { depth: 1 })
+            begin
+              # Try checkout again
+              repo.checkout("#{DEFAULT_REPO_REMOTE_NAME}/#{repo_branch}", { f: true })
+            rescue StandardError => e
+              raise e unless is_sparse_checkout_error(e, sparse_subtrees)
+
+              # Again, silence an error caused by nonexistent sparse checkout directories…
+              return {
+                success: false,
+                newly_initialized: nil,
+                modified_at: nil
+              }
+
+              # but this time throw any other error.
+            end
+          end
+        end
+      end
+
+      latest_commit = repo.gcommit('HEAD')
+
+      {
+        success: true,
+        newly_initialized: newly_initialized,
+        modified_at: latest_commit.date
+      }
+    end
+
+    def is_sparse_checkout_error(err, subtrees)
+      if err.message.include? 'Sparse checkout leaves no entry on working directory'
+        Jekyll.logger.debug('OPF: It looks like sparse checkout of these directories failed:', subtrees.to_s)
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/lib/rop/site_type.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rop
+  #
+  # Infers from available content whether the site is a hub
+  # or individual project site, and adds site-wide config variable
+  # accessible as {{ site.is_hub }} in Liquid.
+  #
+  class SiteTypeVariableGenerator < Jekyll::Generator
+    def generate(site)
+      site.config['is_hub'] = hub_site?(site)
+    end
+
+    private
+
+    # If there’re projects defined, we assume it is indeed
+    # a Jekyll Open Project hub site.
+    def hub_site?(site)
+      projects = site.collections['projects']
+      projects&.docs&.any?
+    end
+  end
+end

data/lib/rop/spec_builder.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'fastimage'
+require_relative 'png_diagram_page'
+
+module Rop
+  class SpecBuilder
+    attr_reader :built_pages
+
+    def initialize(site, spec_index_doc, spec_source_base, spec_out_base, engine, opts)
+      require_relative engine
+
+      @site = site
+      @spec_index_doc = spec_index_doc
+      @spec_source_base = spec_source_base
+      @spec_out_base = spec_out_base
+      @opts = opts
+
+      @built_pages = []
+    end
+
+    def build
+      @built_pages = build_spec_pages(
+        @site,
+        @spec_index_doc,
+        @spec_source_base,
+        @spec_out_base,
+        @opts
+      )
+    end
+
+    def build_spec_pages(site, spec_info, source, dest, _opts)
+      nav_items = get_nav_items_with_path(
+        spec_info.data['navigation']['items']
+      )
+
+      pages, not_found_items = process_spec_images(site, source, nav_items,
+                                                   dest, spec_info)
+
+      not_found_items.each do |item|
+        warn "SPECIFIED PNG NOT FOUND: #{item['title']}.png not found " \
+            "at source as specified at (#{dest})."
+      end
+
+      pages
+    end
+
+    # Recursively go through given list of nav_items, including any nested items,
+    # and return a flat array containing navigation items with path specified.
+    def get_nav_items_with_path(nav_items)
+      items_with_path = []
+
+      nav_items.each do |item|
+        items_with_path.push(item) if item['path']
+
+        items_with_path.concat(get_nav_items_with_path(item['items'])) if item['items']
+      end
+
+      items_with_path
+    end
+
+    def process_spec_images(site, source, nav_items, dest, spec_info)
+      pages = []
+      not_found_items = nav_items.dup
+
+      Dir.glob("#{source}/*.png") do |pngfile|
+        png_name = File.basename(pngfile)
+        png_name_noext = File.basename(png_name, File.extname(png_name))
+
+        nav_item = find_nav_items(nav_items, png_name_noext)[0].clone
+
+        if nav_item.nil?
+          warn "UNUSED PNG: #{File.basename(pngfile)} detected at source " \
+              "without a corresponding navigation item at (#{dest})."
+          next
+        end
+
+        not_found_items.delete_if { |item| item['title'] == nav_item['title'] }
+
+        data = build_spec_page_data(pngfile, dest, png_name, nav_item,
+                                    spec_info)
+
+        pages << build_spec_page(site, dest, png_name_noext, data)
+      end
+
+      [pages, not_found_items]
+    end
+
+    def find_nav_items(diagram_nav_items, png_name_noext)
+      diagram_nav_items.select do |item|
+        item['path'].start_with?(png_name_noext)
+      end
+    end
+
+    def build_spec_page(site, spec_root, png_name_noext, data)
+      page = PngDiagramPage.new(
+        site,
+        site.source,
+        File.join(spec_root, png_name_noext),
+        data
+      )
+
+      stub_path = "#{File.dirname(__FILE__)}/png_diagram.html"
+      page.content = File.read(stub_path)
+
+      page
+    end
+
+    def build_spec_page_data(pngfile, spec_root, png_name, nav_item, spec_info)
+      data = fill_image_data(pngfile, spec_info, spec_root, png_name)
+             .merge(nav_item)
+
+      data['title'] = "#{spec_info['title']}: #{nav_item['title']}"
+      data['article_header_title'] = nav_item['title'].to_s
+
+      data
+    end
+
+    def fill_image_data(pngfile, spec_info, spec_root, png_name)
+      png_dimensions = FastImage.size(pngfile)
+      data = spec_info.data.clone
+      data['image_path'] = "/#{spec_root}/images/#{png_name}"
+      data['image_width'] = png_dimensions[0]
+      data['image_height'] = png_dimensions[1]
+      data
+    end
+  end
+end

data/lib/rop/version.rb

@@ -0,0 +1,3 @@
+module Rop
+  VERSION = '2.1.18'
+end

data/lib/rop.rb

@@ -0,0 +1,5 @@
+require_relative 'rop/site_type'
+require_relative 'rop/project_reader'
+require_relative 'rop/filterable_index'
+require_relative 'rop/blog_index'
+require_relative 'rop/spec_builder'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-rop
 version: !ruby/object:Gem::Version
-  version: 2.1.16
+  version: 2.1.18
 platform: ruby
 authors:
 - Ribose Inc.
@@ -187,6 +187,7 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- Rakefile
 - _config.yml
 - _data/placeholder.yml
 - _includes/_nav-item.html
@@ -250,6 +251,18 @@ files:
 - assets/js/headroom.min.js
 - assets/js/opf.js
 - assets/listing-widget.js
+- lib/jekyll-theme-open-project.rb
+- lib/jekyll-theme-rop.rb
+- lib/rop.rb
+- lib/rop/_plugins
+- lib/rop/blog_index.rb
+- lib/rop/filterable_index.rb
+- lib/rop/png_diagram.html
+- lib/rop/png_diagram_page.rb
+- lib/rop/project_reader.rb
+- lib/rop/site_type.rb
+- lib/rop/spec_builder.rb
+- lib/rop/version.rb
 homepage: https://github.com/riboseinc/jekyll-theme-rop/
 licenses:
 - MIT