notion_to_md 2.5.1 → 3.0.0.beta1

data/lib/notion_to_md/support/frontmatter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+class NotionToMd
+  module Support
+    # === NotionToMd::Support::Frontmatter
+    #
+    # Mixin module responsible for generating YAML frontmatter for
+    # Notion pages and databases. Combines default metadata (id, title,
+    # timestamps, cover, icon, etc.) with supported custom properties.
+    #
+    # @example Use in a page class
+    #   class Page
+    #     include NotionToMd::Support::MetadataProperties
+    #     include NotionToMd::Support::Frontmatter
+    #     attr_reader :metadata
+    #   end
+    #
+    #   page = Page.new(metadata: notion_page_hash)
+    #   puts page.frontmatter
+    #   # =>
+    #   # ---
+    #   # id: 1234
+    #   # title: "Hello World"
+    #   # created_time: 2025-01-01 00:00:00 +0000
+    #   # ...
+    #   # ---
+    #
+    # @see NotionToMd::Support::YamlSanitizer
+    # @see NotionToMd::MetadataType
+    module Frontmatter
+      include YamlSanitizer
+
+      # Generate the YAML frontmatter string by merging default and custom properties.
+      #
+      # @return [String] YAML frontmatter block, surrounded by `---` markers.
+      def frontmatter
+        @frontmatter ||= <<~CONTENT
+          ---
+          #{frontmatter_properties.to_a.map do |k, v|
+              "#{k}: #{v}"
+            end.join("\n")}
+          ---
+        CONTENT
+      end
+
+      private
+
+      # Merge custom and default properties into the final set of frontmatter properties.
+      #
+      # @return [Hash{String => Object}]
+      def frontmatter_properties
+        @frontmatter_properties ||= frontmatter_custom_properties.deep_merge(frontmatter_default_properties)
+      end
+
+      # Retrieve sanitized custom properties.
+      #
+      # @return [Hash{String => Object}]
+      def frontmatter_custom_properties
+        @frontmatter_custom_properties ||= compact_frontmatter_custom_properties
+      end
+
+      # Remove nil/blank values from custom properties.
+      #
+      # @return [Hash{String => Object}]
+      def compact_frontmatter_custom_properties
+        build_frontmatter_custom_properties.reject { |_k, v| v.presence.nil? }
+      end
+
+      # Build supported custom properties based on their type.
+      #
+      # @return [Hash{String => Object}]
+      def build_frontmatter_custom_properties
+        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
+
+      # Determine whether a custom property type is supported.
+      #
+      # @param type [String, Symbol]
+      # @return [Boolean]
+      def valid_custom_property_type?(type)
+        MetadataType.respond_to?(type.to_sym)
+      end
+
+      # Convert a Notion property into a YAML-safe value.
+      #
+      # @param type [String, Symbol] The property type.
+      # @param value [Object] The raw Notion property value.
+      # @return [Object] The normalized value suitable for YAML.
+      def build_custom_property(type, value)
+        MetadataType.send(type, value)
+      end
+
+      # Default frontmatter properties derived from metadata.
+      #
+      # @return [Hash{String => Object}]
+      def frontmatter_default_properties
+        @frontmatter_default_properties ||= {
+          'id' => id,
+          'title' => escape_frontmatter_value(title),
+          'created_time' => created_time,
+          'cover' => cover,
+          'icon' => icon,
+          'last_edited_time' => last_edited_time,
+          'archived' => archived,
+          'created_by_object' => created_by_object,
+          'created_by_id' => created_by_id,
+          'last_edited_by_object' => last_edited_by_object,
+          'last_edited_by_id' => last_edited_by_id
+        }
+      end
+    end
+  end
+end

data/lib/notion_to_md/support/metadata_properties.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+class NotionToMd
+  module Support
+    # === NotionToMd::Support::MetadataProperties
+    #
+    # Mixin module providing convenience accessors for Notion page or
+    # database metadata. It extracts common properties (id, title, timestamps,
+    # cover, icon, etc.) from the `metadata` hash returned by the Notion API.
+    #
+    # When included, this module delegates `#properties` to the `metadata`
+    # attribute of the including class.
+    #
+    # @example Include in a model
+    #   class Page
+    #     include NotionToMd::Support::MetadataProperties
+    #     attr_reader :metadata
+    #   end
+    #
+    #   page = Page.new(metadata: notion_page_hash)
+    #   page.title # => "My Notion Page"
+    #
+    # @see NotionToMd::MetadataType
+    module MetadataProperties
+      def self.included(base)
+        base.extend Forwardable
+        base.def_delegators :metadata, :properties
+      end
+
+      # @return [String] The Notion record ID.
+      def id
+        metadata[:id]
+      end
+
+      # Extract the page or database title.
+      #
+      # @return [String] Plain text concatenated from `title` property.
+      def title
+        title_list =
+          metadata[:title] ||
+          metadata.dig(:properties, :Name, :title) ||
+          metadata.dig(:properties, :title, :title)
+
+        title_list.inject('') do |acc, slug|
+          acc + slug[:plain_text]
+        end
+      end
+
+      # @return [Time] Creation timestamp.
+      def created_time
+        metadata[:created_time]
+      end
+
+      # @return [String, nil] Object type of creator.
+      def created_by_object
+        metadata.dig(:created_by, :object)
+      end
+
+      # @return [String, nil] ID of creator.
+      def created_by_id
+        metadata.dig(:created_by, :id)
+      end
+
+      # @return [Time] Last edited timestamp.
+      def last_edited_time
+        metadata[:last_edited_time]
+      end
+
+      # @return [String, nil] Object type of last editor.
+      def last_edited_by_object
+        metadata.dig(:last_edited_by, :object)
+      end
+
+      # @return [String, nil] ID of last editor.
+      def last_edited_by_id
+        metadata.dig(:last_edited_by, :id)
+      end
+
+      # @return [String] Public URL of the record.
+      def url
+        metadata[:url]
+      end
+
+      # @return [Boolean] Whether the record is archived.
+      def archived
+        metadata[:archived]
+      end
+
+      # Extract the cover image URL, from either external or file source.
+      #
+      # @return [String, nil] Cover URL or nil if not present.
+      def cover
+        MetadataType.external(metadata[:cover]) ||
+          MetadataType.file(metadata[:cover])
+      end
+
+      # Extract the icon (emoji, external, or file).
+      #
+      # @return [String, nil] Icon value or nil if not present.
+      def icon
+        MetadataType.emoji(metadata[:icon]) ||
+          MetadataType.external(metadata[:icon]) ||
+          MetadataType.file(metadata[:icon])
+      end
+    end
+  end
+end

data/lib/notion_to_md/support/pagination.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class NotionToMd
+  module Support
+    ##
+    # The Pagination module provides a helper for iterating through paginated
+    # Notion API responses.
+    #
+    # Many Notion API endpoints (e.g., `block_children`, `database_query`) return
+    # a limited set of results and include `has_more` and `next_cursor` fields.
+    # This module encapsulates the common logic to repeatedly fetch all pages
+    # until no more results are available.
+    #
+    # @example Paginate through all blocks of a page
+    #   include NotionToMd::Support::Pagination
+    #
+    #   all_blocks = paginate do |cursor|
+    #     notion_client.block_children(
+    #       block_id: "xxxx-xxxx",
+    #       start_cursor: cursor
+    #     )
+    #   end
+    #
+    #   all_blocks.each { |block| puts block.type }
+    #
+    module Pagination
+      ##
+      # Iterates through all pages of a paginated Notion API response.
+      #
+      # The given block is called with the current cursor (or `nil` for the
+      # first call). It must return a response object that responds to
+      # `results`, `has_more`, and `next_cursor`.
+      #
+      # @yieldparam [String, nil] cursor the current cursor to start fetching from
+      # @yieldreturn [Object] a response object containing `results`, `has_more`, and `next_cursor`
+      # @return [Array] a flat array of all accumulated results from each page
+      def paginate
+        results = []
+        cursor  = nil
+
+        loop do
+          resp = yield(cursor)
+
+          results.concat(resp.results)
+
+          break unless resp.has_more && resp.next_cursor
+
+          cursor = resp.next_cursor
+        end
+
+        results
+      end
+    end
+  end
+end

data/lib/notion_to_md/support/yaml_sanitizer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+class NotionToMd
+  module Support
+    # === NotionToMd::Support::YamlSanitizer
+    #
+    # Provides helpers to sanitize values before inserting them into
+    # YAML frontmatter. This prevents syntax errors when values contain
+    # characters that YAML treats specially (e.g. colons, dashes).
+    #
+    # @example Escape a simple value
+    #   include NotionToMd::Support::YamlSanitizer
+    #
+    #   escape_frontmatter_value("Hello World")
+    #   # => "Hello World"
+    #
+    # @example Escape a value containing a colon
+    #   escape_frontmatter_value("Title: Subtitle")
+    #   # => "\"Title: Subtitle\""
+    #
+    # @example Escape a value containing dash + space
+    #   escape_frontmatter_value("- item")
+    #   # => "\"- item\""
+    #
+    module YamlSanitizer
+      # Escape a frontmatter value if it contains a colon (`:`) followed by
+      # a space, or a dash followed by a space (`- `). Wraps the string in
+      # double quotes and escapes any embedded quotes.
+      #
+      # @param value [String] The raw value to escape.
+      # @return [String] A safe string suitable for inclusion in YAML frontmatter.
+      def escape_frontmatter_value(value)
+        if value.match?(/: |-\s/)
+          # Escape embedded double quotes to keep valid YAML
+          "\"#{value.gsub('"', '\"')}\""
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/notion_to_md/text.rb

@@ -1,12 +1,39 @@
 # frozen_string_literal: true
 
 class NotionToMd
+  # === NotionToMd::Text
+  #
+  # Utility class to render inline Notion text elements into Markdown.
+  # Used by {NotionToMd::Blocks::Renderer} when processing `rich_text` arrays.
+  #
+  # Supported types:
+  # * `text` → plain text
+  # * `equation` → LaTeX inline math, wrapped as `$`…`$`
+  #
+  # @example Render plain text
+  #   NotionToMd::Text.text({ plain_text: "Hello" })
+  #   # => "Hello"
+  #
+  # @example Render an inline equation
+  #   NotionToMd::Text.equation({ plain_text: "E=mc^2" })
+  #   # => "$`E=mc^2`$"
+  #
+  # @see NotionToMd::Blocks::Renderer
+  # @see NotionToMd::TextAnnotation
   class Text
     class << self
+      # Render a plain text element.
+      #
+      # @param text [Hash] A Notion text object with key `:plain_text`.
+      # @return [String] The raw text.
       def text(text)
         text[:plain_text]
       end
 
+      # Render an inline equation element.
+      #
+      # @param text [Hash] A Notion text object with key `:plain_text`.
+      # @return [String] Inline math expression wrapped with `$...$`.
       def equation(text)
         "$`#{text[:plain_text]}`$"
       end

data/lib/notion_to_md/text_annotation.rb

@@ -1,37 +1,69 @@
 # frozen_string_literal: true
 
 class NotionToMd
-  ##
-  # Append the text type:
-  # * italic: boolean,
-  # * bold: boolean,
-  # * striketrough: boolean,
-  # * underline: boolean,
-  # * code: boolean,
-  # * color: string NOT_SUPPORTED
-
+  # === NotionToMd::TextAnnotation
+  #
+  # Utility class to wrap text with Markdown (or HTML) syntax
+  # corresponding to Notion's text annotations.
+  #
+  # Supported annotations:
+  # * `italic` → `*text*`
+  # * `bold` → `**text**`
+  # * `strikethrough` → `~~text~~`
+  # * `underline` → `<u>text</u>` (HTML, since Markdown does not support underline)
+  # * `code` → `` `text` ``
+  # * `color` → (not supported, returns text as-is)
+  #
+  # @example Apply bold and italic
+  #   NotionToMd::TextAnnotation.bold("Hello")          # => "**Hello**"
+  #   NotionToMd::TextAnnotation.italic("World")        # => "*World*"
+  #
+  # @example Apply underline
+  #   NotionToMd::TextAnnotation.underline("Note")      # => "<u>Note</u>"
+  #
+  # @see NotionToMd::Blocks::Renderer
   class TextAnnotation
     class << self
+      # Apply italic annotation.
+      # @param text [String]
+      # @return [String]
       def italic(text)
         "*#{text}*"
       end
 
+      # Apply bold annotation.
+      # @param text [String]
+      # @return [String]
       def bold(text)
         "**#{text}**"
       end
 
+      # Apply strikethrough annotation.
+      # @param text [String]
+      # @return [String]
       def strikethrough(text)
         "~~#{text}~~"
       end
 
+      # Apply underline annotation (HTML).
+      # @param text [String]
+      # @return [String]
       def underline(text)
         "<u>#{text}</u>"
       end
 
+      # Apply inline code annotation.
+      # @param text [String]
+      # @return [String]
       def code(text)
         "`#{text}`"
       end
 
+      # Color annotation is not supported in Markdown.
+      # Currently returns text unchanged.
+      #
+      # @param text [String]
+      # @return [String]
       def color(text)
         text
       end

data/lib/notion_to_md/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class NotionToMd
-  VERSION = '2.5.1'
+  VERSION = '3.0.0.beta1'
 end

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