jekyll-theme-guides-mbland 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e79364366d4d3392bdd47efda04901a09eee31d0
-  data.tar.gz: 29ded9e8074cf019a88525324611745c003ead7b
+  metadata.gz: 29934a58f4e2a89479b2df4e2d399ad911a8e854
+  data.tar.gz: 47be69db1434d7b7b57ac129f30d2f8354a4dd7b
 SHA512:
-  metadata.gz: 8b113bba5ff0a0a6f73d8179a38cdcc1bb3d9150c22b0703b780a3c600fd61c98ec72d7fe2dc53d68d6d524fb64fef3eaae6bb716fb1ae9170d9c09471577099
-  data.tar.gz: be60c0b9ed4436e02545e1cbce6dea5204c63e75d191abc1b98a522542db7e31f266dc13c6dda702422bb6faa868800462266254ef0f962b594ac5eaa8a53b0f
+  metadata.gz: c226a22e83ede73c78f45e96e395ad21143e80483e3e52649f9237fa1391448fc7d987e0e9383660be884ca910c999b0900863f56a5d5ff958d6376cc6c2127f
+  data.tar.gz: 63363244938c0a3d5d5a5cc032dd22230062909cc11a3e898e159b2d86e5c1c2966369c77b1e7b64cd9ea6ee932eb92c35cf4133ae5d261cb716ded568a843f4

data/lib/jekyll-theme-guides-mbland.rb

@@ -0,0 +1,10 @@
+require 'jekyll-theme-guides-mbland/breadcrumbs'
+require 'jekyll-theme-guides-mbland/generator'
+require 'jekyll-theme-guides-mbland/navigation'
+require 'jekyll-theme-guides-mbland/repository'
+require 'jekyll-theme-guides-mbland/tags'
+require 'jekyll-theme-guides-mbland/update'
+require 'jekyll-theme-guides-mbland/version'
+
+require 'jekyll_pages_api'
+require 'jekyll_pages_api_search'

data/lib/jekyll-theme-guides-mbland/breadcrumbs.rb

@@ -0,0 +1,28 @@
+require 'jekyll'
+require 'safe_yaml'
+
+module JekyllThemeGuidesMbland
+  class Breadcrumbs
+    def self.generate(site, docs)
+      breadcrumbs = create_breadcrumbs(site)
+      docs.each do |page|
+        page.data['breadcrumbs'] = breadcrumbs[page.permalink || page.url]
+      end
+    end
+
+    def self.create_breadcrumbs(site)
+      (site.config['navigation'] || []).flat_map do |nav|
+        Breadcrumbs.generate_breadcrumbs(nav, '/', [])
+      end.to_h
+    end
+
+    def self.generate_breadcrumbs(nav, parent_url, parents)
+      url = parent_url + (nav['url'] || '')
+      crumbs = parents + [{ 'url' => url, 'text' => nav['text'] }]
+      child_crumbs = (nav['children'] || []).flat_map do |child|
+        generate_breadcrumbs(child, url, crumbs)
+      end
+      [[url, crumbs]] + child_crumbs
+    end
+  end
+end

data/lib/jekyll-theme-guides-mbland/generated_nodes.rb

@@ -0,0 +1,64 @@
+module JekyllThemeGuidesMbland
+  class GeneratedNodes
+    # Params:
+    #   url_to_nav: Mapping from original document URL to "nav item" objects,
+    #     i.e. { 'text' => '...', 'url' => '...', 'internal' => true }
+    #   nav_data: Array of nav item objects contained in `url_to_nav` after
+    #     applying updates, possibly containing "orphan" items marked with an
+    #     `:orphan_url` property
+    #
+    # Returns:
+    #   nav_data with orphans properly nested within automatically-generated
+    #     parent nodes marked with `'generated' => true`
+    def self.create_homes_for_orphans(url_to_nav, nav_data)
+      orphans = nav_data.select { |nav| nav[:orphan_url] }
+      orphans.each { |nav| create_home_for_orphan(nav, nav_data, url_to_nav) }
+      nav_data.reject! { |nav| nav[:orphan_url] }
+      prune_childless_parents(nav_data)
+    end
+
+    def self.create_home_for_orphan(nav, nav_data, url_to_nav)
+      parents = nav[:orphan_url].split('/')[1..-1]
+      nav['url'] = parents.pop + '/'
+      child_url = '/'
+      immediate_parent = parents.reduce(nil) do |parent, child|
+        child_url = child_url + child + '/'
+        find_or_create_node(nav_data, child_url, parent, child, url_to_nav)
+      end
+      assign_orphan_to_home(nav, immediate_parent, url_to_nav)
+    end
+
+    def self.find_or_create_node(nav_data, child_url, parent, child, url_to_nav)
+      child_nav = url_to_nav[child_url]
+      if child_nav.nil?
+        child_nav = generated_node(child)
+        url_to_nav[child_url] = child_nav
+        (parent.nil? ? nav_data : (parent['children'] ||= [])) << child_nav
+      end
+      child_nav
+    end
+
+    def self.generated_node(parent_slug)
+      {
+        'text' => parent_slug.split('-').join(' ').capitalize,
+        'url' => parent_slug + '/',
+        'internal' => true,
+        'generated' => true,
+      }
+    end
+
+    def self.assign_orphan_to_home(nav, immediate_parent, url_to_nav)
+      nav_copy = {}.merge(nav)
+      url_to_nav[nav_copy.delete(:orphan_url)] = nav_copy
+      (immediate_parent['children'] ||= []) << nav_copy
+    end
+
+    def self.prune_childless_parents(nav_data)
+      (nav_data || []).reject! do |nav|
+        children = (nav['children'] || [])
+        prune_childless_parents(children)
+        nav['generated'] && children.empty?
+      end
+    end
+  end
+end

data/lib/jekyll-theme-guides-mbland/generated_pages.rb

@@ -0,0 +1,36 @@
+module JekyllThemeGuidesMbland
+  class GeneratedPages
+    DEFAULT_LAYOUT = 'jekyll_theme_guides_mbland_generated_home_redirect'.freeze
+
+    def self.generate_pages_from_navigation_data(site)
+      layout = site.config['generate_nodes']
+      return if layout.nil? || layout == false
+      layout = DEFAULT_LAYOUT if layout == true
+      nav_data = site.config['navigation']
+      generate_pages_from_generated_nodes(site, layout, nav_data, '/')
+    end
+
+    def self.generate_pages_from_generated_nodes(site, layout, nav_data,
+      parent_url)
+      (nav_data || []).select { |nav| nav['generated'] }.each do |nav|
+        site.pages << GeneratedPage.new(site, layout, nav, parent_url)
+        children = nav['children']
+        next_url = parent_url + nav['url']
+        generate_pages_from_generated_nodes(site, layout, children, next_url)
+      end
+    end
+  end
+
+  class GeneratedPage < ::Jekyll::Page
+    def initialize(site, layout, nav, parent_url)
+      @site = site
+      @name = 'index.html'
+
+      process(@name)
+      @data = {}
+      data['title'] = nav['text']
+      data['permalink'] = parent_url + nav['url']
+      data['layout'] = layout
+    end
+  end
+end

data/lib/jekyll-theme-guides-mbland/generator.rb

@@ -0,0 +1,17 @@
+require_relative './breadcrumbs'
+require_relative './generated_pages'
+require_relative './namespace_flattener'
+
+require 'jekyll'
+
+module JekyllThemeGuidesMbland
+  class Generator < ::Jekyll::Generator
+    def generate(site)
+      GeneratedPages.generate_pages_from_navigation_data(site)
+      pages = site.collections['pages']
+      docs = (pages.nil? ? [] : pages.docs) + site.pages
+      Breadcrumbs.generate(site, docs)
+      NamespaceFlattener.flatten_url_namespace(site, docs)
+    end
+  end
+end

data/lib/jekyll-theme-guides-mbland/namespace_flattener.rb

@@ -0,0 +1,39 @@
+module JekyllThemeGuidesMbland
+  class NamespaceFlattener
+    def self.flatten_url_namespace(site, docs)
+      flatten_urls(docs) if site.config['flat_namespace']
+    end
+
+    def self.flatten_urls(docs)
+      flat_to_orig = {}
+      docs.each { |page| flatten_page_urls(page, flat_to_orig) }
+      check_for_collisions(flat_to_orig)
+    end
+
+    def self.flatten_page_urls(page, flat_to_orig)
+      orig_url = page.permalink || page.url
+      flattened_url = flat_url(orig_url)
+      (flat_to_orig[flattened_url] ||= []) << orig_url
+      page.data['permalink'] = flattened_url
+      (page.data['breadcrumbs'] || []).each do |crumb|
+        crumb['url'] = flat_url(crumb['url'])
+      end
+    end
+
+    def self.flat_url(url)
+      url == '/' ? url : "/#{url.split('/')[1..-1].last}/"
+    end
+
+    def self.check_for_collisions(flat_to_orig)
+      collisions = flat_to_orig.map do |flattened, orig|
+        [flattened, orig] if orig.size != 1
+      end.compact
+
+      return if collisions.empty?
+
+      messages = collisions.map { |flat, orig| "#{flat}: #{orig.join(', ')}" }
+      raise StandardError, "collisions in flattened namespace between\n  " +
+        messages.join("\n  ")
+    end
+  end
+end

data/lib/jekyll-theme-guides-mbland/navigation.rb

@@ -0,0 +1,257 @@
+require_relative './generated_nodes'
+
+require 'jekyll'
+require 'safe_yaml'
+
+module JekyllThemeGuidesMbland
+  module FrontMatter
+    EXTNAMES = %w[.md .html].freeze
+
+    def self.load(basedir)
+      # init_file_to_front_matter_map is initializing the map with a nil value
+      # for every file that _should_ contain front matter as far as the
+      # navigation menu is concerned. Any nil values that remain after merging
+      # with the site_file_to_front_matter map will result in a validation
+      # error.
+      init_file_to_front_matter_map(basedir)
+        .merge(site_file_to_front_matter(init_site(basedir)))
+    end
+
+    def self.validate_with_message_upon_error(front_matter)
+      files_with_errors = validate front_matter
+      return if files_with_errors.empty?
+      message = ['The following files have errors in their front matter:']
+      files_with_errors.each do |file, errors|
+        message << "  #{file}:"
+        message.concat(errors.map { |error| "    #{error}" })
+      end
+      message.join "\n" unless message.size == 1
+    end
+
+    def self.validate(front_matter)
+      front_matter.map do |file, data|
+        next [file, ['no front matter defined']] if data.nil?
+        errors = missing_property_errors(data) + permalink_errors(data)
+        [file, errors] unless errors.empty?
+      end.compact.to_h
+    end
+
+    class << self
+      private
+
+      def init_site(basedir)
+        Dir.chdir(basedir) do
+          config = SafeYAML.load_file('_config.yml', safe: true)
+          adjust_config_paths(basedir, config)
+          site = Jekyll::Site.new(Jekyll.configuration(config))
+          site.reset
+          site.read
+          site
+        end
+      end
+
+      def adjust_config_paths(basedir, config)
+        source = config['source']
+        config['source'] = source.nil? ? basedir : File.join(basedir, source)
+        destination = config['destination']
+        destination = '_site' if destination.nil?
+        config['destination'] = File.join(basedir, destination)
+      end
+
+      def site_file_to_front_matter(site)
+        site_pages(site).map do |page|
+          [page.relative_path,  page.data]
+        end.to_h
+      end
+
+      # We're supporting two possible configurations:
+      #
+      # - a `pages/` directory in which documents appear as part of the regular
+      #   site.pages collection; we have to filter by page.relative_path, and we
+      #   do not assign a permalink so that validation (in a later step) will
+      #   ensure that each page has a permalink assigned
+      #
+      # - an actual `pages` collection, stored in a `_pages` directory; no
+      #   filtering is necessary, and we can reliably set the permalink to
+      #   page.url as a default
+      def site_pages(site)
+        pages = site.collections['pages']
+        if pages.nil?
+          site.pages.select do |page|
+            # Handle both with and without leading slash, as leading slash was
+            # removed in v3.2.0.pre.beta2:
+            # jekyll/jekyll/commit/4fbbeddae20fa52732f30ef001bb1f80258bc5d7
+            page.relative_path.start_with?('/pages/', 'pages/') ||
+              page.url == '/'
+          end
+        else
+          pages.docs.each { |page| page.data['permalink'] ||= page.url }
+        end
+      end
+
+      def init_file_to_front_matter_map(basedir)
+        file_to_front_matter = {}
+        Dir.chdir(basedir) do
+          pages_dir = Dir.exist?('_pages') ? '_pages' : 'pages'
+          Dir[File.join(pages_dir, '**', '*')].each do |file_name|
+            extname = File.extname(file_name)
+            next unless File.file?(file_name) && EXTNAMES.include?(extname)
+            file_to_front_matter[file_name] = nil
+          end
+        end
+        file_to_front_matter
+      end
+
+      def missing_property_errors(data)
+        properties = %w[title permalink]
+        properties.map { |p| "no `#{p}:` property" if data[p].nil? }.compact
+      end
+
+      def permalink_errors(data)
+        pl = data['permalink']
+        return [] if pl.nil?
+        errors = []
+        errors << "`permalink:` does not begin with '/'" \
+          unless pl.start_with? '/'
+        errors << "`permalink:` does not end with '/'" unless pl.end_with? '/'
+        errors
+      end
+    end
+  end
+
+  # Automatically updates the `navigation:` field in _config.yml.
+  #
+  # Does this by parsing the front matter from files in `pages/`. Preserves the
+  # existing order of items in `navigation:`, but new items may need to be
+  # reordered manually.
+  def self.update_navigation_configuration(basedir)
+    config_path = File.join basedir, '_config.yml'
+    config_data = SafeYAML.load_file config_path, safe: true
+    return unless config_data
+    nav_data = config_data['navigation'] || []
+    NavigationMenu.update_navigation_data(nav_data, basedir, config_data)
+    NavigationMenuWriter.write_navigation_data_to_config_file(config_path,
+      nav_data)
+  end
+
+  module NavigationMenu
+    def self.update_navigation_data(nav_data, basedir, config_data)
+      original = map_nav_items_by_url('/', nav_data).to_h
+      updated = updated_nav_data(basedir)
+      remove_stale_nav_entries(nav_data, original, updated)
+      updated.map { |url, nav| apply_nav_update(url, nav, nav_data, original) }
+      if config_data['generate_nodes']
+        GeneratedNodes.create_homes_for_orphans(original, nav_data)
+      else
+        check_for_orphaned_items(nav_data)
+      end
+    end
+
+    def self.map_nav_items_by_url(parent_url, nav_data)
+      nav_data.flat_map do |nav|
+        url = File.join('', parent_url, nav['url'] || '')
+        [[url, nav]].concat(map_nav_items_by_url(url, nav['children'] || []))
+      end
+    end
+
+    def self.updated_nav_data(basedir)
+      front_matter = FrontMatter.load basedir
+      errors = FrontMatter.validate_with_message_upon_error front_matter
+      abort errors + "\n_config.yml not updated" if errors
+      front_matter
+        .values.sort_by { |fm| fm['permalink'] }
+        .map { |fm| [fm['permalink'], page_nav(fm)] }.to_h
+    end
+
+    def self.page_nav(front_matter)
+      url_components = front_matter['permalink'].split('/')[1..-1]
+      result = {
+        'text' => front_matter['navtitle'] || front_matter['title'],
+        'url' => "#{url_components.nil? ? '' : url_components.last}/",
+        'internal' => true,
+      }
+      # Delete the root URL so we don't have an empty `url:` property laying
+      # around.
+      result.delete 'url' if result['url'] == '/'
+      result
+    end
+
+    def self.remove_stale_nav_entries(nav_data, original, updated)
+      # Remove old entries whose pages have been deleted
+      original.each do |url, nav|
+        if !updated.member?(url) && nav['internal'] && !nav['generated']
+          nav['delete'] = true
+        end
+      end
+      original.delete_if { |_url, nav| nav['delete'] }
+      nav_data.delete_if { |nav| nav['delete'] }
+      nav_data.each { |nav| remove_stale_children(nav) }
+    end
+
+    def self.remove_stale_children(parent)
+      children = (parent['children'] || [])
+      children.delete_if { |nav| nav['delete'] }
+      parent.delete 'children' if children.empty?
+      children.each { |child| remove_stale_children(child) }
+    end
+
+    def self.apply_nav_update(url, nav, nav_data, original)
+      orig = original[url]
+      if orig.nil?
+        apply_new_nav_item(url, nav, nav_data, original)
+      else
+        orig['text'] = nav['text']
+        orig.delete('generated')
+      end
+    end
+
+    def self.apply_new_nav_item(url, nav, nav_data, original)
+      parent_url = File.dirname(url || '/')
+      parent = original["#{parent_url}/"]
+      if parent_url == '/'
+        nav_data << (original[url] = nav)
+      elsif parent.nil?
+        nav_data << nav.merge(orphan_url: url)
+      else
+        (parent['children'] ||= []) << nav
+      end
+    end
+
+    def self.check_for_orphaned_items(nav_data)
+      orphan_urls = nav_data.map { |nav| nav[:orphan_url] }.compact
+      return if orphan_urls.empty?
+      raise StandardError, "Parent pages missing for the following:\n  " +
+        orphan_urls.join("\n  ")
+    end
+  end
+
+  class NavigationMenuWriter
+    def self.write_navigation_data_to_config_file(config_path, nav_data)
+      lines = []
+      in_navigation = false
+      open(config_path).each_line do |line|
+        in_navigation = process_line line, lines, nav_data, in_navigation
+      end
+      File.write config_path, lines.join
+    end
+
+    def self.process_line(line, lines, nav_data, in_navigation = false)
+      if !in_navigation && line.start_with?('navigation:')
+        lines << line << format_navigation_section(nav_data)
+        in_navigation = true
+      elsif in_navigation
+        in_navigation = line.start_with?(' ', '-')
+        lines << line unless in_navigation
+      else
+        lines << line
+      end
+      in_navigation
+    end
+
+    YAML_PREFIX = "---\n".freeze
+
+    def self.format_navigation_section(nav_data)
+      nav_data.empty? ? '' : nav_data.to_yaml[YAML_PREFIX.size..-1]
+    end
+  end
+end

data/lib/jekyll-theme-guides-mbland/repository.rb

@@ -0,0 +1,73 @@
+require 'English'
+require 'fileutils'
+
+module JekyllThemeGuidesMbland
+  TEMPLATE_FILES = %w[
+    _pages/add-a-new-page/make-a-child-page.md
+    _pages/add-a-new-page.md
+    _pages/add-images.md
+    _pages/advanced-features.md
+    _pages/github-setup.md
+    _pages/images.png
+    _pages/post-your-guide.md
+    _pages/update-the-config-file/understanding-baseurl.md
+    _pages/update-the-config-file.md
+    images/description.png
+    images/gh-add-guide.png
+    images/gh-branches-link.png
+    images/gh-default-branch.png
+    images/gh-settings-button.png
+    images/gh-webhook.png
+  ].freeze
+
+  def self.clear_template_files_and_create_new_repository(basedir,
+    outstream = $stdout)
+    remove_template_files basedir, outstream
+    delete_create_repo_command_from_go_script basedir, outstream
+    create_new_git_repository basedir, outstream
+  end
+
+  def self.remove_template_files(basedir, outstream)
+    Dir.chdir basedir do
+      outstream.puts 'Clearing Guides Template files.'
+      files = TEMPLATE_FILES.map { |f| File.join basedir, f }
+                            .select { |f| File.exist? f }
+      File.delete(*files)
+    end
+  end
+
+  def self.delete_create_repo_command_from_go_script(basedir, outstream)
+    Dir.chdir basedir do
+      outstream.puts 'Removing `:create_repo` command from the `./go` script.'
+      go_script = File.join basedir, 'go'
+      content = File.read go_script
+      match = /\ndef_command\(\n  :create_repo,.*?end\n/m.match content
+      content = "#{match.pre_match}#{match.post_match}" unless match.nil?
+      File.write go_script, content
+    end
+  end
+
+  GIT_COMMANDS = {
+    'Creating a new git repository.' => 'git init',
+    'Creating mbland-pages branch.' => 'git checkout -b mbland-pages',
+    'Adding files for initial commit.' => 'git add .',
+  }.freeze
+
+  def self.create_new_git_repository(basedir, outstream)
+    Dir.chdir basedir do
+      outstream.puts 'Removing old git repository.'
+      FileUtils.rm_rf '.git'
+      GIT_COMMANDS.each do |description, command|
+        outstream.puts description
+        exec_cmd_capture_output command, outstream
+      end
+      outstream.puts "All done! Run \'git commit\' to create your first commit."
+    end
+  end
+  private_class_method :create_new_git_repository
+
+  def self.exec_cmd_capture_output(command, outstream)
+    opts = { out: outstream, err: outstream }
+    exit $CHILD_STATUS.exitstatus unless system command, opts
+  end
+end

data/lib/jekyll-theme-guides-mbland/tags.rb

@@ -0,0 +1,51 @@
+require 'jekyll/tags/include'
+require 'liquid'
+
+module JekyllThemeGuidesMbland
+  class ShouldExpandNavTag < ::Liquid::Tag
+    NAME = 'jekyll_theme_guides_mbland_should_expand_nav'.freeze
+    ::Liquid::Template.register_tag(NAME, self)
+
+    attr_reader :parent_reference, :url_reference
+
+    def initialize(_tag_name, markup, _)
+      references = markup.split(',').map(&:strip)
+      @parent_reference = references.shift
+      @url_reference = references.shift
+    end
+
+    def render(context)
+      scope = context.scopes.detect { |s| s.member?(url_reference) }
+      parent_url = scope[url_reference]
+      page_url = context['page']['url']
+      page_url == parent_url || page_url.start_with?(parent_url) ||
+        expand_nav_default(scope, context)
+    end
+
+    private
+
+    def expand_nav_default(scope, context)
+      default = scope[parent_reference]['expand_nav']
+      default = context['site']['expand_nav'] if default.nil?
+      default.nil? ? false : default
+    end
+  end
+
+  class PopLastUrlComponent < ::Liquid::Tag
+    NAME = 'jekyll_theme_guides_mbland_pop_last_url_component'.freeze
+    ::Liquid::Template.register_tag(NAME, self)
+
+    attr_reader :reference
+
+    def initialize(_tag_name, markup, _)
+      @reference = markup.strip
+    end
+
+    def render(context)
+      scope = context.scopes.detect { |s| s.member?(reference) }
+      parent_url = scope[reference]
+      result = File.dirname(parent_url)
+      result == '/' ? result : "#{result}/"
+    end
+  end
+end

data/lib/jekyll-theme-guides-mbland/update.rb

@@ -0,0 +1,6 @@
+module JekyllThemeGuidesMbland
+  def self.update_theme
+    exec({ 'RUBYOPT' => nil }, 'bundle',
+      *%w[update --source jekyll-theme-guides-mbland].freeze)
+  end
+end

data/lib/jekyll-theme-guides-mbland/version.rb

@@ -0,0 +1,3 @@
+module JekyllThemeGuidesMbland
+  VERSION = '0.2.1'.freeze
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-guides-mbland
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Mike Bland
@@ -180,6 +180,17 @@ files:
 - assets/js/guide.js
 - assets/js/vendor/anchor.min.js
 - assets/js/vendor/jquery-1.11.2.min.js
+- lib/jekyll-theme-guides-mbland.rb
+- lib/jekyll-theme-guides-mbland/breadcrumbs.rb
+- lib/jekyll-theme-guides-mbland/generated_nodes.rb
+- lib/jekyll-theme-guides-mbland/generated_pages.rb
+- lib/jekyll-theme-guides-mbland/generator.rb
+- lib/jekyll-theme-guides-mbland/namespace_flattener.rb
+- lib/jekyll-theme-guides-mbland/navigation.rb
+- lib/jekyll-theme-guides-mbland/repository.rb
+- lib/jekyll-theme-guides-mbland/tags.rb
+- lib/jekyll-theme-guides-mbland/update.rb
+- lib/jekyll-theme-guides-mbland/version.rb
 homepage: https://github.com/mbland/jekyll-theme-guides-mbland
 licenses:
 - ISC