notion_to_md 2.5.1 → 3.0.0.beta2

data/lib/notion_to_md/page.rb

@@ -3,135 +3,109 @@
 class NotionToMd
   # === NotionToMd::Page
   #
-  # This class is responsible for representing a Notion page.
+  # Represents a Notion page and allows conversion to Markdown.
+  #
+  # A `Page` object encapsulates the page metadata, its content blocks,
+  # and optionally the frontmatter section.
+  #
+  # @example Convert a Notion page to Markdown
+  #   notion_client = Notion::Client.new(token: ENV["NOTION_TOKEN"])
+  #   page = NotionToMd::Page.call(id: "xxxx-xxxx", notion_client: notion_client, frontmatter: true)
+  #   File.write("page.md", page.to_s)
+  #
   class Page
-    include Helpers::YamlSanitizer
-
-    attr_reader :page, :blocks
-
-    def initialize(page:, blocks:)
-      @page = page
-      @blocks = blocks
-    end
-
-    def title
-      title_list = page.dig(:properties, :Name, :title) || page.dig(:properties, :title, :title)
-      title_list.inject('') do |acc, slug|
-        acc + slug[:plain_text]
+    include Support::MetadataProperties
+    include Support::Frontmatter
+
+    class << self
+      # Build a new {Page} from the Notion API.
+      #
+      # @param id [String] The Notion page ID.
+      # @param notion_client [Notion::Client] The Notion API client.
+      # @param frontmatter [Boolean] Whether to include frontmatter in the output.
+      #
+      # @return [NotionToMd::Page] a new page instance.
+      #
+      # @see .build
+      def call(id:, notion_client:, frontmatter: false)
+        new(id: id, notion_client: notion_client, frontmatter: frontmatter).call
       end
-    end
 
-    def cover
-      PageProperty.external(page[:cover]) || PageProperty.file(page[:cover])
+      # @!method build(...)
+      #   Alias of {.call}.
+      alias build call
     end
 
-    def icon
-      PageProperty.emoji(page[:icon]) || PageProperty.external(page[:icon]) || PageProperty.file(page[:icon])
-    end
+    # @return [String] The Notion id page.
+    attr_reader :id
 
-    def id
-      page[:id]
-    end
-
-    def created_time
-      page['created_time']
-    end
+    # @param jNotion::Client] The Notion API client.
+    attr_reader :notion_client
 
-    def created_by_object
-      page.dig(:created_by, :object)
-    end
+    # @param [Hash] The page configuration options.
+    attr_reader :config
 
-    def created_by_id
-      page.dig(:created_by, :id)
-    end
+    # @return [Object] The metadata associated with the page.
+    attr_reader :metadata
 
-    def last_edited_time
-      page['last_edited_time']
-    end
+    # @return [Array<#to_md>] The list of child blocks belonging to the page.
+    attr_reader :children
 
-    def last_edited_by_object
-      page.dig(:last_edited_by, :object)
-    end
+    # @!method blocks
+    #   Alias for {#children}.
+    alias blocks children
 
-    def last_edited_by_id
-      page.dig(:last_edited_by, :id)
+    # Initialize a new Page.
+    #
+    # @param id [String] The Notion page ID.
+    # @param notion_client [Notion::Client] The Notion API client.
+    # @param frontmatter [Boolean] Whether to include frontmatter in the Markdown output.
+    def initialize(id:, notion_client:, frontmatter: false)
+      @id = id
+      @notion_client = notion_client
+      @config = { frontmatter: frontmatter }
     end
 
-    def url
-      page[:url]
+    # Fetch page data and child blocks from the Notion API.
+    #
+    # This method populates the page's metadata and children by making API calls
+    # to retrieve the page content and its nested blocks.
+    #
+    # @return [NotionToMd::Page] returns self to allow method chaining.
+    def call
+      @metadata = notion_client.page(page_id: id)
+      @children = Builder.call(block_id: id, notion_client: notion_client)
+      self
     end
 
-    def archived
-      page[:archived]
-    end
+    alias build call
 
+    # Render the body of the page (Markdown representation of its blocks).
+    #
+    # @return [String] The Markdown content of the page.
     def body
       @body ||= blocks.map(&:to_md).compact.join
     end
 
-    def frontmatter
-      @frontmatter ||= <<~CONTENT
-        ---
-        #{props.to_a.map do |k, v|
-            "#{k}: #{v}"
-          end.join("\n")}
-        ---
-      CONTENT
+    # Whether the page includes frontmatter.
+    #
+    # @return [Boolean]
+    def frontmatter?
+      config[:frontmatter]
     end
 
-    def props
-      @props ||= custom_props.deep_merge(default_props)
+    # Render the page as a Markdown string, including optional frontmatter.
+    #
+    # @return [String] The Markdown document.
+    def to_s
+      <<~MD
+        #{frontmatter if frontmatter?}
+        #{body}
+      MD
     end
 
-    def custom_props
-      @custom_props ||= filtered_custom_properties
-    end
-
-    # rubocop:disable Metrics/MethodLength
-    def default_props
-      @default_props ||= {
-        '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
-    # 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
+    # @!method to_md
+    #   Alias for {#to_s}.
+    alias to_md to_s
   end
 end

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
+
+      # 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
+
+      private
+
+      # 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' => metadata['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,102 @@
+# 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
+
+      # 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.beta2'
 end