fni-docs-theme 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73f7f3cdfe0e0a45ceff74d8ce905dbf3bd180954695c6ba242e6934ccc3fd09
-  data.tar.gz: 132b77f2dea994a3f57619453d6be90ec988c105f6fafe3196732bdb6642ac93
+  metadata.gz: 5ba5439ab23c84eab01b03238c30f867e62e58e1c6252790cb1197baf24c10c9
+  data.tar.gz: 2aec63e1e343635dfbc12184fc64d72c7fe6128026a7df5cc9c3679b2591df77
 SHA512:
-  metadata.gz: 130d9973522f41f23519a097b805dbe4d73e5e9ea99c1beef02423bb8fe0f1d62c5668ded928c6bb0ed57a7c0973d03cd6bd6fff361184c7e9fd9a9f891e2d8e
-  data.tar.gz: 6879c3c326b204fe8e4737c04a5b6f6982467fcd774407d082d64c4162d4f5529c721f6a252e28598b1e1a13013de4179c4ccb40a6818013d0afdbe08a1c21c0
+  metadata.gz: 1ec084330a227096c77e00f8fa9acbc985b0e60402dffa61e7d4d414d73203300fe29919518a3cf038a74456620623e2d3baff8b8b386d89e2c04ee95b3a0aeb
+  data.tar.gz: 9d12d80caacf6bb2f981d8f8629807d1187bdf2d01cb720eb68788b39f34a3d977d673de737e3996968b61183275d9ee28cbcc5e10468263af236d407c968e44

data/README.md

@@ -2,18 +2,37 @@
 
 Forked from [just-the-docs](https://pmarsceill.github.io/just-the-docs/)
 
+Pertinent differences:
+* Nav generation has been moved to a plugin, lib/generators/nav-generator. This ensures the nav is only generated once and can be included 
+
 ## Installation
 
-Add this line to your Jekyll site's `_config.yml`:
+This theme is distributed as a Jekyll plugin, to install:
+
+* Add the plugin to your gemfile (recommend pinning a specific version):
+```ruby
+group :jekyll_plugins do
+  gem "fni-docs-theme", "0.4.2"
+end
+```
+
+Add these lines to your Jekyll site's `_config.yml`:
 
 ```yaml
-remote_theme: dealertrack/fni-docs-theme
+theme: fni-docs-theme
+
+plugins:
+  - fni-docs-theme
 ```
 
 ## Usage
 
 [View the documentation](https://pmarsceill.github.io/just-the-docs/) for usage information.
 
+## Publishing
+
+This theme/plugin is published as fni-docs-theme to rubygems.org.
+
 ## License
 
 The theme is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/_includes/head.html

@@ -29,8 +29,14 @@
   {% if site.search_enabled != false %}
     <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
   {% endif %}
+
+  <script src="https://cdn.jsdelivr.net/npm/plantuml-encoder@1.4.0/dist/plantuml-encoder.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/svg-pan-zoom@3.6.1/dist/svg-pan-zoom.min.js"></script>  
+
   <script type="text/javascript" src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
   <script type="text/javascript" src="{{ '/assets/js/jtd-nav.js' | relative_url }}"></script>
+  <script type="text/javascript" src="{{ '/assets/js/links.js' | relative_url }}"></script>
+  <script type="text/javascript" src="{{ '/assets/js/plantuml.js' | relative_url }}"></script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1">
 

data/_includes/iuml.html

@@ -0,0 +1,5 @@
+<div class="plantuml-diagram" data-diagram-src="{{ include.diagram }}"
+     data-diagram-width="{{ include.width }}" data-diagram-height="{{ include.height }}">
+  <div class="plantuml-diagram-open"></div>
+  <div class="plantuml-diagram-inner"></div>
+</div>

data/_sass/modules.scss

@@ -18,3 +18,4 @@
 @import "./code";
 @import "./utilities/utilities";
 @import "./print";
+@import "./plantuml";

data/_sass/plantuml.scss

@@ -0,0 +1,25 @@
+
+// Style iuml diagrams
+.plantuml-diagram {
+  position: relative;
+  color: #333;
+
+  svg {
+      border: 2px solid #444;
+  }
+
+  .error-msg {
+      margin: 1em;
+      padding: 0.5em;
+      background-color: #fdd;
+      border: 1px solid #922;
+  }
+
+  .plantuml-diagram-open {
+      position: absolute;
+      right: 5px;
+      bottom: 8px;
+      font-size: smaller;
+  }
+}
+  

data/assets/js/links.js

@@ -0,0 +1,22 @@
+
+window.jtd.onReady(() => {
+  externalLinks()
+})
+
+// Find all anchor links on the page that reference external pages or static files and open them in a new tab
+function externalLinks() {
+  const newTabExtensions = ['.pdf', '.png', '.svg']
+  const links = document.getElementsByTagName('a')
+  for (const link of links) {
+    const href = link.getAttribute('href')
+    if (href && link.hostname !== location.hostname) {
+      link.target = "_blank";
+      link.rel = "noopener";
+    } else if (href && newTabExtensions.some(ext => href.indexOf(ext) > 0)) {
+      link.onclick = function () {
+        window.open(this.href)
+        return false
+      }
+    }
+  }
+}

data/assets/js/plantuml.js

@@ -0,0 +1,95 @@
+
+window.jtd.onReady(() => {
+  initDiags()
+})
+
+async function initDiags() {
+  const defaultWidth = 736
+  const defaultHeight = 400
+
+  const curPath = window.location.pathname
+  const diags = document.getElementsByClassName('plantuml-diagram')
+
+  for (const diag of diags) {
+    const src = diag.dataset.diagramSrc
+    const svgSrc = src.replace('.iuml', '.svg')
+    const diagCont = diag.getElementsByClassName('plantuml-diagram-inner')[0]
+    const viewCont = diag.getElementsByClassName('plantuml-diagram-open')[0]
+    const width = diag.dataset.diagramWidth || defaultWidth
+    const height = diag.dataset.diagramHeight || defaultHeight
+
+    // Fetch the svg
+    const svgRes = await fetch(curPath + svgSrc)
+    if (!svgRes.ok) {
+      diagCont.innerHTML = '<div class="error-msg">Failed to retrieve diagram</div>'
+      continue
+    }
+
+    // Add an open button
+    viewCont.innerHTML = `<a href="${svgSrc}" target="_blank" rel="noopener">open</a>`
+
+    const svg = await svgRes.text()
+
+    diagCont.innerHTML = svg
+    const svgElement = diag.getElementsByTagName('svg')[0]
+
+    svgElement.style.width = width
+    svgElement.style.height = height
+    svgElement.style.backgroundColor = '#333'
+
+    const spz = svgPanZoom(svgElement, {
+      zoomEnabled: true,
+      controlIconsEnabled: false,
+      fit: true,
+      center: true,
+      dblClickZoomEnabled: false,
+      customEventsHandler: {
+        init: options => {
+          // Double click to toggle fullscreen
+          options.svgElement.addEventListener('dblclick', () => {
+            if (options.svgElement.style.position === 'fixed') {
+              options.svgElement.style.position = null
+              options.svgElement.style.left = null
+              options.svgElement.style.top = null
+              options.svgElement.style.zIndex = null
+              options.svgElement.style.width = width
+              options.svgElement.style.height = height
+            } else {
+              options.svgElement.style.position = 'fixed'
+              options.svgElement.style.left = '20px'
+              options.svgElement.style.top = '20px'
+              options.svgElement.style.zIndex = '9999'
+              options.svgElement.style.width = getWidth() - 40
+              options.svgElement.style.height = getHeight() - 40
+            }
+
+            options.instance.updateBBox()
+            options.instance.resize()
+            options.instance.fit()
+            options.instance.center()
+          })
+        }
+      }
+    })
+  }
+}
+
+function getWidth() {
+  return Math.max(
+    document.body.scrollWidth,
+    document.documentElement.scrollWidth,
+    document.body.offsetWidth,
+    document.documentElement.offsetWidth,
+    document.documentElement.clientWidth
+  );
+}
+
+function getHeight() {
+  return Math.max(
+    document.body.scrollHeight,
+    document.documentElement.scrollHeight,
+    document.body.offsetHeight,
+    document.documentElement.offsetHeight,
+    document.documentElement.clientHeight
+  );
+}

data/lib/converters/plantuml-converter.rb

@@ -0,0 +1,98 @@
+require 'uri'
+require 'net/http'
+require 'digest'
+
+module PlantUmlConverterPlugin
+  # Whitelists *.iuml documents for conversion despite them lacking front matter
+  class PlantUmlGenerator < Jekyll::Generator
+    attr_accessor :site
+    safe true
+    priority :low
+
+    @plantuml_converter
+
+    def initialize(site)
+      @plantuml_converter = PlantUmlConverter.new()
+    end
+
+    def generate(site)
+      diagrams = site.static_files.select { |file| @plantuml_converter.matches(static_file_ext(file)) }
+      site.pages.concat(diagrams.map { |diag| page_from_static_file(site, diag) })
+      site.static_files -= diagrams
+    end
+
+    def static_file_ext(static_file)
+      static_file.extname
+    end
+
+    # Given a Jekyll::StaticFile, returns the file as a Jekyll::Page
+    def page_from_static_file(site, static_file)
+      base = static_file.instance_variable_get("@base")
+      dir  = static_file.instance_variable_get("@dir")
+      name = static_file.instance_variable_get("@name")
+      Jekyll::Page.new(site, base, dir, name)
+    end
+  end
+
+  class PlantUmlConverter < Jekyll::Converter
+    safe true
+    priority :low
+
+    @config = {}
+
+    def matches(ext)
+      ext =~ /^\.iuml$/i
+    end
+
+    def output_ext(ext)
+      '.svg'
+    end
+
+    def initialize(config = {})
+      @config = config['plantuml']
+    end
+
+    def convert(content)
+      dest_uri = URI("#{@config['server_uri']}/svg/")
+      
+      begin
+        iuml = filter_iuml(content)
+        svg_res = Net::HTTP.post(dest_uri, iuml, 'Content-Type' => 'text/plain')
+
+        unless (svg_res.kind_of? Net::HTTPSuccess)
+          diag_name = content.lines.first.sub('@startuml ','').sub("\n", '')
+          error_msg = svg_res['X-PlantUML-Diagram-Error']
+          error_line = svg_res['X-PlantUML-Diagram-Error-Line']
+          Jekyll.logger.error "Failed to render .iuml [#{diag_name}]: #{error_msg} at line #{error_line}"
+          return ''
+        end
+
+        svg_res.body
+      rescue => err
+        diag_name = content.lines.first.sub('@startuml ','').sub("\n", '')
+        Jekyll.logger.error "Failed to convert IUML document: #{diag_name} - #{err.message}"
+        return ''
+      end
+    end
+
+    # Clean up markup as needed (matches)
+    #    Add "!theme spacelab" if no theme present and set background color
+    #    Add an @enduml that only seems to be needed for server rendering
+    def filter_iuml(iuml)
+      iuml_arr = iuml.split("\n")
+      unless (iuml.include? '!theme')
+        iuml_arr = iuml_arr.insert(1, '!theme spacelab')
+      end
+      unless (iuml.include? 'skinparam backgroundColor')
+        iuml_arr = iuml_arr.insert(2, 'skinparam backgroundColor #333')
+      end
+      unless (iuml.include? '@enduml')
+        iuml_arr = iuml_arr.push("@enduml")
+      end
+      iuml_arr.join("\n")
+    end
+  end
+
+  # TODO: Could also define a custom plantuml liquid block instead of the include, would still need to inject scripts into <head>
+  #   ref https://github.com/yegor256/jekyll-plantuml/blob/master/lib/jekyll-plantuml.rb
+end

data/lib/fni-docs-theme.rb

@@ -1 +1,2 @@
 require "generators/nav-generator"
+require "converters/plantuml-converter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fni-docs-theme
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors:
 - Patrick Marsceill
@@ -120,6 +120,7 @@ files:
 - _includes/head.html
 - _includes/head_custom.html
 - _includes/header_custom.html
+- _includes/iuml.html
 - _includes/js/custom.js
 - _includes/nav.html
 - _includes/title.html
@@ -142,6 +143,7 @@ files:
 - _sass/layout.scss
 - _sass/modules.scss
 - _sass/navigation.scss
+- _sass/plantuml.scss
 - _sass/print.scss
 - _sass/search.scss
 - _sass/support/_functions.scss
@@ -168,9 +170,12 @@ files:
 - assets/images/search.svg
 - assets/js/jtd-nav.js
 - assets/js/just-the-docs.js
+- assets/js/links.js
+- assets/js/plantuml.js
 - assets/js/vendor/lunr.min.js
 - assets/js/zzzz-search-data.json
 - bin/just-the-docs
+- lib/converters/plantuml-converter.rb
 - lib/fni-docs-theme.rb
 - lib/generators/nav-generator.rb
 - lib/tasks/search.rake