notion_to_md 2.2.4 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fb7426b97e6a8fdd9cd27cd1254939c5ccd3cb3455920ff35071d5c3429a4f1
-  data.tar.gz: 523b5ff29517de54208a7506970115f11d087c9bb314e4b0a626650760ec89f3
+  metadata.gz: 26fb275bacfb3f94bc62bf1f15de2de6636f043a2a7d11b66ecba0f5df2a39ec
+  data.tar.gz: 53308f1bc92d17a1125969e030f6a070cc82384808b34787f6ed0c853fdbaca9
 SHA512:
-  metadata.gz: f9f181ba6bdbece59d9f8f5ad81c05afe86e942fcca913674ca42f04876a158091e8dc21b4eb392d9226c8839a8eea021c223a9d40c681093c9a16f153ec9793
-  data.tar.gz: 4999b3781d9bf53357f8e5f8585beef8c4c3b501c6b35d360f2593b8596ae5b615979bb20246b2aee911342f5d97824a0c1da882c8d54a544fc14c1e0e61dbb1
+  metadata.gz: b0522c546ae98279d0a20aff3a8bf5d225dc74eea6c5504a0f35bdf6bb692e870c6719ea088251556fb49ad3318031f200754ac2691254fa3d0d4287035e4045
+  data.tar.gz: 2430ca47d1fe39e9f73cc9aad187d6457440edb94cd60dea9d1d82d562a057339acdef9c85ac8b1db79d34acd9db754493a62876643deab50af310472e125b06

data/README.md

@@ -25,6 +25,14 @@ notion_converter = NotionToMd::Converter.new(page_id: 'b91d5...', token: 'secret
 md = notion_converter.convert
 ```
 
+Since v2.3 you can also use the convenient `convert` method from the root module.
+
+```ruby
+require 'notion_to_md'
+
+md = NotionToMd.convert(page_id: 'b91d5...', token: 'secret_...')
+```
+
 If the secret token is provided as an environment variable —`NOTION_TOKEN`—, there's no need to pass it as an argument to the constructor.
 
 ```bash
@@ -36,6 +44,8 @@ require 'notion_to_md'
 
 notion_converter = NotionToMd::Converter.new(page_id: 'b91d5...')
 md = notion_converter.convert
+# or
+md = NotionToMd.convert(page_id: 'b91d5...')
 ```
 
 And that's all. The `md` is a string variable containing the notion page formatted in markdown.
@@ -49,7 +59,7 @@ Everything in a notion page body is a [block object](https://developers.notion.c
 * `heading_2`
 * `heading_3`
 * `bulleted_list_item`
-* `numbered_list_item` as `bulleted_list_item`
+* `numbered_list_item` (supported since v2.3, in previous versions is displayed as `bulleted_list_item`)
 * `to_do`
 * `image`
 * `bookmark`
@@ -77,6 +87,8 @@ By default, the front matter section is not included to the document. To do so,
 
 ```ruby
 NotionToMd::Converter.new(page_id: 'b91d5...').convert(frontmatter: tue)
+# or
+NotionToMd.convert(page_id: 'b91d5...', frontmatter: true) # Since v2.3
 ```
 
 Default notion [properties](https://developers.notion.com/reference/page#all-pages) are page `id`, `title`, `created_time`, `last_edited_time`, `icon`, `archived` and `cover`.

data/lib/notion_to_md/blocks/block.rb

@@ -9,6 +9,8 @@ module NotionToMd
 
       attr_reader :block, :children
 
+      def_delegators :block, :type
+
       # === Parameters:
       # block::
       #   A {Notion::Messages::Message}[https://github.com/orbit-love/notion-ruby-client/blob/main/lib/notion/messages/message.rb] object.
@@ -32,14 +34,18 @@ module NotionToMd
       #
       def to_md(tab_width: 0)
         block_type = block.type.to_sym
-        md = Types.send(block_type, block[block_type])
+        md = Types.send(block_type, block[block_type]) + newline
         md + build_nested_blocks(tab_width + 1)
       rescue NoMethodError
         Logger.info("Unsupported block type: #{block_type}")
         nil
       end
 
-      private
+      protected
+
+      def newline
+        "\n\n"
+      end
 
       def build_nested_blocks(tab_width)
         mds = markdownify_children(tab_width).compact
@@ -54,7 +60,7 @@ module NotionToMd
 
       def indent_children(mds, tab_width)
         mds.map do |md|
-          "\n\n#{"\t" * tab_width}#{md}"
+          "#{"\t" * tab_width}#{md}"
         end
       end
     end

data/lib/notion_to_md/blocks/builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module NotionToMd
+  module Blocks
+    class Builder
+      ##
+      # Array containing the block types allowed to have nested blocks (children).
+      BLOCKS_WITH_PERMITTED_CHILDREN = %i[
+        bulleted_list_item
+        numbered_list_item
+        paragraph
+        to_do
+        table
+      ].freeze
+
+      # === Parameters
+      # block::
+      #   A {Notion::Messages::Message}[https://github.com/orbit-love/notion-ruby-client/blob/main/lib/notion/messages/message.rb] object.
+      #
+      # === Returns
+      # A boolean indicating if the blocked passed in
+      # is permitted to have children based on its type.
+      #
+      def self.permitted_children_for?(block:)
+        BLOCKS_WITH_PERMITTED_CHILDREN.include?(block.type.to_sym) && block.has_children
+      end
+
+      attr_reader :block_id, :fetch_blocks
+
+      # === Parameters
+      # block_id::
+      #   A string representing a notion block id .
+      # fetch_blocks::
+      #   A block that fetches the blocks from the Notion API.
+      #
+      # === Returns
+      # An array of NotionToMd::Blocks::Block.
+      #
+      def initialize(block_id:, &fetch_blocks)
+        @block_id = block_id
+        @fetch_blocks = fetch_blocks
+      end
+
+      # === Parameters
+      #
+      # === Returns
+      # An array of NotionToMd::Blocks::Block.
+      #
+      def build
+        notion_messages = fetch_blocks.call(block_id)
+        blocks = notion_messages.results.map do |block|
+          children = if Builder.permitted_children_for?(block: block)
+                       Builder.new(block_id: block.id, &fetch_blocks).build
+                     else
+                       []
+                     end
+          Factory.build(block: block, children: children)
+        end
+
+        Normalizer.normalize(blocks: blocks)
+      end
+    end
+  end
+end

data/lib/notion_to_md/blocks/bulleted_list_block.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module NotionToMd
+  module Blocks
+    class BulletedListBlock < Block
+      def initialize(children: [])
+        @children = children
+      end
+
+      # === Parameters:
+      # tab_width::
+      #  The number of tabs used to indent the block.
+      #
+      # === Returns
+      # The current block (and its children) converted to a markdown string.
+      #
+      def to_md(tab_width: 0)
+        if tab_width.zero?
+          build_nested_blocks(tab_width) + newline
+        else
+          build_nested_blocks(tab_width)
+        end
+      end
+
+      def type
+        'bulleted_list'
+      end
+
+      def newline
+        "\n"
+      end
+    end
+  end
+end

data/lib/notion_to_md/blocks/bulleted_list_item_block.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module NotionToMd
+  module Blocks
+    class BulletedListItemBlock < Block
+      def newline
+        "\n"
+      end
+
+      def indent_children(mds, _tab_width)
+        mds
+      end
+    end
+  end
+end

data/lib/notion_to_md/blocks/factory.rb

@@ -7,6 +7,14 @@ module NotionToMd
         case block.type.to_sym
         when :table
           TableBlock.new(block: block, children: children)
+        when :table_row
+          TableRowBlock.new(block: block, children: children)
+        when :bulleted_list_item
+          BulletedListItemBlock.new(block: block, children: children)
+        when :numbered_list_item
+          NumberedListItemBlock.new(block: block, children: children)
+        when :to_do
+          ToDoListItemBlock.new(block: block, children: children)
         else
           Blocks::Block.new(block: block, children: children)
         end

data/lib/notion_to_md/blocks/normalizer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module NotionToMd
+  module Blocks
+    class Normalizer
+      # === Parameters
+      # blocks::
+      #  An array of NotionToMd::Blocks::Block.
+      #
+      def self.normalize(blocks:)
+        new(blocks: blocks).normalize
+      end
+
+      attr_reader :normalized_blocks
+
+      def initialize(blocks:)
+        @normalized_blocks = blocks.dup
+      end
+
+      def normalize
+        normalize_for :bulleted_list_item
+        normalize_for :numbered_list_item
+        normalize_for :to_do
+      end
+
+      def normalize_for(type)
+        new_blocks = []
+
+        normalized_blocks.each do |block|
+          if block.type.to_sym == type
+            blocks_to_normalize << block
+          else
+            # When we encounter a block that is not of the provided type,
+            # we need to normalize the blocks we've collected so far.
+            # Then we add the current block to the new blocks array.
+            # This is because we want to keep the order of the blocks.
+            new_blocks << new_block_and_reset_blocks_to_normalize(type) unless blocks_to_normalize.empty?
+            new_blocks << block
+          end
+        end
+
+        # If the last block is the provided type, it won't be added to the new blocks array.
+        # So, we need to normalize the blocks we've collected so far.
+        new_blocks << new_block_and_reset_blocks_to_normalize(type) unless blocks_to_normalize.empty?
+
+        normalized_blocks.replace(new_blocks)
+      end
+
+      private
+
+      def new_block_and_reset_blocks_to_normalize(type)
+        new_block = new_block_for(type, blocks_to_normalize)
+        @blocks_to_normalize = []
+        new_block
+      end
+
+      def blocks_to_normalize
+        @blocks_to_normalize ||= []
+      end
+
+      def new_block_for(type, children)
+        case type
+        when :bulleted_list_item
+          BulletedListBlock.new(children: children)
+        when :numbered_list_item
+          NumberedListBlock.new(children: children)
+        when :to_do
+          ToDoListBlock.new(children: children)
+        end
+      end
+    end
+  end
+end

data/lib/notion_to_md/blocks/numbered_list_block.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module NotionToMd
+  module Blocks
+    class NumberedListBlock < BulletedListBlock
+      def type
+        'numbered_list'
+      end
+
+      protected
+
+      def markdownify_children(tab_width)
+        children.map.with_index do |nested_block, index|
+          nested_block.to_md(tab_width: tab_width, index: index + 1)
+        end
+      end
+    end
+  end
+end

data/lib/notion_to_md/blocks/numbered_list_item_block.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative './bulleted_list_item_block'
+
+module NotionToMd
+  module Blocks
+    class NumberedListItemBlock < BulletedListItemBlock
+      # === Parameters:
+      # tab_width::
+      #  The number of tabs used to indent the block.
+      # index::
+      #  The index of the block in its parent's children array used to number the item.
+      #
+      # === Returns
+      # The current block (and its children) converted to a markdown string.
+      #
+      def to_md(tab_width: 0, index: nil)
+        md = Types.numbered_list_item(block[block.type.to_sym], index) + newline
+        md + build_nested_blocks(tab_width + 1)
+      rescue NoMethodError
+        Logger.info("Unsupported block type: #{block.type}")
+        nil
+      end
+    end
+  end
+end

data/lib/notion_to_md/blocks/table_block.rb

@@ -10,17 +10,21 @@ module NotionToMd
         table_aligment = markdownify_aligment
         table_body = table[1..table.size]
 
-        [table_header, table_aligment, table_body.join("\n")].compact.join("\n")
+        [table_header, table_aligment, table_body].compact.join + newline
       end
 
-      private
+      protected
 
       def row_size
         @row_size ||= children.first.block.table_row.cells.size
       end
 
       def markdownify_aligment
-        "|#{row_size.times.map { '---' }.join('|')}|" if block.table.has_column_header
+        "|#{row_size.times.map { '---' }.join('|')}|\n" if block.table.has_column_header
+      end
+
+      def newline
+        "\n"
       end
     end
   end

data/lib/notion_to_md/blocks/table_row_block.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module NotionToMd
+  module Blocks
+    class TableRowBlock < Block
+      def newline
+        "\n"
+      end
+    end
+  end
+end

data/lib/notion_to_md/blocks/to_do_list_block.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module NotionToMd
+  module Blocks
+    class ToDoListBlock < BulletedListBlock
+      def type
+        'to_do_list'
+      end
+    end
+  end
+end

data/lib/notion_to_md/blocks/to_do_list_item_block.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative './bulleted_list_item_block'
+
+module NotionToMd
+  module Blocks
+    class ToDoListItemBlock < BulletedListItemBlock
+      def newline
+        "\n"
+      end
+    end
+  end
+end

data/lib/notion_to_md/blocks/types.rb

@@ -36,9 +36,10 @@ module NotionToMd
           "- #{convert_text(block)}"
         end
 
-        def numbered_list_item(block)
-          Logger.info('numbered_list_item type not supported. Shown as bulleted_list_item.')
-          bulleted_list_item(block)
+        def numbered_list_item(block, index = nil)
+          return bulleted_list_item(block) if index.nil?
+
+          "#{index}. #{convert_text(block)}"
         end
 
         def to_do(block)

data/lib/notion_to_md/blocks.rb

@@ -1,51 +1,32 @@
 # frozen_string_literal: true
 
-require_relative './blocks/block'
+require_relative './blocks/builder'
+require_relative './blocks/normalizer'
 require_relative './blocks/factory'
-require_relative './blocks/table_block'
 require_relative './blocks/types'
+require_relative './blocks/block'
+require_relative './blocks/table_block'
+require_relative './blocks/table_row_block'
+require_relative './blocks/bulleted_list_block'
+require_relative './blocks/bulleted_list_item_block'
+require_relative './blocks/numbered_list_block'
+require_relative './blocks/numbered_list_item_block'
+require_relative './blocks/to_do_list_block'
+require_relative './blocks/to_do_list_item_block'
 
 module NotionToMd
   module Blocks
-    ##
-    # Array containing the block types allowed to have nested blocks (children).
-    PERMITTED_CHILDREN = [
-      Types.method(:bulleted_list_item).name,
-      Types.method(:numbered_list_item).name,
-      Types.method(:paragraph).name,
-      Types.method(:to_do).name,
-      :table
-    ].freeze
-
-    # === Parameters
-    # block::
-    #   A {Notion::Messages::Message}[https://github.com/orbit-love/notion-ruby-client/blob/main/lib/notion/messages/message.rb] object.
-    #
-    # === Returns
-    # A boolean indicating if the blocked passed in
-    # is permitted to have children based on its type.
-    #
-    def self.permitted_children?(block:)
-      PERMITTED_CHILDREN.include?(block.type.to_sym) && block.has_children
-    end
-
     # === Parameters
     # block_id::
     #   A string representing a notion block id .
+    # fetch_blocks::
+    #   A block that fetches the blocks from the Notion API.
     #
     # === Returns
     # An array of NotionToMd::Blocks::Block.
     #
     def self.build(block_id:, &fetch_blocks)
-      blocks = fetch_blocks.call(block_id)
-      blocks.results.map do |block|
-        children = if permitted_children?(block: block)
-                     build(block_id: block.id, &fetch_blocks)
-                   else
-                     []
-                   end
-        Factory.build(block: block, children: children)
-      end
+      Builder.new(block_id: block_id, &fetch_blocks).build
     end
   end
 end

data/lib/notion_to_md/helpers/yaml_sanitizer.rb

@@ -0,0 +1,17 @@
+module NotionToMd
+  module Helpers
+    module YamlSanitizer
+      # Escape the frontmatter value if it contains a colon or a dash followed by a space
+      # @param value [String] the value to escape
+      # @return [String] the escaped value
+      def escape_frontmatter_value(value)
+        if value.match?(/: |-\s/)
+          # Escape the double quotes inside the string
+          "\"#{value.gsub('"', '\"')}\""
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/notion_to_md/helpers.rb

@@ -0,0 +1 @@
+require_relative './helpers/yaml_sanitizer'

data/lib/notion_to_md/page.rb

@@ -2,6 +2,8 @@
 
 module NotionToMd
   class Page
+    include Helpers::YamlSanitizer
+
     attr_reader :page, :blocks
 
     def initialize(page:, blocks:)
@@ -45,7 +47,7 @@ module NotionToMd
     end
 
     def body
-      @body ||= blocks.map(&:to_md).compact.join("\n\n")
+      @body ||= blocks.map(&:to_md).compact.join
     end
 
     def frontmatter
@@ -77,11 +79,11 @@ module NotionToMd
     def default_props
       @default_props ||= {
         'id' => id,
-        'title' => title,
+        'title' => escape_frontmatter_value(title),
         'created_time' => created_time,
         'cover' => cover,
         'icon' => icon,
-        'last_edited_time' => last_edited_time,
+        'last_edited_time' => last_edited_time.to_s.dump,
         'archived' => archived
       }
     end

data/lib/notion_to_md/page_property.rb

@@ -3,6 +3,8 @@
 module NotionToMd
   class PageProperty
     class << self
+      include Helpers::YamlSanitizer
+
       def file(prop)
         prop.dig(:file, :url)
       rescue NoMethodError
@@ -28,7 +30,7 @@ module NotionToMd
       end
 
       def select(prop)
-        prop.dig(:select, :name)
+        escape_frontmatter_value(prop.dig(:select, :name))
       rescue NoMethodError
         nil
       end
@@ -85,7 +87,8 @@ module NotionToMd
       end
 
       def rich_text(prop)
-        prop[:rich_text].map { |text| text[:plain_text] }.join
+        text = prop[:rich_text].map { |text| text[:plain_text] }.join
+        text.blank? ? nil : escape_frontmatter_value(text)
       rescue NoMethodError
         nil
       end

data/lib/notion_to_md/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NotionToMd
-  VERSION = '2.2.4'
+  VERSION = '2.3.1'
 end

data/lib/notion_to_md.rb

@@ -4,6 +4,7 @@ require 'notion'
 require 'logger'
 require 'active_support/inflector'
 require 'active_support/core_ext/object/blank'
+require_relative './notion_to_md/helpers'
 require_relative './notion_to_md/version'
 require_relative './notion_to_md/converter'
 require_relative './notion_to_md/logger'
@@ -12,3 +13,20 @@ require_relative './notion_to_md/page'
 require_relative './notion_to_md/blocks'
 require_relative './notion_to_md/text'
 require_relative './notion_to_md/text_annotation'
+
+module NotionToMd
+  # === Parameters
+  # page_id::
+  #   A string representing the notion page id.
+  # token::
+  #   The notion API secret token. The token can replaced by the environment variable NOTION_TOKEN.
+  # frontmatter::
+  #   A boolean indicating whether to include the page properties as frontmatter.
+  #
+  # === Returns
+  # The string that represent the markdown document.
+  #
+  def self.convert(page_id:, token: nil, frontmatter: false)
+    Converter.new(page_id: page_id, token: token).convert(frontmatter: frontmatter)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: notion_to_md
 version: !ruby/object:Gem::Version
-  version: 2.2.4
+  version: 2.3.1
 platform: ruby
 authors:
 - Enrique Arias
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-22 00:00:00.000000000 Z
+date: 2023-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -108,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Notion Markdown Exporter in Ruby
 email: emoriarty81@gmail.com
 executables: []
@@ -118,10 +132,21 @@ files:
 - lib/notion_to_md.rb
 - lib/notion_to_md/blocks.rb
 - lib/notion_to_md/blocks/block.rb
+- lib/notion_to_md/blocks/builder.rb
+- lib/notion_to_md/blocks/bulleted_list_block.rb
+- lib/notion_to_md/blocks/bulleted_list_item_block.rb
 - lib/notion_to_md/blocks/factory.rb
+- lib/notion_to_md/blocks/normalizer.rb
+- lib/notion_to_md/blocks/numbered_list_block.rb
+- lib/notion_to_md/blocks/numbered_list_item_block.rb
 - lib/notion_to_md/blocks/table_block.rb
+- lib/notion_to_md/blocks/table_row_block.rb
+- lib/notion_to_md/blocks/to_do_list_block.rb
+- lib/notion_to_md/blocks/to_do_list_item_block.rb
 - lib/notion_to_md/blocks/types.rb
 - lib/notion_to_md/converter.rb
+- lib/notion_to_md/helpers.rb
+- lib/notion_to_md/helpers/yaml_sanitizer.rb
 - lib/notion_to_md/logger.rb
 - lib/notion_to_md/page.rb
 - lib/notion_to_md/page_property.rb