guides_style_mbland 0.1.0

data/lib/guides_style_mbland/breadcrumbs.rb

@@ -0,0 +1,28 @@
+require 'jekyll'
+require 'safe_yaml'
+
+module GuidesStyleMbland
+  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/guides_style_mbland/generated_nodes.rb

@@ -0,0 +1,63 @@
+module GuidesStyleMbland
+  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/guides_style_mbland/generated_pages.rb

@@ -0,0 +1,38 @@
+require_relative './layouts'
+
+module GuidesStyleMbland
+  class GeneratedPages
+    DEFAULT_LAYOUT = 'guides_style_mbland_generated_home_redirect'
+
+    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/guides_style_mbland/generator.rb

@@ -0,0 +1,21 @@
+require_relative './assets'
+require_relative './breadcrumbs'
+require_relative './generated_pages'
+require_relative './layouts'
+require_relative './namespace_flattener'
+
+require 'jekyll'
+
+module GuidesStyleMbland
+  class Generator < ::Jekyll::Generator
+    def generate(site)
+      Layouts.register(site)
+      Assets.copy_to_site(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/guides_style_mbland/includes.rb

@@ -0,0 +1,21 @@
+require 'jekyll/tags/include'
+require 'liquid'
+
+module GuidesStyleMbland
+  class IncludeTag < ::Jekyll::Tags::IncludeTag
+    ::Liquid::Template.register_tag 'guides_style_mbland_include', self
+
+    def initialize(_tag_name, _name, _tokens)
+      super
+      @includes_dir = File.join File.dirname(__FILE__), 'includes'
+    end
+
+    def tag_includes_dir(*_context)
+      includes_dir
+    end
+
+    def resolved_includes_dir(_context)
+      includes_dir
+    end
+  end
+end

data/lib/guides_style_mbland/includes/analytics.html

@@ -0,0 +1,16 @@
+{% if site.google_analytics_ua %}<!-- Google Analytics -->
+<script>
+  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+  ga('create', '{{ site.google_analytics_ua }}', 'auto');
+
+  // anonymize user IPs (chops off the last IP triplet)
+  ga('set', 'anonymizeIp', true);
+  ga('set', 'forceSSL', true);
+  ga('send', 'pageview');
+</script>
+
+<!-- Digital Analytics Program roll-up, see https://analytics.usa.gov for data -->
+<script id="_fed_an_ua_tag" src="https://dap.digitalgov.gov/Universal-Federated-Analytics-Min.js?agency=GSA"></script>{% endif %}

data/lib/guides_style_mbland/includes/breadcrumbs.html

@@ -0,0 +1,8 @@
+<nav class="nav-main">
+  <div class="wrapper">
+    <ol class="breadcrumbs">
+    {% for breadcrumb in page.breadcrumbs %}<li>{% if forloop.last %}{{ breadcrumb.text }}{% else %}<a href="{{ site.baseurl}}{{ breadcrumb.url }}">{{ breadcrumb.text }}</a>{% endif %}</li>
+    {% endfor %}
+    </div>
+  </div>
+</nav>

data/lib/guides_style_mbland/includes/footer.html

@@ -0,0 +1,5 @@
+<footer role="contentinfo">
+  <div class="wrap">{% assign repo_url = site.repos[0].url %}
+    <p>This project is maintained by <a href="{{ site.author.url }}">{{ site.author.name }}</a>. The source is available at <a href="{{ repo_url }}">{{ repo_url }}</a>.</p>
+  </div>
+</footer>

data/lib/guides_style_mbland/includes/header.html

@@ -0,0 +1,29 @@
+<head>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width">
+
+  {% if page.title %}
+    <title>{{ page.title }} - {{ site.name }}</title>
+  {% elsif site.title %}
+    <title>{{ site.title }} - {{ site.name }}</title>
+  {% endif %}
+
+  {% if page.description %}
+    <meta name="description" content="{{ page.description | xml_escape }}">
+  {% elsif site.description %}
+    <meta name="description" content="{{ site.description | xml_escape }}">
+  {% endif %}
+
+  <link rel="shortcut icon" type="image/ico" href="{{ site.baseurl }}/assets/favicons/favicon.ico" />
+  <link rel="icon" type="image/png" sizes="16x16" href="{{ site.baseurl }}/assets/favicons/favicon16.png" />
+  <link rel="icon" type="image/png" sizes="32x32" href="{{ site.baseurl }}/assets/favicons/favicon32.png" />
+  <link rel="apple-touch-icon" href="{{ site.baseurl }}/assets/favicons/18f-center-57.png" />
+  <link rel="apple-touch-icon" sizes="76x76" href="{{ site.baseurl }}/assets/favicons/touch-icon-76.png" />
+  <link rel="apple-touch-icon" sizes="120x120" href="{{ site.baseurl }}/assets/favicons/touch-icon-120.png" />
+  <link rel="apple-touch-icon" sizes="152x152" href="{{ site.baseurl }}/assets/favicons/touch-icon-152.png"/>
+  <link href='{{ site.baseurl }}/assets/css/google-fonts.css' rel='stylesheet' type='text/css' />
+  <link rel="stylesheet" href="{{ site.baseurl }}/assets/css/styles.css" type='text/css' />{% for style in site.styles %}
+  <link rel="stylesheet" href="{{ site.baseurl }}/{{ style }}" type='text/css' />{% endfor %}{% for style in page.styles %}
+  <link rel="stylesheet" href="{{ site.baseurl }}/{{ style }}" type='text/css' />{% endfor %}
+</head>

data/lib/guides_style_mbland/includes/scripts.html

@@ -0,0 +1,6 @@
+<script src="{{ site.baseurl }}/assets/js/vendor/jquery-1.11.2.min.js"></script>
+<script src="{{ site.baseurl }}/assets/js/accordion.js"></script>
+<script src="{{ site.baseurl }}/assets/js/guide.js"></script>{% for script in site.scripts %}
+<script src="{{ site.baseurl }}/{{ script }}"></script>{% endfor %}{% for script in page.scripts %}
+<script src="{{ site.baseurl }}/{{ script }}"></script>{% endfor %}
+{% jekyll_pages_api_search_load %}

data/lib/guides_style_mbland/includes/sidebar-children.html

@@ -0,0 +1,17 @@
+{% if parent.children %}
+{% capture expand_nav %}{% guides_style_mbland_should_expand_nav parent, parent_url %}{% endcapture %}
+<button class="expand-subnav"
+        aria-expanded="{{ expand_nav }}"
+        aria-controls="nav-collapsible-{{ forloop.index }}">+</button>
+<ul class="nav-children" id="nav-collapsible-{{ forloop.index }}"
+    aria-hidden="{% if expand_nav == 'true' %}false{% else %}true{% endif %}">
+  {% for child in parent.children %}
+  {% capture child_url %}{{ parent_url }}{{ child.url }}{% endcapture %}
+    <li class="{% if page.url == child_url %}sidebar-nav-active{% endif %}">
+      <a href="{% if child.internal == true %}{{ site.baseurl }}{{ child_url }}{% else %}{{ child.url }}{% endif %}"
+        title="{% if page.url == child_url %}Current Page{% else %}{{ child.text }}{% endif %}">{{ child.text }}</a>
+      {% assign parent = child %}{% assign parent_url = child_url %}
+      {% guides_style_mbland_include sidebar-children.html %}
+      {% capture parent_url %}{% guides_style_mbland_pop_last_url_component parent_url %}{% endcapture %}
+    </li>{% endfor %}
+</ul>{% endif %}

data/lib/guides_style_mbland/includes/sidebar.html

@@ -0,0 +1,14 @@
+<aside>
+  <p class="intro">{{ site.subtitle }}</p>
+  <nav class="sidebar-nav" role="navigation">
+    <ul>{% for link in site.navigation %}{% capture parent_url %}/{{ link.url }}{% endcapture %}
+        <li class="group {% if page.url == parent_url %}sidebar-nav-active{% endif %}">
+          <a href="{% if link.internal == true %}{{ site.baseurl }}/{% endif %}{{ link.url }}"  
+            title="{% if page.url == parent_url %}Current Page
+                  {% else %}{{ link.text }}{% endif %}">{{ link.text }}</a>
+          {% assign parent = link %}
+          {% guides_style_mbland_include sidebar-children.html %}
+        </li>{% endfor %}
+    </ul>
+  </nav>
+</aside>

data/lib/guides_style_mbland/layouts.rb

@@ -0,0 +1,51 @@
+require 'jekyll/layout'
+require 'safe_yaml'
+
+module GuidesStyleMbland
+  # We have to essentially recreate the ::Jekyll::Layout constructor to loosen
+  # the default restriction that layouts be included in the site source.
+  class Layouts < ::Jekyll::Layout
+    LAYOUTS_DIR = File.join(File.dirname(__FILE__), 'layouts')
+    SEARCH_RESULTS_LAYOUT = 'search-results'
+
+    private_class_method :new
+
+    def initialize(site, subdir, layout_file)
+      @site = site
+      @base = File.join(LAYOUTS_DIR, subdir)
+      @name = "#{layout_file}.html"
+      @path = File.join @base, @name
+      parse_content_and_data File.join(@base, name)
+      process name
+    end
+
+    def parse_content_and_data(file_path)
+      self.data = {}
+      self.content = File.read(file_path)
+
+      front_matter_pattern = /^(---\n.*)---\n/m
+      front_matter_match = front_matter_pattern.match content
+      return unless front_matter_match
+
+      self.content = front_matter_match.post_match
+      self.data = SafeYAML.load front_matter_match[1],  safe: true
+    end
+    private :parse_content_and_data
+
+    def self.register(site)
+      site.layouts['guides_style_mbland_default'] = new(site, '', 'default')
+      site.layouts['guides_style_mbland_generated_home_redirect'] = new(
+        site, 'generated', 'home-redirect')
+      register_search_results_layout(site)
+    end
+
+    def self.register_search_results_layout(site)
+      layouts_dir = File.join(site.source, site.config['layouts_dir'])
+      results_layout = File.join(layouts_dir, "#{SEARCH_RESULTS_LAYOUT}.html")
+      unless File.exist?(results_layout)
+        site.layouts[SEARCH_RESULTS_LAYOUT] = new(
+          site, '', SEARCH_RESULTS_LAYOUT)
+      end
+    end
+  end
+end

data/lib/guides_style_mbland/layouts/default.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang='en'>
+
+  {% guides_style_mbland_include header.html %}
+
+  <body>
+
+    <div class="container">
+      <a class="skip-link visuallyhidden focusable" href="#main">Skip to Main Content</a>
+
+      <header role="banner">
+
+        <div class="wrap">
+
+
+          <h1 class="site-title"><a class="title-link" href="{{ site.baseurl }}/">{{ site.name }}</a></h1>{% if site.back_link %}
+
+          {% jekyll_pages_api_search_interface %}
+
+          <div class="back-link"><a href="{{ site.back_link.url }}">&laquo; {{ site.back_link.text }}</a></div>{% endif %}
+
+
+        </div>
+
+      </header>
+
+      <div class="wrap content">
+
+        <section id="main" class="main-content" role="main">
+          <h2>{{ page.title }}</h2>
+          {{ content }}
+        </section>
+
+        {% guides_style_mbland_include sidebar.html %}
+
+      </div><!-- /.wrap content -->
+
+      {% guides_style_mbland_include footer.html %}
+
+    </div> <!-- /.container -->
+
+  </body>
+{% guides_style_mbland_include analytics.html %}
+{% guides_style_mbland_include scripts.html %}
+</html>

data/lib/guides_style_mbland/layouts/generated/home-redirect.html

@@ -0,0 +1,6 @@
+<!DOCTYPE html>
+<html>
+<head><meta http-equiv="refresh" content="0;URL='{{ site.baseurl }}/#{{ page.title | slugify }}'">
+</head>
+<body></body>
+</html>

data/lib/guides_style_mbland/layouts/search-results.html

@@ -0,0 +1,4 @@
+---
+layout: guides_style_mbland_default
+---
+{% jekyll_pages_api_search_results %}

data/lib/guides_style_mbland/namespace_flattener.rb

@@ -0,0 +1,39 @@
+module GuidesStyleMbland
+  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(', ')}" }
+      fail(StandardError, "collisions in flattened namespace between\n  " +
+        messages.join("\n  "))
+    end
+  end
+end

data/lib/guides_style_mbland/navigation.rb

@@ -0,0 +1,253 @@
+require_relative './generated_nodes'
+
+require 'jekyll'
+require 'safe_yaml'
+
+module GuidesStyleMbland
+  module FrontMatter
+    EXTNAMES = %w(.md .html)
+
+    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
+
+    private
+
+    def self.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 self.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 self.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 self.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 self.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 self.missing_property_errors(data)
+      properties = %w(title permalink)
+      properties.map { |p| "no `#{p}:` property" if data[p].nil? }.compact
+    end
+
+    def self.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
+
+  # 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
+      unless orphan_urls.empty?
+        fail(StandardError, "Parent pages missing for the following:\n  " +
+          orphan_urls.join("\n  "))
+      end
+    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?(' ') || line.start_with?('-')
+        lines << line unless in_navigation
+      else
+        lines << line
+      end
+      in_navigation
+    end
+
+    YAML_PREFIX = "---\n"
+
+    def self.format_navigation_section(nav_data)
+      nav_data.empty? ? '' : nav_data.to_yaml[YAML_PREFIX.size..-1]
+    end
+  end
+end