notion_to_md 2.4.1 → 2.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2c563b14bee2d927bd6f37cbbc18f59f52545bdc02bcb74e865657231a8d926
-  data.tar.gz: e99d9b5e01e3c042e26818ea5eb8b7652701fca9d3a1d94f1c4b5cc41efdca8b
+  metadata.gz: bb8852f9013936bcb404e0779e4930e84831e2db4235b2f0bca8268a9e4edaf0
+  data.tar.gz: d3b9fe50d279cfc14abf20d7f8468d1534b043b73e00ee8123248556c03b43bf
 SHA512:
-  metadata.gz: 0f523319dad22eeae015ab2e52bbd24f04d34acf9f654e4d92a9dcebed1e3a0255f08d8492af371347d2fc81d3acf24d0ef0e51d3a0708a2d143485056e783b9
-  data.tar.gz: 8d01b8e6d570da473aa38eb32391f26841ec49e75809ea5733f94974a37a495d731200f3c24a2e3909579ee9ffc1d7d3fcb8b1523fb3070a9d87a711af2be8d9
+  metadata.gz: e49f3a1d040fb7381e8369c774cff8a31a510909c3e7813c4ba8016085075d613d01808a23a8075d9d9246335eadd1e08347225d287c702c07753df44f3f3af7
+  data.tar.gz: 52806a867c8d24e96e993c4a07741ff13322d14151e0285351c341237a772579f7084913764112f703435e963d598754e326e0c047c29f2d74f4ce6b58f68951

data/README.md

@@ -1,6 +1,8 @@
 # notion_to_md
 Notion Markdown Exporter in Ruby.
 
+The generated document is compliant with the [GitHub Flavored Markdown specification](https://github.github.com/gfm/).
+
 ## Installation
 Use gem to install.
 ```bash
@@ -28,8 +30,6 @@ 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_...')
 ```
 
@@ -40,15 +40,27 @@ $ export NOTION_TOKEN=<secret_...>
 ```
 
 ```ruby
-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.
+And that's all. The `md` is a string variable containing the notion document formatted in markdown.
+
+### Callable
+
+From version 2.5.0, the `call` method is also available. It's an alias for `convert`.
+
+```ruby
+md = NotionToMd.call(page_id: 'b91d5...')
+```
+
+The `call` method also supports the passing of a block.
+
+```ruby
+NotionToMd.call(page_id: 'b91d5...') { puts _1 }
+```
 
 ## Blocks
 
@@ -69,6 +81,11 @@ Everything in a notion page body is a [block object](https://developers.notion.c
 * `table`
 * `embed`
 * `code`
+* `link_preview`
+* `file`
+* `pdf`
+* `video`
+* `equation`
 
 ### Nested blocks
 

data/lib/notion_to_md/blocks/block.rb

@@ -2,8 +2,11 @@
 
 require 'forwardable'
 
-module NotionToMd
+class NotionToMd
   module Blocks
+    # === NotionToMd::Blocks::Block
+    #
+    # This class is responsible for converting Notion blocks to markdown.
     class Block
       extend Forwardable
 

data/lib/notion_to_md/blocks/builder.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
+    # === NotionToMd::Blocks::Builder
+    #
+    # This class is responsible for building a tree of blocks from the Notion API.
     class Builder
       ##
       # Array containing the block types allowed to have nested blocks (children).

data/lib/notion_to_md/blocks/bulleted_list_block.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
     class BulletedListBlock < Block
       def initialize(children: [])

data/lib/notion_to_md/blocks/bulleted_list_item_block.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
     class BulletedListItemBlock < Block
       def newline

data/lib/notion_to_md/blocks/factory.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
+    # === NotionToMd::Blocks::Factory
+    #
+    # Factory class to create block instances based on the block type
     class Factory
+      # rubocop:disable Metrics/MethodLength
       def self.build(block:, children: [])
         case block.type.to_sym
         when :table
@@ -19,6 +23,7 @@ module NotionToMd
           Blocks::Block.new(block: block, children: children)
         end
       end
+      # rubocop:enable Metrics/MethodLength
     end
   end
 end

data/lib/notion_to_md/blocks/normalizer.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
+    # === NotionToMd::Blocks::Normalizer
+    #
+    # This class is responsible for normalizing blocks of the same type
     class Normalizer
       # === Parameters
       # blocks::
@@ -27,27 +30,37 @@ module NotionToMd
         new_blocks = []
 
         normalized_blocks.each do |block|
-          if block.type.to_sym == type
+          if block_of_type?(block, 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?
+            # This is to keep the order of the blocks as they are in the original array.
+            flush_blocks_to_normalize_into(new_blocks, type)
             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?
+        flush_blocks_to_normalize_into(new_blocks, type)
 
         normalized_blocks.replace(new_blocks)
       end
 
       private
 
+      def block_of_type?(block, type)
+        block.type.to_sym == type
+      end
+
+      def flush_blocks_to_normalize_into(new_blocks, type)
+        return if blocks_to_normalize.empty?
+
+        new_blocks << new_block_and_reset_blocks_to_normalize(type)
+      end
+
       def new_block_and_reset_blocks_to_normalize(type)
         new_block = new_block_for(type, blocks_to_normalize)
         @blocks_to_normalize = []

data/lib/notion_to_md/blocks/numbered_list_block.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
     class NumberedListBlock < BulletedListBlock
       def type

data/lib/notion_to_md/blocks/numbered_list_item_block.rb

@@ -2,7 +2,7 @@
 
 require_relative './bulleted_list_item_block'
 
-module NotionToMd
+class NotionToMd
   module Blocks
     class NumberedListItemBlock < BulletedListItemBlock
       # === Parameters:

data/lib/notion_to_md/blocks/table_block.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
     class TableBlock < Block
       def to_md

data/lib/notion_to_md/blocks/table_row_block.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
     class TableRowBlock < Block
       def newline

data/lib/notion_to_md/blocks/to_do_list_block.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
     class ToDoListBlock < BulletedListBlock
       def type

data/lib/notion_to_md/blocks/to_do_list_item_block.rb

@@ -2,7 +2,7 @@
 
 require_relative './bulleted_list_item_block'
 
-module NotionToMd
+class NotionToMd
   module Blocks
     class ToDoListItemBlock < BulletedListItemBlock
       def newline

data/lib/notion_to_md/blocks/types.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   module Blocks
     class Types
       class << self
@@ -89,6 +89,32 @@ module NotionToMd
           "|#{block[:cells].map(&method(:convert_table_row)).join('|')}|"
         end
 
+        def link_preview(block)
+          url = block[:url]
+
+          "[#{url}](#{url})"
+        end
+
+        def file(block)
+          type = block[:type].to_sym
+          url = block.dig(type, :url)
+          caption = convert_caption(block)
+
+          "[#{url}](#{url})\n\n#{caption}"
+        end
+
+        def pdf(block)
+          file(block)
+        end
+
+        def video(block)
+          file(block)
+        end
+
+        def equation(block)
+          "$$#{block['expression']}$$"
+        end
+
         private
 
         def convert_table_row(cells)

data/lib/notion_to_md/blocks.rb

@@ -14,7 +14,10 @@ require_relative './blocks/numbered_list_item_block'
 require_relative './blocks/to_do_list_block'
 require_relative './blocks/to_do_list_item_block'
 
-module NotionToMd
+class NotionToMd
+  # === NotionToMd::Blocks
+  #
+  # This module is responsible for building Notion blocks.
   module Blocks
     # === Parameters
     # block_id::

data/lib/notion_to_md/converter.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-module NotionToMd
-  ##
+class NotionToMd
   # The Converter class allows to transform notion pages to markdown documents.
   # Just create a new Converter instance by providing the page_id:
   #   page_converter = NotionToMd::Converter.new(page_id: '9dc17c9c9d2e469dbbf0f9648f3288d3')
   # Then, call for convert to obtain the markdown document:
   #   page_converter.convert
-
   class Converter
-    attr_reader :page_id
+    include Callee
+
+    attr_reader :page_id, :frontmatter
 
     # === Parameters
     # page_id::
@@ -20,9 +20,10 @@ module NotionToMd
     # === Returns
     # A NotionToMd::Converter object.
     #
-    def initialize(page_id:, token: nil)
+    def initialize(page_id:, token: nil, frontmatter: false)
       @notion = Notion::Client.new(token: token || ENV['NOTION_TOKEN'])
       @page_id = page_id
+      @frontmatter = frontmatter
     end
 
     # === Parameters
@@ -40,6 +41,14 @@ module NotionToMd
       MD
     end
 
+    def call
+      md = convert frontmatter: frontmatter
+
+      yield md if block_given?
+
+      md
+    end
+
     private
 
     def page

data/lib/notion_to_md/helpers/yaml_sanitizer.rb

@@ -1,4 +1,6 @@
-module NotionToMd
+# frozen_string_literal: true
+
+class NotionToMd
   module Helpers
     module YamlSanitizer
       # Escape the frontmatter value if it contains a colon or a dash followed by a space

data/lib/notion_to_md/helpers.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require_relative './helpers/yaml_sanitizer'

data/lib/notion_to_md/logger.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   class Logger
     @logger = ::Logger.new($stdout)
 

data/lib/notion_to_md/page.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
+  # === NotionToMd::Page
+  #
+  # This class is responsible for representing a Notion page.
   class Page
     include Helpers::YamlSanitizer
 
@@ -81,17 +84,10 @@ module NotionToMd
     end
 
     def custom_props
-      @custom_props ||= page.properties.each_with_object({}) do |prop, memo|
-        name = prop.first
-        value = prop.last # Notion::Messages::Message
-        type = value.type
-
-        next memo unless CustomProperty.respond_to?(type.to_sym)
-
-        memo[name.parameterize.underscore] = CustomProperty.send(type, value)
-      end.reject { |_k, v| v.presence.nil? }
+      @custom_props ||= filtered_custom_properties
     end
 
+    # rubocop:disable Metrics/MethodLength
     def default_props
       @default_props ||= {
         'id' => id,
@@ -107,10 +103,35 @@ module NotionToMd
         'last_edited_by_id' => last_edited_by_id
       }
     end
+    # rubocop:enable Metrics/MethodLength
 
     # This class is kept for retro compatibility reasons.
     # Use instead the PageProperty class.
     class CustomProperty < PageProperty
     end
+
+    private
+
+    def filtered_custom_properties
+      build_custom_properties.reject { |_k, v| v.presence.nil? }
+    end
+
+    def build_custom_properties
+      page.properties.each_with_object({}) do |(name, value), memo|
+        type = value.type
+        next unless valid_custom_property_type?(type)
+
+        key = name.parameterize.underscore
+        memo[key] = build_custom_property(type, value)
+      end
+    end
+
+    def valid_custom_property_type?(type)
+      CustomProperty.respond_to?(type.to_sym)
+    end
+
+    def build_custom_property(type, value)
+      CustomProperty.send(type, value)
+    end
   end
 end

data/lib/notion_to_md/page_property.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   class PageProperty
     class << self
       include Helpers::YamlSanitizer
@@ -66,7 +66,7 @@ module NotionToMd
       end
 
       def checkbox(prop)
-        prop[:checkbox].nil? ? nil : prop[:checkbox].to_s
+        prop[:checkbox]&.to_s
       rescue NoMethodError
         nil
       end

data/lib/notion_to_md/text.rb

@@ -1,4 +1,6 @@
-module NotionToMd
+# frozen_string_literal: true
+
+class NotionToMd
   class Text
     class << self
       def text(text)
@@ -6,7 +8,7 @@ module NotionToMd
       end
 
       def equation(text)
-        "$$ #{text[:plain_text]} $$"
+        "$`#{text[:plain_text]}`$"
       end
     end
   end

data/lib/notion_to_md/text_annotation.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module NotionToMd
+class NotionToMd
   ##
   # Append the text type:
   # * italic: boolean,

data/lib/notion_to_md/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module NotionToMd
-  VERSION = '2.4.1'
+class NotionToMd
+  VERSION = '2.5.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 'callee'
 require_relative './notion_to_md/helpers'
 require_relative './notion_to_md/version'
 require_relative './notion_to_md/converter'
@@ -14,7 +15,18 @@ require_relative './notion_to_md/blocks'
 require_relative './notion_to_md/text'
 require_relative './notion_to_md/text_annotation'
 
-module NotionToMd
+# The NotionToMd class allows to transform notion pages to markdown documents.
+class NotionToMd
+  include Callee
+
+  attr_reader :page_id, :token, :frontmatter
+
+  def initialize(page_id:, token: nil, frontmatter: false)
+    @page_id = page_id
+    @token = token || ENV['NOTION_TOKEN']
+    @frontmatter = frontmatter
+  end
+
   # === Parameters
   # page_id::
   #   A string representing the notion page id.
@@ -29,4 +41,12 @@ module NotionToMd
   def self.convert(page_id:, token: nil, frontmatter: false)
     Converter.new(page_id: page_id, token: token).convert(frontmatter: frontmatter)
   end
+
+  def call
+    md = self.class.convert(page_id: page_id, token: token, frontmatter: frontmatter)
+
+    yield md if block_given?
+
+    md
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: notion_to_md
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.1
 platform: ruby
 authors:
 - Enrique Arias
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-20 00:00:00.000000000 Z
+date: 2025-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7'
+- !ruby/object:Gem::Dependency
+  name: callee
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.6
 - !ruby/object:Gem::Dependency
   name: notion-ruby-client
   requirement: !ruby/object:Gem::Requirement