neo4j-asciidoctor-extensions 0.0.1

data/Rakefile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Dir.glob('tasks/*.rake').each { |file| load file }
+
+task default: %w[lint spec]

data/lib/neo4j_asciidoctor_extensions.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'neo4j_asciidoctor_extensions/course_document_attributes'
+require_relative 'neo4j_asciidoctor_extensions/cypher_syntax_role'
+require_relative 'neo4j_asciidoctor_extensions/document_metadata_generator'
+require_relative 'neo4j_asciidoctor_extensions/inline_highlighter_rouge'
+require_relative 'neo4j_asciidoctor_extensions/revealjs_linear_navigation'
+require_relative 'neo4j_asciidoctor_extensions/revealjs_speaker_notes_aggregator'

data/lib/neo4j_asciidoctor_extensions/course_document_attributes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+require_relative 'course_document_attributes/extension'
+
+Asciidoctor::Extensions.register do
+  postprocessor Neo4j::AsciidoctorExtensions::CourseDocumentAttributesPostProcessor
+end

data/lib/neo4j_asciidoctor_extensions/course_document_attributes/extension.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+module Neo4j
+  # Asciidoctor extensions by Neo4j
+  module AsciidoctorExtensions
+    include Asciidoctor
+
+    # A postprocessor that adds attributes about the course.
+    # /!\ This extension is tightly coupled to the course publishing project and should not be used for other purposes /!\
+    #
+    class CourseDocumentAttributesPostProcessor < Extensions::Postprocessor
+      use_dsl
+
+      # TODO: this slug should be configurable
+      TESTING_SLUG_PREFIX = '_testing_'
+
+      def process(document)
+        if (docdir = document.attr 'docdir')
+          # TODO: this path should be configurable
+          path = File.expand_path('../build/online/asciidoctor-module-descriptor.yml', docdir)
+          if File.exist?(path)
+            require 'yaml'
+            module_descriptor = YAML.load_file(path)
+            if (document_slug = document.attr 'slug') && document.attr('stage') != 'production'
+              document_slug = "#{TESTING_SLUG_PREFIX}#{document_slug}"
+              document.set_attr 'slug', document_slug
+            end
+            set_attributes(document, document_slug, module_descriptor)
+            document.set_attribute 'module-name', module_descriptor['module_name']
+          end
+        end
+        document
+      end
+
+      private
+
+      def set_attributes(document, document_slug, module_descriptor)
+        module_descriptor['pages'].each_with_index do |page, index|
+          document.set_attribute "module-toc-link-#{index}", page['url']
+          document.set_attribute "module-toc-title-#{index}", page['title']
+          page_slug = page['slug']
+          page_slug = "#{TESTING_SLUG_PREFIX}#{page_slug}" unless document.attr('stage') == 'production'
+          document.set_attribute "module-toc-slug-#{index}", page_slug
+          document.set_attribute "module-quiz-#{index}", page['quiz']
+          next unless document_slug == page_slug
+
+          set_next_attributes(document, page)
+          document.set_attribute 'module-quiz', page['quiz']
+          document.set_attribute 'module-certificate', page['certificate']
+        end
+      end
+
+      def set_next_attributes(document, page)
+        return unless page.key?('next')
+
+        next_page_slug = page['next']['slug']
+        next_page_slug = "#{TESTING_SLUG_PREFIX}#{next_page_slug}" unless document.attr('stage') == 'production'
+        document.set_attr 'module-next-slug', next_page_slug, false
+        document.set_attr 'module-next-title', page['next']['title'], false
+      end
+    end
+  end
+end

data/lib/neo4j_asciidoctor_extensions/cypher_syntax_role.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+require_relative 'cypher_syntax_role/extension'
+
+Asciidoctor::Extensions.register do
+  tree_processor Neo4j::AsciidoctorExtensions::CypherSyntaxRoleTreeProcessor
+end

data/lib/neo4j_asciidoctor_extensions/cypher_syntax_role/extension.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+module Neo4j
+  # Asciidoctor extensions by Neo4j
+  module AsciidoctorExtensions
+    include Asciidoctor
+
+    # A tree processor that adds a role on code blocks using "cypher-syntax" as a language.
+    #
+    # Usage:
+    #
+    #   [source,cypher-syntax]
+    #   ----
+    #   ()
+    #   (p)
+    #   (l)
+    #   (n)
+    #   ----
+    #
+    class CypherSyntaxRoleTreeProcessor < Extensions::TreeProcessor
+      use_dsl
+
+      def process(document)
+        document.find_by(context: :listing) { |block| block.attr('language') == 'cypher-syntax' }.each do |block|
+          block.add_role('syntax')
+        end
+        document
+      end
+    end
+  end
+end

data/lib/neo4j_asciidoctor_extensions/document_metadata_generator.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+require_relative 'document_metadata_generator/extension'
+
+Asciidoctor::Extensions.register do
+  postprocessor Neo4j::AsciidoctorExtensions::DocumentMetadataGeneratorPostProcessor
+end

data/lib/neo4j_asciidoctor_extensions/document_metadata_generator/extension.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+module Neo4j
+  # Asciidoctor extensions by Neo4j
+  module AsciidoctorExtensions
+    include Asciidoctor
+
+    # Type of value
+    module ValueType
+      # string
+      STRING = 1
+      # [string]
+      LIST_STRING = 2
+      # [<string,string>]
+      LIST_TUPLES = 3
+    end
+
+    # A postprocess that generates a metadata file (in YAML format) from a list of document attributes.
+    #
+    # Usage:
+    #
+    #   # .file.adoc
+    #   #:document-metadata-attrs-include: author,slug,parent-path,tags*,taxonomies*<>
+    #   #:tags: intro,course
+    #   #:taxonomies: os=linux,programming_language=java,neo4j_version=3-5;3-6
+    #   #:slug: intro-neo4j-4-0
+    #   #:parent_path: /intro
+    #
+    #   # .file.yml
+    #   # ---
+    #   # slug: intro-neo4j-4-0
+    #   # parent_path: /intro
+    #   # author:
+    #   #   name: Michael Hunger
+    #   #   first_name: Michael
+    #   #   last_name: Hunger
+    #   #   email: michael.hunger@neotechnology.com
+    #   # tags:
+    #   #   - intro
+    #   #   - course
+    #   # taxonomies:
+    #   #   - key: os
+    #   #     values:
+    #   #       - linux
+    #   #   - key: programming_language
+    #   #     values:
+    #   #       - java
+    #   #   - key: neo4j_version
+    #   #     values:
+    #   #       - 3-5
+    #   #       - 3-6
+    class DocumentMetadataGeneratorPostProcessor < Extensions::Postprocessor
+      use_dsl
+
+      def process(document, output)
+        if (attrs_include = document.attr 'document-metadata-attrs-include')
+          if (outfile = document.attr 'outfile')
+            require 'yaml'
+            metadata = {}
+            attrs_include = attrs_include
+                            .split(',')
+                            .map(&:strip)
+                            .reject(&:empty?)
+
+            attrs_include.each do |attr_include|
+              value_type = resolve_value_type(attr_include)
+              attr_name = resolve_attr_name(attr_include)
+              if document.attr? attr_name
+                attr_value = resolve_attribute_value(attr_name, document, value_type)
+                metadata[attr_name] = attr_value
+              end
+            end
+            metadata['title'] = document.doctitle
+            write(metadata, outfile)
+          end
+        end
+        output
+      end
+
+      private
+
+      def resolve_value_type(attr_include)
+        if attr_include.end_with? '*'
+          ValueType::LIST_STRING
+        elsif attr_include.end_with? '*&lt;&gt;'
+          ValueType::LIST_TUPLES
+        else
+          ValueType::STRING
+        end
+      end
+
+      def resolve_attr_name(attr_include)
+        attr_include
+          .gsub(/\*$/, '')
+          .gsub(/\*&lt;&gt;$/, '')
+          .gsub('-', '_')
+      end
+
+      def write(metadata, outfile)
+        outputdir = File.dirname(outfile)
+        filename = File.basename(outfile, File.extname(outfile))
+        File.open("#{outputdir}/#{filename}.yml", 'w') { |file| file.write(metadata.to_yaml) }
+      end
+
+      def resolve_attribute_value(attr_name, document, value_type)
+        if attr_name == 'author'
+          author = {}
+          author['name'] = document.attr 'author'
+          author['first_name'] = document.attr 'firstname'
+          author['last_name'] = document.attr 'lastname'
+          author['email'] = document.attr 'email'
+          author
+        elsif value_type == ValueType::LIST_STRING
+          split_values(attr_name, document)
+        elsif value_type == ValueType::LIST_TUPLES
+          split_values(attr_name, document)
+            .map do |tuple|
+            key, value = tuple.split('=')
+            { 'key' => key.strip, 'values' => value.strip.split(';').map(&:strip).reject(&:empty?) }
+          end
+        else
+          document.attr attr_name
+        end
+      end
+
+      def split_values(attr_name, document)
+        (document.attr attr_name)
+          .split(',')
+          .map(&:strip)
+          .reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/neo4j_asciidoctor_extensions/inline_highlighter_rouge.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+require_relative 'inline_highlighter_rouge/extension'
+
+Asciidoctor::Extensions.register do
+  inline_macro Neo4j::AsciidoctorExtensions::InlineHighlighter::MonospacedTextInlineMacro
+  inline_macro Neo4j::AsciidoctorExtensions::InlineHighlighter::SrcInlineMacro
+end

data/lib/neo4j_asciidoctor_extensions/inline_highlighter_rouge/extension.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+require 'rouge'
+
+module Neo4j
+  # Asciidoctor extensions by Neo4j
+  module AsciidoctorExtensions
+    # Inline syntax highlighter based on Rouge.
+    #
+    module InlineHighlighter
+      include Asciidoctor
+
+      def self.highlight_code(lang, text, doc)
+        return '' if text.nil? || text.strip.empty?
+
+        lexer = Rouge::Lexer.find lang
+        theme = Rouge::Theme.find(doc.attr('rouge-style', 'github')).new
+        formatter = Rouge::Formatters::HTMLInline.new(theme)
+        formatter.format(lexer.lex(text))
+      end
+
+      # Apply syntax highlighting on monospaced text cypher:
+      #
+      # Usage:
+      #
+      # # [src-cypher]`MATCH (c:Customer {customerName: 'ABCCO'}) RETURN c.BOUGHT.productName`
+      #
+      class MonospacedTextInlineMacro < Extensions::InlineMacroProcessor
+        use_dsl
+        named :monospaced_highlighter
+        match %r{<code class="src-([a-z]+)">([^<]+)<\/code>}i
+        positional_attributes :content
+
+        def process(parent, target, attrs)
+          raw_text = attrs[:content]
+          raw_text = raw_text.gsub('&#8594;', '->') if raw_text.include? '&'
+          raw_text = raw_text.gsub('&#8592;', '<-') if raw_text.include? '&'
+          highlighted_text = InlineHighlighter.highlight_code(target, raw_text, parent.document)
+          create_inline_pass parent, %(<code class="rouge">#{highlighted_text}</code>), attrs
+        end
+      end
+
+      # Apply syntax highlighting on src inline macro:
+      #
+      # Usage:
+      #
+      # # src:cypher[MATCH (c:Customer {customerName: 'ABCCO'}) RETURN c.BOUGHT.productName]
+      #
+      class SrcInlineMacro < Extensions::InlineMacroProcessor
+        use_dsl
+        named :src
+        positional_attributes :content
+
+        def process(parent, target, attrs)
+          new_text = InlineHighlighter.highlight_code(target, attrs[:content], parent.document)
+          create_inline_pass parent, %(<code class="rouge">#{new_text}</code>), attrs
+        end
+      end
+    end
+  end
+end

data/lib/neo4j_asciidoctor_extensions/revealjs_linear_navigation.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+require_relative 'revealjs_linear_navigation/extension'
+
+Asciidoctor::Extensions.register do
+  tree_processor Neo4j::AsciidoctorExtensions::RevealJsLinearNavigationTreeProcessor
+end

data/lib/neo4j_asciidoctor_extensions/revealjs_linear_navigation/extension.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+module Neo4j
+  # Asciidoctor extensions by Neo4j
+  module AsciidoctorExtensions
+    include Asciidoctor
+
+    # A tree process that "flatten" a reveal.js presentation to use a linear navigation.
+    # By default, the reveal.js converter will use a vertical navigation for the second levels of section titles (and below).
+    # This extension will effectively prevent that by using only first level section titles.
+    #
+    class RevealJsLinearNavigationTreeProcessor < Extensions::TreeProcessor
+      use_dsl
+
+      def process(document)
+        if document.backend == 'revealjs'
+          document.find_by(context: :section) { |section| section.level > 1 }.reverse_each do |section|
+            section.parent.blocks.delete(section)
+            parent_section = section.parent
+            parent_section = parent_section.parent while parent_section.parent && parent_section.parent.context == :section
+            section.level = 1
+            document.blocks.insert(parent_section.index + 1, section)
+          end
+        end
+        document
+      end
+    end
+  end
+end

data/lib/neo4j_asciidoctor_extensions/revealjs_speaker_notes_aggregator.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+require_relative 'revealjs_speaker_notes_aggregator/extension'
+
+Asciidoctor::Extensions.register do
+  tree_processor Neo4j::AsciidoctorExtensions::RevealJsSpeakerNotesAggregatorTreeProcessor
+end

data/lib/neo4j_asciidoctor_extensions/revealjs_speaker_notes_aggregator/extension.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+module Neo4j
+  # Asciidoctor extensions by Neo4j
+  module AsciidoctorExtensions
+    include Asciidoctor
+
+    # A tree processor that aggregates multiple [notes] blocks in a section (slide).
+    #
+    # Usage:
+    #
+    #   == Introduction
+    #
+    #   [.notes]
+    #   --
+    #   This is a speaker note.
+    #   --
+    #
+    #   Hello!
+    #
+    #   [.notes]
+    #   --
+    #   This is another speaker note.
+    #   --
+    #
+    class RevealJsSpeakerNotesAggregatorTreeProcessor < Extensions::TreeProcessor
+      use_dsl
+
+      def process(document)
+        if document.backend == 'revealjs'
+          document.find_by(context: :section).each do |section|
+            notes_blocks = section.blocks.select { |block| block.context == :open && block.roles.include?('notes') }
+            next if notes_blocks.empty?
+
+            agg_notes_block = Asciidoctor::Block.new(section, :open, attributes: { 'role' => 'notes' })
+            notes_blocks.each do |notes_block|
+              section.blocks.delete(notes_block)
+              notes_block.remove_role('notes')
+              agg_notes_block << notes_block
+            end
+            section.blocks << agg_notes_block
+          end
+        end
+        document
+      end
+    end
+  end
+end