intranet-pandoc 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24560ea4df2f1a415458f86f96fa27895ab40d3379644ece2a7a0899555b7581
-  data.tar.gz: 852e88cd84850b7c5d87c5adb36859da31aaa201cdc149763ba7b2703818281c
+  metadata.gz: 2e9ba0d93e05f580d6620fe156202f62fe7a5ed1c4c8f86ecc412204beccff24
+  data.tar.gz: dee2cfa108cfd44b4442909185c8c613d277c5ba8115059218b2fb8e2e5ba55b
 SHA512:
-  metadata.gz: 7b37d13b54a0cb20801f3722249d51dbc07f7adeb341ef0271164b32c24531c404c835ad4040b4397ff06f6e2ce6f2ca2ccc249747b2b9ac677b7282e0406ae7
-  data.tar.gz: dc1bbbee393733e9e53fba1bf6973742d00884941aed8c153a25e53c54e3e9c3997170311c90deaac69967615773011ea4c92540672cbe17a8be4a871cc51833
+  metadata.gz: 97a49825a5b70100d6243910bb473cf24ad4e3aae58acc95a5deadf3b13125daf8d0e1579b89c9fb6bb287cd44203ff86600d39d56f774797845657c1f3e769a
+  data.tar.gz: 661e974bb3aaf1607fee00cc193b8e53ef454965bcbb4bc88362d03c7da5adab00422a39a448d7c20c59c7cf7d6c5ac8c2a1364b898ae341cc1d7a9c2b88104e

data/lib/intranet/pandoc/responder.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'intranet/abstract_responder'
+require 'intranet/core/haml_wrapper'
+require 'mimemagic'
+require 'pandoc-ruby'
+require_relative 'version'
+
+module Intranet
+  module Pandoc
+    # The responder for the Pandoc module of the Intranet.
+    class Responder < AbstractResponder
+      include Core::HamlWrapper # 'inherits' from methods of HamlWrapper
+
+      # Returns the name of the module.
+      # @return [String] The name of the module.
+      def self.module_name
+        NAME
+      end
+
+      # The version of the module, according to semantic versionning.
+      # @return [String] The version of the module.
+      def self.module_version
+        VERSION
+      end
+
+      # The homepage of the module.
+      # @return [String] The homepage URL of the module.
+      def self.module_homepage
+        HOMEPAGE_URL
+      end
+
+      # Initializes a new Pandoc responder instance.
+      # @param title [String] The title of the module instance.
+      # @param rootdir [String] The root directory of the module instance.
+      # @param in_menu [Boolean] Whether the module instance should be displayed in the main
+      #                          navigation menu or not.
+      def initialize(logger, title, rootdir, template = nil, in_menu = true)
+        @logger   = logger
+        @title    = title
+        @rootdir  = rootdir
+        @template = template
+        @in_menu  = in_menu
+      end
+
+      # Specifies if the responder instance should be displayed in the main navigation menu or not.
+      # @return [Boolean] True if the responder instance should be added to the main navigation
+      #                   menu, False otherwise.
+      def in_menu?
+        @in_menu
+      end
+
+      # Specifies the absolute path to the resources directory for that module.
+      # @return [String] The absolute path to the resources directory for the module.
+      def resources_dir
+        File.absolute_path(File.join('..', 'resources'), __dir__)
+      end
+
+      # Generates the HTML content associated to the given +path+ and +query+.
+      # @param path [String] The requested URI, relative to that module root URI.
+      # @param query [Hash<String,String>] The URI variable/value pairs, if any.
+      # @return [Integer, String, String] The HTTP return code, the MIME type and the answer body.
+      def generate_page(path, query)
+        case path
+        when %r{^/.+\.html$} then serve_page(path.gsub(%r{^/(.+)\.html$}, '\\1'))
+        when %r{^/.+\.(jpg|png)$} then serve_media(path.gsub(%r{^/(.+)$}, '\\1'))
+        else super(path, query)
+        end
+      end
+
+      # The title of the module instance, as displayed on the web page.
+      # @return [String] The title of the module instance.
+      attr_reader :title
+
+      private
+
+      # Provides the list of required stylesheets.
+      # @return [Array<String>] The list of required stylesheets.
+      def stylesheets
+        ['design/style.css']
+      end
+
+      # Provides the list of required script files.
+      # @return [Array<Hash<Symbol,String>>] The list of required scripts.
+      def scripts
+        []
+      end
+
+      # Provides the list of Lua filters to be passed to Pandoc when converting mardown to HTML.
+      # @return [Array<String>] The list of Lua filters, relative to the .
+      def lua_filters
+        [
+          File.join(resources_dir, 'filters', 'titles-shift-levels.lua'),
+          File.join(resources_dir, 'filters', 'links-open-external-in-new-tab.lua')
+        ]
+      end
+
+      ##########################################################################
+      ###            Servicing of the HTML "display-able" content            ###
+      ##########################################################################
+
+      # Convert a single markdown file to HTML format and returns the markup.
+      # @param path [String] The path to the markdown file, relative to the module root directory
+      #                      and without extension.
+      # @raise [RuntimeError] If pandoc fails for whatever reason.
+      def convert_to_html(path)
+        input   = "\"#{File.join(@rootdir, "#{path}.md")}\""
+        filters = lua_filters.map { |filter| "--lua-filter=\"#{filter}\"" }
+        options = ['--standalone', "--template=\"#{@template}\""] unless @template.to_s.empty?
+        PandocRuby.new([input], filters, options).to_html
+      end
+
+      def serve_page(path)
+        content = "<section>#{convert_to_html(path)}</section>"
+        [206, 'text/html',
+         { content: content, title: @title, stylesheets: stylesheets, scripts: scripts }]
+      rescue RuntimeError => e
+        @logger.debug(e.message.chomp)
+        [404, '', '']
+      end
+
+      ##########################################################################
+      ###                 Servicing of the media (pictures)                  ###
+      ##########################################################################
+
+      def serve_media(path)
+        media_path = File.join(@rootdir, path)
+        [200, MimeMagic.by_path(media_path).type, File.read(media_path)]
+      rescue Errno::ENOENT
+        [404, '', '']
+      end
+    end
+  end
+end

data/lib/intranet/pandoc/version.rb

@@ -8,7 +8,7 @@ module Intranet
     NAME = 'intranet-pandoc'
 
     # The version of the gem, according to semantic versionning.
-    VERSION = '0.0.0'
+    VERSION = '1.0.0'
 
     # The URL of the gem homepage.
     HOMEPAGE_URL = 'https://rubygems.org/gems/intranet-pandoc'

data/lib/intranet/resources/filters/links-open-external-in-new-tab.lua

@@ -0,0 +1,10 @@
+-- Lua filter for Pandoc.
+
+-- Add target="_blank" attribute to all external links.
+function Link(el)
+    if string.match(el.target, '^http') then
+        el.attributes.target = '_blank'
+    end
+    return el
+end
+

data/lib/intranet/resources/filters/titles-shift-levels.lua

@@ -0,0 +1,8 @@
+-- Lua filter for Pandoc.
+
+-- Shift title levels by one (first-level become h2, second-level become h3,
+-- on so forth). This is to leave h1 for the main page title.
+function Header(el)
+    return pandoc.Header(el.level + 1, el.content, el.attr)
+end
+

data/lib/intranet/resources/www/style.css

@@ -0,0 +1,21 @@
+/**
+ * pandoc/style.css
+ * Design for the Pandoc module of the IntraNet.
+ */
+
+figure {
+  max-width: 75%;
+  margin: 3em auto; /* top/bottom sides */
+  text-align: center;
+}
+
+figure > img, p img {
+  max-width: 100%;
+}
+
+/* Mobile devices only */
+@media only screen and (max-width: 600px), only screen and (max-device-width: 600px) {
+  figure {
+    max-width: 85%;
+  }
+}

data/spec/intranet/pandoc/responder_spec.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'intranet/core'
+require 'intranet/logger'
+require 'intranet/abstract_responder'
+require 'intranet/pandoc/responder'
+
+RSpec.describe Intranet::Pandoc::Responder do
+  it 'should inherit from Intranet::AbstractResponder' do
+    expect(described_class.superclass).to eql(Intranet::AbstractResponder)
+  end
+
+  it 'should define its name, version and homepage' do
+    expect { described_class.module_name }.not_to raise_error
+    expect { described_class.module_version }.not_to raise_error
+    expect { described_class.module_homepage }.not_to raise_error
+  end
+
+  before do
+    logger = Intranet::Logger.new(Intranet::Logger::FATAL)
+    @core = Intranet::Core.new(logger)
+
+    testroot = File.absolute_path('testroot', __dir__)
+    @template = File.join(testroot, 'template.html')
+    @responder = described_class.new(logger, 'TITLE', testroot, nil)
+    @core.register_module(
+      @responder, ['pandoc'], File.absolute_path('../../../lib/intranet/resources', __dir__)
+    )
+  end
+
+  describe '#in_menu?' do
+    it 'should return the value provided at initialization' do
+      expect(described_class.new(nil, '', nil, nil, false).in_menu?).to be false
+      expect(described_class.new(nil, '', nil, nil, true).in_menu?).to be true
+    end
+  end
+
+  describe '#resources_dir' do
+    it 'should return the absolute path of the resources directory' do
+      expect(described_class.new(nil, '', nil, false).resources_dir).to eql(
+        File.absolute_path('../../../lib/intranet/resources', __dir__)
+      )
+    end
+  end
+
+  describe '#title' do
+    it 'should return the title of the webpage provided by the module' do
+      expect(@responder.title).to eql('TITLE')
+    end
+  end
+
+  describe '#generate_page' do
+    context 'when asked for an existing HTML page' do
+      it 'should return a partial HTML content generated from the index.md file' do
+        code, mime, content = @responder.generate_page('/index.html', {})
+        expect(code).to eql(206)
+        expect(mime).to eql('text/html')
+        expect(content).to eql(
+          {
+            content: '<section>' \
+                     "<p>This is index.md, the main markdown page.</p>\n" \
+                     "<p>We may use the following text attributes:</p>\n" \
+                     "<ul>\n" \
+                     "<li><em>italic</em></li>\n" \
+                     "<li><strong>bold</strong></li>\n" \
+                     "<li><code>monospace</code></li>\n" \
+                     "</ul>\n" \
+                     "<p>We may produce an horizontal rule:</p>\n" \
+                     "<hr />\n" \
+                     "<p>Two spaces at the end of a line<br />\nproduce a line break.</p>\n" \
+                     "<blockquote>\n" \
+                     "<p>Markdown uses email-style characters for blockquoting.</p>\n" \
+                     "<p>Multiple paragraphs need to be prepended individually.</p>\n" \
+                     "</blockquote>\n" \
+                     '</section>',
+            title: 'TITLE',
+            stylesheets: ['design/style.css'],
+            scripts: []
+          }
+        )
+      end
+
+      it 'should shift titles by one level to correctly fit in intranet page template' do
+        code, mime, content = @responder.generate_page('/filters/test-titles-shift-levels.html', {})
+        expect(code).to eql(206)
+        expect(mime).to eql('text/html')
+        expect(content).to eql(
+          {
+            content: '<section>' \
+                     "<h2 id=\"level-1-heading\">Level-1 Heading</h2>\n" \
+                     "<h3 id=\"level-2-heading\">Level-2 Heading</h3>\n" \
+                     "<h2 id=\"alternative-level-1-heading\">Alternative Level-1 heading</h2>\n" \
+                     "<h3 id=\"alternative-level-2-heading\">Alternative Level-2 heading</h3>\n" \
+                     "<h4 id=\"level-3-heading\">Level-3 heading</h4>\n" \
+                     "<p>Other heading levels are not supported by pandoc markdown.</p>\n" \
+                     '</section>',
+            title: 'TITLE',
+            stylesheets: ['design/style.css'],
+            scripts: []
+          }
+        )
+      end
+
+      it 'should add the _blank attributes to external links' do
+        code, mime, content = @responder.generate_page('/filters/test-links-open-external-in-new-tab.html', {})
+        expect(code).to eql(206)
+        expect(mime).to eql('text/html')
+        expect(content).to eql(
+          {
+            content: '<section>' \
+                     "<p>We use a filter that may produce:</p>\n" \
+                     "<ul>\n" \
+                     "<li><a href=\"index.html\">relative internal links</a></li>\n" \
+                     "<li><a href=\"/index.html\">absolute internal links</a></li>\n" \
+                     "<li><a href=\"http://example.com\" target=\"_blank\">HTTP external links</a></li>\n" \
+                     "<li><a href=\"https://example.com\" target=\"_blank\">HTTPS external links</a></li>\n" \
+                     "</ul>\n" \
+                     '</section>',
+            title: 'TITLE',
+            stylesheets: ['design/style.css'],
+            scripts: []
+          }
+        )
+      end
+
+      it 'should use the specified template, if any, to generate the partial HTML content' do
+        @responder.instance_variable_set(:@template, @template)
+        code, mime, content = @responder.generate_page('/index.html', {})
+        expect(code).to eql(206)
+        expect(mime).to eql('text/html')
+        expect(content).to eql(
+          {
+            content: '<section>' \
+                     "<p>This page was generated using <code>template.html</code>.</p>\n" \
+                     "\n" \
+                     "<p>This is index.md, the main markdown page.</p>\n" \
+                     "<p>We may use the following text attributes:</p>\n" \
+                     "<ul>\n" \
+                     "<li><em>italic</em></li>\n" \
+                     "<li><strong>bold</strong></li>\n" \
+                     "<li><code>monospace</code></li>\n" \
+                     "</ul>\n" \
+                     "<p>We may produce an horizontal rule:</p>\n" \
+                     "<hr />\n" \
+                     "<p>Two spaces at the end of a line<br />\nproduce a line break.</p>\n" \
+                     "<blockquote>\n" \
+                     "<p>Markdown uses email-style characters for blockquoting.</p>\n" \
+                     "<p>Multiple paragraphs need to be prepended individually.</p>\n" \
+                     "</blockquote>\n" \
+                     "\n" \
+                     "<p>End of template</p>\n" \
+                     '</section>',
+            title: 'TITLE',
+            stylesheets: ['design/style.css'],
+            scripts: []
+          }
+        )
+      end
+    end
+
+    context 'when asked for an existing picture' do
+      it 'should return the picture' do
+        # JPG file
+        code, mime, content = @responder.generate_page('/white.jpg', {})
+        expect(code).to eql(200)
+        expect(mime).to eql('image/jpeg')
+        expect(content).to eql(File.read(File.join(__dir__, 'testroot', 'white.jpg')))
+
+        # PNG file
+        code, mime, content = @responder.generate_page('/alpha.png', {})
+        expect(code).to eql(200)
+        expect(mime).to eql('image/png')
+        expect(content).to eql(File.read(File.join(__dir__, 'testroot', 'alpha.png')))
+      end
+    end
+
+    context 'otherwise' do
+      it 'should return an HTTP 404 error' do
+        expect(@responder.generate_page('/filters/index.html', {})).to eql([404, '', ''])
+        expect(@responder.generate_page('index.html', {})).to eql([404, '', ''])
+        expect(@responder.generate_page('/black.jpg', {})).to eql([404, '', ''])
+      end
+    end
+  end
+end

data/spec/intranet/pandoc/testroot/filters/test-links-open-external-in-new-tab.md

@@ -0,0 +1,6 @@
+We use a filter that may produce:
+
+ * [relative internal links](index.html)
+ * [absolute internal links](/index.html)
+ * [HTTP external links](http://example.com)
+ * [HTTPS external links](https://example.com)

data/spec/intranet/pandoc/testroot/filters/test-titles-shift-levels.md

@@ -0,0 +1,13 @@
+Level-1 Heading
+===============
+
+Level-2 Heading
+---------------
+
+# Alternative Level-1 heading
+
+## Alternative Level-2 heading
+
+### Level-3 heading
+
+Other heading levels are not supported by pandoc markdown.

data/spec/intranet/pandoc/testroot/index.md

@@ -0,0 +1,19 @@
+This is index.md, the main markdown page.
+
+We may use the following text attributes:
+
+ * _italic_
+ * **bold**
+ * `monospace`
+
+We may produce an horizontal rule:
+
+---
+
+Two spaces at the end of a line  
+produce a line break.
+
+> Markdown uses email-style
+characters for blockquoting.
+>
+> Multiple paragraphs need to be prepended individually.

data/spec/intranet/pandoc/testroot/template.html

@@ -0,0 +1,5 @@
+<p>This page was generated using <code>template.html</code>.</p>
+
+$body$
+
+<p>End of template</p>

data/spec/spec_helper.rb

@@ -41,13 +41,11 @@ RSpec.configure do |config|
   $LOAD_PATH << File.absolute_path(File.join('..', 'lib'), __dir__)
 
   # Load and start SimpleCov to gather code coverage information
-  unless config.files_to_run.one?
-    require 'simplecov'
-    SimpleCov.start do
-      enable_coverage :branch                   # measure branches coverage
-      primary_coverage :branch
-      minimum_coverage line: 100, branch: 100   # minimal coverage rate to succeed
-      add_filter 'spec'                         # exclude 'spec' folder from coverage
-    end
+  require 'simplecov'
+  SimpleCov.start do
+    enable_coverage :branch                   # measure branches coverage
+    primary_coverage :branch
+    minimum_coverage line: 100, branch: 100   # minimal coverage rate to succeed
+    add_filter 'spec'                         # exclude 'spec' folder from coverage
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: intranet-pandoc
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Ebling Mis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-24 00:00:00.000000000 Z
+date: 2022-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: intranet-core
@@ -19,7 +19,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.4.0
+        version: 2.4.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,41 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.4.0
+        version: 2.4.5
+- !ruby/object:Gem::Dependency
+  name: mimemagic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: pandoc-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -106,7 +140,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/intranet/pandoc/responder.rb
 - lib/intranet/pandoc/version.rb
+- lib/intranet/resources/filters/links-open-external-in-new-tab.lua
+- lib/intranet/resources/filters/titles-shift-levels.lua
+- lib/intranet/resources/www/style.css
+- spec/intranet/pandoc/responder_spec.rb
+- spec/intranet/pandoc/testroot/alpha.png
+- spec/intranet/pandoc/testroot/filters/test-links-open-external-in-new-tab.md
+- spec/intranet/pandoc/testroot/filters/test-titles-shift-levels.md
+- spec/intranet/pandoc/testroot/index.md
+- spec/intranet/pandoc/testroot/template.html
+- spec/intranet/pandoc/testroot/white.jpg
 - spec/spec_helper.rb
 homepage: https://rubygems.org/gems/intranet-pandoc
 licenses: