dss_tech_docs 0.1.0

data/lib/govuk_tech_docs/table_of_contents/heading_tree_builder.rb

@@ -0,0 +1,41 @@
+module GovukTechDocs
+  module TableOfContents
+    class HeadingTreeBuilder
+      def initialize(headings)
+        @headings = headings
+        @tree = HeadingTree.new
+        @pointer = @tree
+      end
+
+      def tree
+        @headings.each do |heading|
+          move_to_depth(heading.size)
+
+          @pointer.children << HeadingTree.new(parent: @pointer, heading: heading)
+        end
+
+        @tree
+      end
+
+    private
+
+      def move_to_depth(depth)
+        if depth > @pointer.depth
+          @pointer = @pointer.children.last
+
+          if depth > @pointer.depth
+            @pointer.children << HeadingTree.new(parent: @pointer)
+
+            move_to_depth(depth)
+          end
+        end
+
+        if depth < @pointer.depth
+          @pointer = @pointer.parent
+
+          move_to_depth(depth)
+        end
+      end
+    end
+  end
+end

data/lib/govuk_tech_docs/table_of_contents/heading_tree_renderer.rb

@@ -0,0 +1,46 @@
+module GovukTechDocs
+  module TableOfContents
+    class HeadingTreeRenderer
+      DEFAULT_MAX_LEVEL = Float::INFINITY
+      DEFAULT_INDENTATION = ''.freeze
+      INDENTATION_INCREMENT = '  '.freeze
+
+      def initialize(heading_tree, max_level: nil)
+        @heading_tree = heading_tree
+        @max_level = max_level || DEFAULT_MAX_LEVEL
+      end
+
+      def html
+        render_tree(@heading_tree, level: 0)
+      end
+
+    private
+
+      def render_tree(tree, indentation: DEFAULT_INDENTATION, level: nil)
+        output = ''
+
+        if tree.heading
+          output += indentation + %{<a href="#{tree.heading.href}">#{tree.heading.title}</a>\n}
+        end
+
+        if tree.children.any? && level < @max_level
+          output += indentation + "<ul>\n"
+
+          tree.children.each do |child|
+            output += indentation + INDENTATION_INCREMENT + "<li>\n"
+            output += render_tree(
+              child,
+              indentation: indentation + INDENTATION_INCREMENT * 2,
+              level: level + 1
+            )
+            output += indentation + INDENTATION_INCREMENT + "</li>\n"
+          end
+
+          output += indentation + "</ul>\n"
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/govuk_tech_docs/table_of_contents/headings_builder.rb

@@ -0,0 +1,39 @@
+module GovukTechDocs
+  module TableOfContents
+    class HeadingsBuilder
+      def initialize(html, url)
+        @html = html
+        @url = url
+      end
+
+      def headings
+        heading_elements.map do |element|
+          Heading.new(
+            element_name: element.node_name,
+            text: element.content,
+            attributes: convert_nokogiri_attr_objects_to_hashes(element.attributes),
+            page_url: @url
+          )
+        end
+      end
+
+    private
+
+      def page
+        @_page ||= Nokogiri::HTML(@html)
+      end
+
+      def heading_elements
+        page.search('h1, h2, h3, h4, h5, h6')
+      end
+
+      def convert_nokogiri_attr_objects_to_hashes(attributes)
+        attributes.tap do |hash|
+          hash.each do |k, v|
+            hash[k] = v.value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/govuk_tech_docs/table_of_contents/helpers.rb

@@ -0,0 +1,79 @@
+require 'govuk_tech_docs/table_of_contents/heading_tree_builder'
+require 'govuk_tech_docs/table_of_contents/heading_tree_renderer'
+require 'govuk_tech_docs/table_of_contents/heading_tree'
+require 'govuk_tech_docs/table_of_contents/heading'
+require 'govuk_tech_docs/table_of_contents/headings_builder'
+
+module GovukTechDocs
+  module TableOfContents
+    module Helpers
+      def single_page_table_of_contents(html, url: '', max_level: nil)
+        headings = HeadingsBuilder.new(html, url).headings
+
+        if headings.none? { |heading| heading.size == 1 }
+          raise "No H1 tag found. You have to at least add one H1 heading to the page: " + url
+        end
+
+        tree = HeadingTreeBuilder.new(headings).tree
+        HeadingTreeRenderer.new(tree, max_level: max_level).html
+      end
+
+      def multi_page_table_of_contents(resources, current_page, config, current_page_html = nil)
+        # Only parse top level html files
+        # Sorted by weight frontmatter
+        resources = resources
+        .select { |r| r.path.end_with?(".html") && (r.parent.nil? || r.parent.url == "/") }
+        .sort_by { |r| [r.data.weight ? 0 : 1, r.data.weight || 0] }
+
+        render_page_tree(resources, current_page, config, current_page_html)
+      end
+
+      def render_page_tree(resources, current_page, config, current_page_html)
+        # Sort by weight frontmatter
+        resources = resources
+        .sort_by { |r| [r.data.weight ? 0 : 1, r.data.weight || 0] }
+        output = '';
+        resources.each do |resource|
+          # Reuse the generated content for the active page
+          # If we generate it twice it increments the heading ids
+          content =
+            if current_page.url == resource.url && current_page_html
+              current_page_html
+            else
+              resource.render(layout: false)
+            end
+          # Avoid redirect pages
+          next if content.include? "http-equiv=refresh"
+          # If this page has children, just print the title and recursively
+          # render the children. If not, print the heading structure.
+
+          # We avoid printing the children of the root index.html as it is the
+          # parent of every other top level file.  We need to take any custom
+          # prefix in to consideration when checking for the root index.html.
+          # The prefix may be set with or without a trailing slash: make sure
+          # it has one for this comparison check.
+          home_url =
+            if config[:http_prefix].end_with?("/")
+              config[:http_prefix]
+            else
+              config[:http_prefix] + "/"
+            end
+
+          if resource.children.any? && resource.url != home_url
+            output += %{<ul><li><a href="#{resource.url}">#{resource.data.title}</a>\n}
+            output += render_page_tree(resource.children, current_page, config, current_page_html)
+            output += '</li></ul>'
+          else
+            output +=
+              single_page_table_of_contents(
+                content,
+                url: resource.url,
+                max_level: config[:tech_docs][:max_toc_heading_level]
+              )
+          end
+        end
+        output
+      end
+    end
+  end
+end

data/lib/govuk_tech_docs/tech_docs_html_renderer.rb

@@ -0,0 +1,34 @@
+require 'middleman-core/renderers/redcarpet'
+
+module GovukTechDocs
+  class TechDocsHTMLRenderer < Middleman::Renderers::MiddlemanRedcarpetHTML
+    include Redcarpet::Render::SmartyPants
+
+    def initialize(options = {})
+      @local_options = options.dup
+      @app = @local_options[:context].app
+      super
+    end
+
+    def paragraph(text)
+      @app.api("<p>#{text.strip}</p>\n")
+    end
+
+    def header(text, level)
+      anchor = UniqueIdentifierGenerator.instance.create(text, level)
+      %(<h#{level} id="#{anchor}">#{text}</h#{level}>)
+    end
+
+    def image(link, *args)
+      %(<a href="#{link}" target="_blank" rel="noopener noreferrer">#{super}</a>)
+    end
+
+    def table(header, body)
+      %(<div class="table-container">
+        <table>
+          #{header}#{body}
+        </table>
+      </div>)
+    end
+  end
+end

data/lib/govuk_tech_docs/unique_identifier_extension.rb

@@ -0,0 +1,13 @@
+module GovukTechDocs
+  class UniqueIdentifierExtension < Middleman::Extension
+    def initialize(app, options_hash = {}, &block)
+      super
+
+      app.before do
+        UniqueIdentifierGenerator.instance.reset
+      end
+    end
+  end
+end
+
+::Middleman::Extensions.register(:unique_identifier, GovukTechDocs::UniqueIdentifierExtension)

data/lib/govuk_tech_docs/unique_identifier_generator.rb

@@ -0,0 +1,72 @@
+require 'singleton'
+
+module GovukTechDocs
+  class UniqueIdentifierGenerator
+    include Singleton
+
+    Anchor = Struct.new(:id, :level)
+
+    attr_reader :anchors
+
+    def initialize
+      reset
+    end
+
+    def create(id, level)
+      anchor = heading_slug(id)
+
+      unless unique?(anchor)
+        anchor = prefixed_by_parent(anchor, level)
+      end
+
+      unless unique?(anchor)
+        anchor = suffixed_with_number(anchor)
+      end
+
+      @anchors << Anchor.new(anchor, level)
+
+      anchor
+    end
+
+    def reset
+      @anchors = []
+    end
+
+  private
+
+    def prefixed_by_parent(anchor, level)
+      closest_parent = @anchors.reverse.find { |a| a.level < level }
+      if closest_parent.nil?
+        anchor
+      else
+        [closest_parent.id, anchor].join("-")
+      end
+    end
+
+    def suffixed_with_number(text)
+      number = 2
+      anchor = "#{text}-#{number}"
+
+      until unique?(anchor)
+        anchor = "#{text}-#{number}"
+        number += 1
+      end
+
+      anchor
+    end
+
+    def unique?(value)
+      @anchors.none? { |a| a.id == value }
+    end
+
+    # https://github.com/vmg/redcarpet/blob/820dadb98b3720811cc20c5570a5d43c796c85fc/ext/redcarpet/html.c#L274-L305
+    def heading_slug(text)
+      text
+        .downcase
+        .strip
+        .gsub(%r{</?[^>]+?>}, '') # Remove HTML tags
+        .gsub(/[^0-9a-z]+/, '-')  # Replace non-alphanumeric characters with dashes
+        .gsub(/\A-+|-+\z/, '')    # Remove trailing dashes
+    end
+  end
+end

data/lib/govuk_tech_docs/version.rb

@@ -0,0 +1,3 @@
+module GovukTechDocs
+  VERSION = "0.1.0".freeze
+end

data/lib/govuk_tech_docs/warning_text_extension.rb

@@ -0,0 +1,23 @@
+module GovukTechDocs
+  class WarningTextExtension < Middleman::Extension
+    def initialize(app, options_hash = {}, &block)
+      super
+    end
+
+    helpers do
+      def warning_text(text)
+        <<~EOS
+        <div class="govuk-warning-text">
+          <span class="govuk-warning-text__icon" aria-hidden="true">!</span>
+          <strong class="govuk-warning-text__text">
+            <span class="govuk-warning-text__assistive">Warning</span>
+            #{text}
+          </strong>
+        </div>
+        EOS
+      end
+    end
+  end
+end
+
+::Middleman::Extensions.register(:warning_text, GovukTechDocs::WarningTextExtension)

data/lib/source/api/pages.json.erb

@@ -0,0 +1 @@
+<%= GovukTechDocs::Pages.new(sitemap, config).to_json %>

data/lib/source/images/search-result-caret.svg

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="13px" height="23px" viewBox="0 0 13 23" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <!-- Generator: Sketch 43.2 (39069) - http://www.bohemiancoding.com/sketch -->
+    <title>Page 1</title>
+    <desc>Created with Sketch.</desc>
+    <defs></defs>
+    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g fill="#FFFFFF">
+            <polygon id="Fill-1" points="11.6343 0.8004 0.7043 11.8004 11.6343 22.8004 13 22.8004 13 0.8004"></polygon>
+            <polyline id="Stroke-2" stroke="#B4B4B4" points="11.6346 22.8004 0.7046 11.8004 11.6346 0.8004 11.6346 0.8004"></polyline>
+        </g>
+    </g>
+</svg>

data/lib/source/layouts/_analytics.erb

@@ -0,0 +1,15 @@
+<% if config[:tech_docs][:ga_tracking_id].is_a?(String) && !config[:tech_docs][:ga_tracking_id].empty? %>
+  <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', '<%= config[:tech_docs][:ga_tracking_id] %>', 'auto');
+  ga('set', 'anonymizeIp', true);
+  ga('set', 'displayFeaturesTask', null);
+  ga('set', 'transport', 'beacon');
+  ga('set', 'page', location.pathname+location.search+location.hash);
+  ga('send', 'pageview');
+  </script>
+<% end %>

data/lib/source/layouts/_footer.erb

@@ -0,0 +1,10 @@
+<footer class="footer">
+  <div class="footer__licence">
+    <a class="footer__licence-logo" href="https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" rel="license">Open Government Licence</a>
+    <p class="footer__licence-description">All content is available under the <a href="https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" rel="license">Open Government Licence v3.0</a>, except where otherwise stated</p>
+  </div>
+
+  <div class="footer__copyright">
+    <a class="footer__copyright-logo" href="http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/copyright-and-re-use/crown-copyright/">© Crown copyright</a>
+  </div>
+</footer>

data/lib/source/layouts/_header.erb

@@ -0,0 +1,44 @@
+<header class="header header--full-width">
+  <div class="header__container">
+    <div class="header__brand">
+      <% if config[:tech_docs][:service_link] %>
+        <a href="<%= url_for config[:tech_docs][:service_link] %>">
+      <% else %>
+        <span>
+      <% end %>
+        <% if config[:tech_docs][:show_govuk_logo] %>
+          <span class="govuk-logo">
+            <img class="govuk-logo__printable-crown" src="/images/gov.uk_logotype_crown_invert_trans.png" height="32" width="36" alt="">
+            GOV.UK
+          </span>
+        <% end %>
+        <span class="header__title">
+          <%= config[:tech_docs][:service_name] %>
+          <% if config[:tech_docs][:phase] %>
+            <span class="phase-banner"><%= config[:tech_docs][:phase] %></span>
+          <% end %>
+        </span>
+      <% if config[:tech_docs][:service_link] %>
+        </a>
+      <% else %>
+        </span>
+      <% end %>
+    </div>
+
+    <% if config[:tech_docs][:header_links] %>
+      <div data-module="navigation">
+        <button type="button" class="header__navigation-toggle js-nav-toggle" aria-controls="navigation" aria-label="Show or hide top level navigation">Menu</button>
+
+        <nav id="navigation" class="header__navigation js-nav" aria-label="Top Level Navigation" aria-hidden="true">
+          <ul>
+            <% config[:tech_docs][:header_links].each do |title, path| %>
+              <li<% if active_page(path) %> class="active"<% end %>>
+                <a href="<%= url_for path %>"><%= title %></a>
+              </li>
+            <% end %>
+          </ul>
+        </nav>
+      </div>
+    <% end %>
+  </div>
+</header>