notion_to_md 2.5.1 → 3.0.0.beta2

data/lib/notion_to_md.rb

@@ -4,49 +4,76 @@ 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'
-require_relative './notion_to_md/logger'
-require_relative './notion_to_md/page_property'
-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'
-
-# The NotionToMd class allows to transform notion pages to markdown documents.
-class NotionToMd
-  include Callee
-
-  attr_reader :page_id, :token, :frontmatter
+require 'zeitwerk'
 
-  def initialize(page_id:, token: nil, frontmatter: false)
-    @page_id = page_id
-    @token = token || ENV['NOTION_TOKEN']
-    @frontmatter = frontmatter
-  end
+# Load the NotionToMd classes using Zeitwerk
+loader = Zeitwerk::Loader.for_gem
+loader.setup
 
-  # === 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.
+##
+# The {NotionToMd} class is the main entry point for converting
+# Notion pages and databases into Markdown documents.
+#
+# It provides a single class method {.call} (aliased as {.convert})
+# that accepts a Notion resource type (`:page` or `:database`), an ID,
+# and options to control conversion.
+#
+# @example Convert a single Notion page to Markdown
+#   markdown = NotionToMd.call(:page, id: "xxxx-xxxx", token: "secret_token")
+#
+# @example Convert a Notion database to Markdown and yield the result
+#   NotionToMd.convert(:database, id: "xxxx-xxxx").each_with_index do |md, index|
+#     File.write("output_#{index}.md", md)
+#   end
+#
+class NotionToMd
+  ##
+  # Supported resource types for conversion.
   #
-  def self.convert(page_id:, token: nil, frontmatter: false)
-    Converter.new(page_id: page_id, token: token).convert(frontmatter: frontmatter)
-  end
+  # @return [Hash{Symbol => Symbol}] mapping of friendly keys to types
+  TYPES = { database: :database, page: :page }.freeze
+
+  class << self
+    ##
+    # Convert a Notion resource (page or database) to Markdown.
+    #
+    # @param type [Symbol] the type of Notion resource (`:page` or `:database`).
+    # @param id [String] the Notion page or database ID.
+    # @param token [String, nil] the Notion API token.
+    #   If omitted, defaults to `ENV['NOTION_TOKEN']`.
+    # @param frontmatter [Boolean] whether to include YAML frontmatter
+    #   in the generated Markdown.
+    #
+    # @yield [md] optional block to handle the generated Markdown.
+    # @yieldparam md [String] the Markdown output.
+    #
+    # @return [String] the Markdown representation of the Notion resource.
+    #
+    # @raise [RuntimeError] if the given +type+ is not supported.
+    #
+    def call(type, id:, token: nil, frontmatter: false)
+      raise "#{type} is not supported. Use :database or :page" unless TYPES.values.include?(type)
+
+      notion_client = Notion::Client.new(token: token || ENV.fetch('NOTION_TOKEN', nil))
+      md = case type
+           when TYPES[:database]
+             Database.call(id: id, notion_client: notion_client, frontmatter: frontmatter).to_md
+           when TYPES[:page]
+             Page.call(id: id, notion_client: notion_client, frontmatter: frontmatter).to_md
+           end
 
-  def call
-    md = self.class.convert(page_id: page_id, token: token, frontmatter: frontmatter)
+      yield md if block_given?
 
-    yield md if block_given?
+      md
+    end
 
-    md
+    ##
+    # Alias for {.call}.
+    #
+    # @see .call
+    #
+    def convert(type, id:, token: nil, frontmatter: false, &block)
+      call(type, id: id, token: token, frontmatter: frontmatter, &block)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: notion_to_md
 version: !ruby/object:Gem::Version
-  version: 2.5.1
+  version: 3.0.0.beta2
 platform: ruby
 authors:
 - Enrique Arias
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-19 00:00:00.000000000 Z
+date: 2025-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,20 +24,6 @@ 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
@@ -53,89 +39,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1'
 - !ruby/object:Gem::Dependency
-  name: hashie
-  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'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  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'
-- !ruby/object:Gem::Dependency
-  name: rubocop
+  name: zeitwerk
   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'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  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'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  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'
-- !ruby/object:Gem::Dependency
-  name: vcr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '2.6'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.6'
 description: Notion Markdown Exporter in Ruby
 email: emoriarty81@gmail.com
 executables: []
@@ -144,33 +60,38 @@ extra_rdoc_files: []
 files:
 - README.md
 - 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/renderer.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/database.rb
+- lib/notion_to_md/database/builder.rb
 - lib/notion_to_md/logger.rb
+- lib/notion_to_md/metadata_type.rb
 - lib/notion_to_md/page.rb
-- lib/notion_to_md/page_property.rb
+- lib/notion_to_md/page/builder.rb
+- lib/notion_to_md/support/frontmatter.rb
+- lib/notion_to_md/support/metadata_properties.rb
+- lib/notion_to_md/support/pagination.rb
+- lib/notion_to_md/support/yaml_sanitizer.rb
 - lib/notion_to_md/text.rb
 - lib/notion_to_md/text_annotation.rb
 - lib/notion_to_md/version.rb
 homepage: https://github.com/emoriarty/notion_to_md
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
+  status: beta
+  source_code_uri: https://github.com/emoriarty/notion_to_md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -179,12 +100,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.1.6
 signing_key:

data/lib/notion_to_md/blocks/builder.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-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).
-      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.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-require_relative './blocks/builder'
-require_relative './blocks/normalizer'
-require_relative './blocks/factory'
-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'
-
-class NotionToMd
-  # === NotionToMd::Blocks
-  #
-  # This module is responsible for building Notion blocks.
-  module 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 self.build(block_id:, &fetch_blocks)
-      Builder.new(block_id: block_id, &fetch_blocks).build
-    end
-  end
-end

data/lib/notion_to_md/converter.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-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
-    include Callee
-
-    attr_reader :page_id, :frontmatter
-
-    # === 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.
-    #
-    # === Returns
-    # A NotionToMd::Converter object.
-    #
-    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
-    # frontmatter::
-    #   A boolean value that indicates whether the front matter block is included in the markdown document.
-    #
-    # === Returns
-    # The string that represent the markdown document.
-    #
-    def convert(frontmatter: false)
-      md_page = Page.new(page: page, blocks: page_blocks)
-      <<~MD
-        #{md_page.frontmatter if frontmatter}
-        #{md_page.body}
-      MD
-    end
-
-    def call
-      md = convert frontmatter: frontmatter
-
-      yield md if block_given?
-
-      md
-    end
-
-    private
-
-    def page
-      @page ||= @notion.page(page_id: page_id)
-    end
-
-    def page_blocks
-      @page_blocks ||= build_blocks(block_id: page_id)
-    end
-
-    def build_blocks(block_id:)
-      Blocks.build(block_id: block_id) do |nested_block_id|
-        fetch_blocks(block_id: nested_block_id)
-      end
-    end
-
-    def fetch_blocks(block_id:)
-      @notion.block_children(block_id: block_id)
-    end
-  end
-end

data/lib/notion_to_md/helpers/yaml_sanitizer.rb

@@ -1,19 +0,0 @@
-# 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
-      # @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

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

data/lib/notion_to_md/page_property.rb

@@ -1,106 +0,0 @@
-# frozen_string_literal: true
-
-class NotionToMd
-  class PageProperty
-    class << self
-      include Helpers::YamlSanitizer
-
-      def file(prop)
-        prop.dig(:file, :url)
-      rescue NoMethodError
-        nil
-      end
-
-      def external(prop)
-        prop.dig(:external, :url)
-      rescue NoMethodError
-        nil
-      end
-
-      def emoji(prop)
-        prop[:emoji]
-      rescue NoMethodError
-        nil
-      end
-
-      def multi_select(prop)
-        prop[:multi_select].map { |sel| sel[:name] }
-      rescue NoMethodError
-        nil
-      end
-
-      def select(prop)
-        escape_frontmatter_value(prop.dig(:select, :name))
-      rescue NoMethodError
-        nil
-      end
-
-      def people(prop)
-        prop[:people].map { |sel| sel[:name] }
-      rescue NoMethodError
-        nil
-      end
-
-      def files(prop)
-        prop[:files].map { |f| file(f) || external(f) }
-      rescue NoMethodError
-        nil
-      end
-
-      def phone_number(prop)
-        prop[:phone_number]
-      rescue NoMethodError
-        nil
-      end
-
-      def number(prop)
-        prop[:number]
-      rescue NoMethodError
-        nil
-      end
-
-      def email(prop)
-        prop[:email]
-      rescue NoMethodError
-        nil
-      end
-
-      def checkbox(prop)
-        prop[:checkbox]&.to_s
-      rescue NoMethodError
-        nil
-      end
-
-      # date type properties not supported:
-      # - end
-      # - time_zone
-      def date(prop)
-        date = prop.dig(:date, :start)
-
-        case date
-        when Date
-          date.to_time
-        when String
-          Time.parse(date)
-        else
-          date # Time or nil
-        end
-      rescue NoMethodError
-        nil
-      end
-
-      def url(prop)
-        prop[:url]
-      rescue NoMethodError
-        nil
-      end
-
-      def rich_text(prop)
-        text = prop[:rich_text].map { |text| text[:plain_text] }.join
-        text.blank? ? nil : escape_frontmatter_value(text)
-      rescue NoMethodError
-        nil
-      end
-    end
-  end
-end