Introduce Topics and bidirectional links between pages

Gemfile

@@ -20,3 +20,5 @@ gem 'color_pound_spec_reporter'
 
 # HTTP bindings to libcurl - https://github.com/taf2/curb
 gem 'curb'
+
+gem "nokogiri", "~> 1.13.10"

Gemfile.lock

@@ -55,15 +55,20 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.3.6)
+    mini_portile2 (2.8.1)
     minitest (5.14.2)
     minitest-reporters (1.4.2)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
+    nokogiri (1.13.10)
+      mini_portile2 (~> 2.8.0)
+      racc (~> 1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (5.0.0)
+    racc (1.6.2)
     rake (13.0.1)
     rb-fsevent (0.10.4)
     rb-inotify (0.10.1)
@@ -92,7 +97,8 @@ DEPENDENCIES
   kramdown-parser-gfm
   minitest
   minitest-reporters
+  nokogiri (~> 1.13.10)
   rake
 
 BUNDLED WITH
-   2.1.4
+   2.3.26

Rakefile

@@ -81,7 +81,7 @@ desc 'Create a new post file'
 namespace :posts do
   task :new do
     # Fetch user command line args. Exit if required args are missing.
-    pr, host, date = get_cli_options
+    pr, host, date = get_cli_options_posts
     handle_missing_required_arg('pr') unless pr
     handle_missing_required_arg('host') unless host
 
@@ -120,7 +120,7 @@ namespace :posts do
   end
 end
 
-def get_cli_options(options = {})
+def get_cli_options_posts(options = {})
   OptionParser.new do |opts|
     opts.banner = 'Usage: rake posts:new -- <options>'
     opts.on('-p', '--pr NUMBER', 'Pull request number (required)') do
@@ -143,8 +143,57 @@ def get_cli_options(options = {})
   [options[:pr], options[:host], options[:date]]
 end
 
-def handle_missing_required_arg(name)
-  puts "Error: Missing required --#{name} argument. Run `rake posts:new -- --help` for info."
+# To see the rake topics:new help, run:
+#   rake topics:new -- -H
+#
+desc 'Create a new topics file'
+namespace :topics do
+  task :new do
+    # Fetch user command line args. Exit if required args are missing.
+    title, slug = get_cli_options_topics
+
+    handle_missing_required_arg('title', 'topics') unless title
+
+    # Slugify title if slug not supplied by user.
+    unless slug
+      slug = title.downcase.strip.gsub(' ', '-').gsub(/[^\w-]/, '')
+      puts "Topic '#{title}' has been slugified and filename set to : #{slug}"
+    end
+    # Create a new topic file if none exists, otherwise exit.
+    filename = "#{'_topics/' if File.directory?('_topics')}#{slug}.md"
+
+    if File.file?(filename)
+      puts "Filename #{filename} already exists. Nothing done, exiting."
+    else
+      create_topic_file!(filename, title)
+      puts "New file #{filename} created successfully."
+    end
+    exit
+  end
+end
+
+def get_cli_options_topics(options = {})
+  OptionParser.new do |opts|
+    opts.banner = 'Usage: rake topics:new -- <options>'
+    opts.on('-t', '--title TOPIC_LONG', 'Long name for topic (required)') do
+      |title| options[:title] = title
+    end
+    opts.on('-s', '--slug TOPIC_SHORT',
+            'Short name for topic (optional, defaults to slugified title)') do
+      |slug| options[:slug] = slug
+    end
+    opts.on('-H', '--help', 'Display this help') do
+      puts opts
+      exit
+    end
+    args = opts.order!(ARGV) {}
+    opts.parse!(args)
+  end
+  [options[:title], options[:slug]]
+end
+
+def handle_missing_required_arg(name, rake = "posts")
+  puts "Error: Missing required --#{name} argument. Run `rake #{rake}:new -- --help` for info."
   exit
 end
 
@@ -225,6 +274,24 @@ def create_post_file!(filename, response, date, host)
   end
 end
 
+def create_topic_file!(filename, title)
+  def comment_out(line, header)
+    line.puts "<!-- uncomment to add"
+    line.puts "## #{header}"
+    line.puts "-->"
+  end
+
+  File.open(filename, 'w') do |line|
+    line.puts '---'
+    line.puts 'layout: topic'
+    line.puts "title: #{title}"
+    line.puts "---\n\n"
+    comment_out(line, "Notes")
+    comment_out(line, "History")
+    comment_out(line, "Resources")
+  end
+end
+
 def parse_title(title)
   first, *rest = title.split # e.g. if title = "a b c", first = "a", rest = ["b", "c"]
   first.downcase! # mutate first word to lowercase in place

_config.yml

@@ -32,6 +32,11 @@ exclude:
    - Rakefile
    - test/
 
+collections:
+  topics:
+    output: true
+    permalink: /topics/:slug
+
 defaults:
   - scope:
       path: ""  ## all pages

_data/settings.yml

@@ -6,5 +6,6 @@ author:
 menu:
 - {name: 'Home', url: ''}
 - {name: 'Meetings', url: 'meetings/'}
+- {name: 'Topics', url: 'topics/'}
 - {name: 'Code of Conduct', url: 'code-of-conduct/'}
 - {name: 'Hosting', url: 'hosting/'}

_includes/backlinks.html

@@ -0,0 +1,20 @@
+<side style="font-size: 0.9em">
+  {% if page.backlinks.size > 0 %}
+    <h3 style="margin-bottom: 1em; color: #828282">{{ page.backlinks.size }} Linked pages</h3>
+    <div style="display: grid; grid-gap: 1em; grid-template-columns: repeat(1fr);">
+      {% for backlink in page.backlinks %}
+        <div >
+          <a class="internal-link" style="font-size: 1.2em" href="{{ backlink.doc.url }}">{%- if backlink.doc.pr -%}#{{ backlink.doc.pr }}&nbsp;{%- endif -%}{{ backlink.doc.title }}</a><br>
+          <div style="margin-top: 0.3em; display: grid; grid-gap: 0.7em; grid-template-columns: repeat(1fr);">
+          {% for snippet in backlink.snippets %}
+            <div class="backlink-box">
+              <div class="backlink-header">{{ snippet.header }}</div>
+              {{ snippet.paragraph | link_to_anchor: backlink.doc.url | markdownify }}
+            </div>
+          {% endfor %}
+          </div>
+        </div>
+      {% endfor %}
+    </div>
+  {% endif %}
+</side>

_layouts/pr.html

@@ -65,5 +65,6 @@ <h1>{{ page.title }} ({{components}})</h1>
     <p>
       {{ content }}
     </p>
+    {% include backlinks.html %}
   </div>
 </section>

_layouts/topic.html

@@ -0,0 +1,22 @@
+---
+layout: default
+---
+
+<section>
+    <div class="post-content">
+      {% if page.code %}
+        <h1><code>{{ page.title }}</code></h1>
+      {% else %}
+        <h1>{{ page.title }}</h1>
+      {% endif %}
+
+      <time class="dt-published" datetime="{{ page.last-modified-date | date_to_xmlschema }}">
+        Last updated: {{ page.last-modified-date | date: '%B %d, %Y' }}
+      </time>
+
+      <p>
+        {{ content }}
+      </p>
+      {% include backlinks.html %}
+    </div>
+</section>

_plugins/auto-anchor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# This file is based on code from https://github.com/bitcoinops/bitcoinops.github.io
+
+# Automatically adds id tags (anchors) to list items
+
+require 'digest/md5'
+
+def generate_slug(text)
+  # Remove double-quotes from titles before attempting to slugify
+  text.gsub!('"', '')
+  # Remove whitespace character from the end and use Liquid/Jekyll slugify filter
+  slug_text = "{{ \"#{text.rstrip}\" | slugify: 'latin' }}"
+  # use the digest library to create deterministic ids based on text
+  id = Digest::MD5.hexdigest(slug_text)[0...7]
+  slug = "\#b#{id}" # prefix with 'b', ids cannot start with a number
+  slug
+end
+
+def generate_anchor_list_link(anchor_link, class_name='anchor-list-link')
+  # custom clickable bullet linking to an anchor
+  "<a href=\"#{anchor_link}\" class=\"#{class_name}\">●</a>"
+end
+
+def auto_anchor(content)
+  # finds “bulleted” list items that start with hyphen (-) or asterisk (*)
+  # adds anchor and clickable bullet
+  content.gsub!(/^ *[\*-] .*?(?:\n\n|\z)/m) do |bulleted_paragraph|
+    slug = generate_slug(bulleted_paragraph)
+    bullet_character = bulleted_paragraph.match(/^ *([\*-])/)[1] # bullet can be '-' or '*'
+    id_prefix = "#{bullet_character} {:#{slug} .anchor-list} #{generate_anchor_list_link(slug)}"
+    bulleted_paragraph.sub!(/#{Regexp.quote(bullet_character)}/, id_prefix)
+  end
+  # finds “numbered” list items that start with number (1.)
+  # adds anchor only
+  content.gsub!(/^ *\d+\. .*?(?:\n\n|\z)/m) do |numbered_paragraph|
+    slug = generate_slug(numbered_paragraph)
+    id_prefix = "1. {:#{slug} .anchor-list .anchor-numbered}"
+    numbered_paragraph.sub!(/\d+\./, id_prefix)
+  end
+end
+
+## Run automatically on all documents
+Jekyll::Hooks.register :documents, :pre_render do |post|
+  ## Don't process documents if YAML headers say: "auto_id: false"
+  unless post.data["auto_id"] == false
+    auto_anchor(post.content)
+  end
+end
+
+module TextFilter
+  # This is a custom filter used in backlinks.html to 
+  # add anchor links to each backlink snippet
+  def link_to_anchor(text, url)
+    slug = generate_slug(text)
+    id_prefix = generate_anchor_list_link("#{url}#{slug}", "backlink-link")
+    text.sub!(/(?:-|\*|\d+\.)/, id_prefix) # this targets both “bulleted” and “numbered” list items
+    text
+  end
+end
+
+Liquid::Template.register_filter(TextFilter)