notion_to_md 2.5.0 → 3.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4137f1edccac5aceec8f5195beb513019ec2ad84c52c5495a1d9842098dd2b4d
-  data.tar.gz: 51a57a1bf294d1c2cf3d0be1e24c693aa633c3c873fe864a9f2864fec6194ecb
+  metadata.gz: 2671f75f28373209f1846e06ed528f7adcc9d857da3fde4d1b0a5e43144c5850
+  data.tar.gz: 39c65f58ff9432277667c0c5c2597561d1b28d9252a7868ec2b8885d0e94e07a
 SHA512:
-  metadata.gz: 32e4a48a21d956bba91ba88d3aa3db0fdb6f7b0f54f55fcd44fdb07dd15842247ab6150b06f0f82a828ef8f0f632d158e746f54007afdd85357c41e75167b203
-  data.tar.gz: b9aa39eeb9b5cb105a8ebf48ca78fe4e88c0a9a7c013f63dc0057dc3adf0ffcfd0cbd2c72df87b83d5e5eafaaa9605e26a0c44f63852af4be9e87e37f752d6cc
+  metadata.gz: 3c1571b5b93eb39bccb66032db2296d84b1d02313a6098e3d0e0f03022bfbea5eb0d46b54ae20b7bed6a9a5d6e79721922623491b5b1b829060e08b09cb67114
+  data.tar.gz: 5eea9bf71539d0d6c66880c89a39950c42da4c67767d651b1e218ebb380539b27c5b3ed5f00c18c77a13f547db9edc21f3645bb66e4c3e6204d08b59085da0fa

data/README.md

@@ -1,113 +1,122 @@
+<img src="https://ik.imagekit.io/gxidvqvc9/noiton_to_md_logo_white_bg_-OiZSEkqY.png?updatedAt=1756209770491" width="150">
+
 # notion_to_md
-Notion Markdown Exporter in Ruby.
 
-The generated document is compliant with the [GitHub Flavored Markdown specification](https://github.github.com/gfm/).
+A Ruby library to export [Notion](https://www.notion.so/) pages and databases to Markdown.
+The output is fully compliant with the [GitHub Flavored Markdown specification](https://github.github.com/gfm/).
+
+[![Gem Version](https://badge.fury.io/rb/notion_to_md.svg)](https://badge.fury.io/rb/notion_to_md)
+[![CI](https://github.com/emoriarty/notion_to_md/actions/workflows/ci.yml/badge.svg)](https://github.com/emoriarty/notion_to_md/actions)
+
+> [!NOTE]
+> You are reading the documentation for the latest development branch.
+> For the stable **v2.x.x** documentation, see [the v2.x.x branch](https://github.com/emoriarty/notion_to_md/tree/v2.x.x).
 
 ## Installation
-Use gem to install.
+
+Install via RubyGems:
+
 ```bash
-$ gem install 'notion_to_md'
+gem install notion_to_md
 ```
 
-Or add it to the `Gemfile`.
+Or add it to your `Gemfile`:
+
 ```ruby
-# Gemfile
 gem 'notion_to_md'
 ```
 
-## Usage
-Before using the gem create an integration and generate a secret token. Check [notion getting started guide](https://developers.notion.com/docs/getting-started) to learn more.
-
-Pass the page id and secret token to the constructor and execute the `convert` method.
+### Beta version (3.0.0.beta1)
 
-```ruby
-require 'notion_to_md'
+If you want to try the **beta release**, install with the `--pre` flag:
 
-notion_converter = NotionToMd::Converter.new(page_id: 'b91d5...', token: 'secret_...')
-md = notion_converter.convert
+```bash
+gem install notion_to_md --pre
 ```
 
-Since v2.3 you can also use the convenient `convert` method from the root module.
+Or pin the beta in your Gemfile:
 
 ```ruby
-md = NotionToMd.convert(page_id: 'b91d5...', token: 'secret_...')
+gem "notion_to_md", "3.0.0.beta1"
 ```
 
-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.
+⚠️ This version is under active development. For stable usage, prefer the latest `2.x.x` release.
 
-```bash
-$ export NOTION_TOKEN=<secret_...>
-```
+
+## Quick Start
 
 ```ruby
-notion_converter = NotionToMd::Converter.new(page_id: 'b91d5...')
-md = notion_converter.convert
-# or
-md = NotionToMd.convert(page_id: 'b91d5...')
+# Convert a Notion page to Markdown
+md = NotionToMd.call(:page, id: 'b91d5...', token: ENV['NOTION_TOKEN'])
+File.write("page.md", md)
 ```
 
-And that's all. The `md` is a string variable containing the notion document formatted in markdown.
+## Usage
 
-### Callable
+Before using the gem, create a Notion integration and obtain a secret token.
+See the [Notion Getting Started Guide](https://developers.notion.com/docs/getting-started) for details.
 
-From version 2.5.0, the `call` method is also available. It's an alias for `convert`.
+### Pages
 
 ```ruby
-md = NotionToMd.call(page_id: 'b91d5...')
+md = NotionToMd.call(:page, id: 'b91d5...', token: 'secret_...')
+# or equivalently
+md = NotionToMd.convert(:page, id: 'b91d5...', token: 'secret_...')
 ```
 
-The `call` method also supports the passing of a block.
+`md` is a string containing the page content in Markdown format.
+
+### Databases
 
 ```ruby
-NotionToMd.call(page_id: 'b91d5...') { puts _1 }
+mds = NotionToMd.call(:database, id: 'b91d5...')
 ```
 
-## Blocks
+`mds` is an array of strings, one per page.
 
-Everything in a notion page body is a [block object](https://developers.notion.com/reference/block#block-object-keys). Therefore, not every type can be mapped to Markdown. Below there's a list of current supported blocks types.
+### Environment Variables
 
-* `paragraph`
-* `heading_1`
-* `heading_2`
-* `heading_3`
-* `bulleted_list_item`
-* `numbered_list_item` (supported since v2.3, in previous versions is displayed as `bulleted_list_item`)
-* `to_do`
-* `image`
-* `bookmark`
-* `callout`
-* `quote`
-* `divider`
-* `table`
-* `embed`
-* `code`
-* `link_preview`
-* `file`
-* `pdf`
-* `video`
+If your token is stored in `NOTION_TOKEN`, you don’t need to pass it explicitly:
 
-### Nested blocks
+```bash
+export NOTION_TOKEN=<secret_...>
+```
 
-Starting with v2, nested blocks are supported. The permitted blocks to have children are:
+```ruby
+md = NotionToMd.call(:page, id: 'b91d5...')
+```
+
+## Supported Blocks
 
-* `paragraph`
-* `bulleted_list_item`
-* `numbered_list_item`
-* `to_do`
+Everything in Notion is a [block object](https://developers.notion.com/reference/block#block-object-keys).
 
-## Front matter
+| Block type                        | Nested children supported? |
+|-----------------------------------|----------------------------|
+| paragraph                         | ✅ |
+| heading_1 / heading_2 / heading_3 | ❌ |
+| bulleted_list_item                | ✅ |
+| numbered_list_item                | ✅ |
+| to_do                             | ✅ |
+| image, file, pdf, video           | ❌ |
+| bookmark, embed, link_preview     | ❌ |
+| callout                           | ❌ |
+| quote                             | ❌ |
+| divider                           | ❌ |
+| table                             | ❌ |
+| code                              | ❌ |
+| equation                          | ❌ |
 
-From version 0.2.0, notion_to_md supports front matter in markdown files.
+## Front Matter
 
-By default, the front matter section is not included to the document. To do so, provide the `:frontmatter` option set to `true` to `convert` method.
+By default, front matter is **disabled**. Enable it with:
 
 ```ruby
-NotionToMd::Converter.new(page_id: 'b91d5...').convert(frontmatter: tue)
-# or
-NotionToMd.convert(page_id: 'b91d5...', frontmatter: true) # Since v2.3
+NotionToMd.call(:page, id: 'b91d5...', frontmatter: true)
 ```
 
-Default notion [properties](https://developers.notion.com/reference/page#all-pages) are page `id`, `title`, `created_time`, `last_edited_time`, `icon`, `archived` and `cover`.
+### Examples
+
+**Default properties:**
 
 ```yml
 ---
@@ -125,9 +134,7 @@ last_edited_by_object: user
 ---
 ```
 
-In addition to default properties, custom properties are also supported.
-Custom properties name is [parameterized](https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-parameterize) and [underscorized](https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-underscore) before added to front matter.
-For example, two properties named `Multiple Options` and `Tags` will be transformed to `multiple_options` and `tags`, respectively.
+**Custom properties:**
 
 ```yml
 ---
@@ -136,25 +143,30 @@ multiple_options: option1, option2
 ---
 ```
 
-The supported property types are:
+Custom property names are [parameterized](https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-parameterize) and [underscored](https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-underscore).
+
+Supported property types:
+
+- `number`
+- `select`
+- `multi_select`
+- `date`
+- `people`
+- `files`
+- `checkbox`
+- `url`
+- `email`
+- `phone_number`
+- `rich_text` (plain text only)
 
-* `number`
-* `select`
-* `multi_select`
-* `date`
-* `people`
-* `files`
-* `checkbox`
-* `url`
-* `email`
-* `phone_number`
-* `rich_text`, supported but in plain text
+> [!NOTE]
+> Advanced types such as `formula`, `relation`, and `rollup` are **not supported**.
+> See the [Notion property value docs](https://developers.notion.com/reference/property-value-object#all-property-values).
 
-Advanced types like `formula`, `relation` and `rollup` are not supported.
+## Development
 
-Check notion documentation about [property values](https://developers.notion.com/reference/property-value-object#all-property-values) to know more.
+Run the test suite with:
 
-## Test
 ```bash
 rspec
 ```

data/lib/notion_to_md/blocks/block.rb

@@ -4,37 +4,55 @@ require 'forwardable'
 
 class NotionToMd
   module Blocks
+    # === NotionToMd::Blocks::Block
+    #
+    # Represents a Notion block and provides functionality
+    # to convert it (and its children) into Markdown.
+    #
+    # A block corresponds to a `Notion::Messages::Message`
+    # returned by the [notion-ruby-client](https://github.com/orbit-love/notion-ruby-client).
+    #
+    # @example Convert a block to Markdown
+    #   block = NotionToMd::Blocks::Block.new(block: notion_message, children: [])
+    #   puts block.to_md
+    #
+    # @see NotionToMd::Blocks::Renderer
     class Block
       extend Forwardable
 
-      attr_reader :block, :children
+      # @return [Notion::Messages::Message] The Notion API block data.
+      attr_reader :block
 
+      # @return [Array<NotionToMd::Blocks::Block>] The nested child blocks.
+      attr_reader :children
+
+      # Delegate the `#type` method to the underlying `block`.
       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.
-      # children::
-      #   An array of NotionToMd::Block::Block objects.
-      #
-      # === Returns
-      # A Block object.
+      # Initialize a new block wrapper.
       #
+      # @param block [Notion::Messages::Message]
+      #   A Notion block message from the Notion API.
+      # @param children [Array<NotionToMd::Blocks::Block>]
+      #   Nested blocks belonging to this block.
       def initialize(block:, children: [])
         @block = block
         @children = children
       end
 
-      # === Parameters:
-      # tab_width::
-      #  The number of tabs used to indent the block.
+      # Convert the block (and its children) into Markdown.
+      #
+      # Uses {NotionToMd::Blocks::Renderer} to render
+      # the Markdown representation of the block.
+      #
+      # @param tab_width [Integer] The number of tabs used to indent nested blocks. Defaults to 0.
       #
-      # === Returns
-      # The current block (and its children) converted to a markdown string.
+      # @return [String, nil] The Markdown string, or `nil` if the block type is unsupported.
       #
+      # @see NotionToMd::Blocks::Renderer
       def to_md(tab_width: 0)
         block_type = block.type.to_sym
-        md = Types.send(block_type, block[block_type]) + newline
+        md = Renderer.send(block_type, block[block_type]) + newline
         md + build_nested_blocks(tab_width + 1)
       rescue NoMethodError
         Logger.info("Unsupported block type: #{block_type}")
@@ -43,21 +61,35 @@ class NotionToMd
 
       protected
 
+      # @return [String] Two newlines separating blocks.
       def newline
         "\n\n"
       end
 
+      # Build the Markdown for all nested blocks.
+      #
+      # @param tab_width [Integer] The indentation level.
+      # @return [String]
       def build_nested_blocks(tab_width)
         mds = markdownify_children(tab_width).compact
         indent_children(mds, tab_width).join
       end
 
+      # Render children blocks into Markdown.
+      #
+      # @param tab_width [Integer] The indentation level.
+      # @return [Array<String, nil>] Markdown strings (or nil if unsupported).
       def markdownify_children(tab_width)
         children.map do |nested_block|
           nested_block.to_md(tab_width: tab_width)
         end
       end
 
+      # Indent the Markdown output of children by `tab_width`.
+      #
+      # @param mds [Array<String>] Markdown strings.
+      # @param tab_width [Integer] The indentation level.
+      # @return [Array<String>] Indented Markdown strings.
       def indent_children(mds, tab_width)
         mds.map do |md|
           "#{"\t" * tab_width}#{md}"

data/lib/notion_to_md/blocks/factory.rb

@@ -2,22 +2,59 @@
 
 class NotionToMd
   module Blocks
+    # === NotionToMd::Blocks::Factory
+    #
+    # Factory class for instantiating the correct block wrapper class
+    # depending on the Notion block type.
+    #
+    # This is used by {NotionToMd::Page::Builder} when traversing Notion
+    # blocks returned from the API.
+    #
+    # @example Build a block instance from a Notion API message
+    #   block = notion_client.block_children(block_id: "xxxx").results.first
+    #   instance = NotionToMd::Blocks::Factory.build(block: block)
+    #   instance # => NotionToMd::Blocks::Block subclass
+    #
+    # @see NotionToMd::Blocks::Block
+    # @see NotionToMd::Page::Builder
     class Factory
-      def self.build(block:, children: [])
-        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)
+      class << self
+        # Build the appropriate block wrapper.
+        #
+        # @param block [Notion::Messages::Message]
+        #   A Notion block message from the API.
+        # @param children [Array<NotionToMd::Blocks::Block>]
+        #   Optional nested block instances.
+        #
+        # @return [NotionToMd::Blocks::Block]
+        #   A block instance of the corresponding subclass:
+        #
+        #   * {TableBlock} for `:table`
+        #   * {TableRowBlock} for `:table_row`
+        #   * {BulletedListItemBlock} for `:bulleted_list_item`
+        #   * {NumberedListItemBlock} for `:numbered_list_item`
+        #   * {ToDoListItemBlock} for `:to_do`
+        #   * {NotionToMd::Blocks::Block} for all others
+        #
+        # @note Custom block classes must implement `#to_md`.
+        def call(block:, children: [])
+          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
         end
+
+        alias build call
       end
     end
   end

data/lib/notion_to_md/blocks/normalizer.rb

@@ -2,62 +2,143 @@
 
 class NotionToMd
   module Blocks
+    # === NotionToMd::Blocks::Normalizer
+    #
+    # Responsible for normalizing sequences of adjacent blocks of the same type
+    # into grouped list blocks (e.g., multiple consecutive `bulleted_list_item`
+    # blocks into a single `BulletedListBlock`).
+    #
+    # This ensures Markdown output has proper list structures instead of
+    # repeated, ungrouped items.
+    #
+    # @example Normalize a sequence of blocks
+    #   blocks = [
+    #     BulletedListItemBlock.new(block: block1),
+    #     BulletedListItemBlock.new(block: block2),
+    #     NotionToMd::Blocks::Block.new(block: block3)
+    #   ]
+    #
+    #   normalized = NotionToMd::Blocks::Normalizer.normalize(blocks: blocks)
+    #   # => [BulletedListBlock(children: [..]), Block(..)]
+    #
+    # @see NotionToMd::Blocks::Block
+    # @see NotionToMd::Blocks::Factory
     class Normalizer
-      # === Parameters
-      # blocks::
-      #  An array of NotionToMd::Blocks::Block.
-      #
-      def self.normalize(blocks:)
-        new(blocks: blocks).normalize
+      class << self
+        # Normalize a list of blocks.
+        #
+        # @param blocks [Array<NotionToMd::Blocks::Block>]
+        #   Raw blocks to normalize.
+        #
+        # @return [Array<NotionToMd::Blocks::Block>]
+        #   Normalized blocks where consecutive list items are grouped.
+        def call(blocks:)
+          new(blocks: blocks).call
+        end
       end
 
+      # @return [Array<NotionToMd::Blocks::Block>]
+      #   The mutable, normalized block list.
       attr_reader :normalized_blocks
 
+      # Create a new normalizer.
+      #
+      # @param blocks [Array<NotionToMd::Blocks::Block>]
+      #   Raw blocks to normalize.
       def initialize(blocks:)
         @normalized_blocks = blocks.dup
       end
 
-      def normalize
+      # Run normalization for all supported types:
+      #
+      # * `:bulleted_list_item`
+      # * `:numbered_list_item`
+      # * `:to_do`
+      #
+      # @return [Array<NotionToMd::Blocks::Block>]
+      #   The final normalized block array.
+      def call
         normalize_for :bulleted_list_item
         normalize_for :numbered_list_item
         normalize_for :to_do
+        normalized_blocks
       end
 
+      # Normalize consecutive blocks of the given +type+ into a single grouped block,
+      # while preserving original order for everything else.
+      #
+      # The algorithm scans left-to-right, buffering runs of +type+. When a different
+      # type appears (or we reach the end), the buffered run is flushed as a grouped
+      # block and the non-matching block is appended as-is.
       def normalize_for(type)
         new_blocks = []
 
         normalized_blocks.each do |block|
-          if block.type.to_sym == type
+          if block_of_type?(block, type)
+            # Accumulate consecutive blocks of the target 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?
+            # A different type breaks the run:
+            # 1) flush the buffered run as a single grouped block
+            # 2) append the current (non-matching) block
+            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?
+        # If the sequence ended with a run of the target type, it hasn’t been
+        # emitted yet—flush it now.
+        flush_blocks_to_normalize_into(new_blocks, type)
 
+        # Replace the working set with the newly normalized list
         normalized_blocks.replace(new_blocks)
       end
 
       private
 
+      # @api private
+      # @param block [NotionToMd::Blocks::Block]
+      # @param type [Symbol]
+      # @return [Boolean] true if the block matches the given type.
+      def block_of_type?(block, type)
+        block.type.to_sym == type
+      end
+
+      # @api private
+      # Flush accumulated blocks to the new array as a grouped block.
+      #
+      # @param new_blocks [Array<NotionToMd::Blocks::Block>]
+      # @param type [Symbol]
+      # @return [void]
+      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
+
+      # @api private
+      # Create a grouped block and reset buffer.
+      #
+      # @param type [Symbol]
+      # @return [NotionToMd::Blocks::Block]
       def new_block_and_reset_blocks_to_normalize(type)
         new_block = new_block_for(type, blocks_to_normalize)
         @blocks_to_normalize = []
         new_block
       end
 
+      # @api private
+      # @return [Array<NotionToMd::Blocks::Block>]
       def blocks_to_normalize
         @blocks_to_normalize ||= []
       end
 
+      # @api private
+      # Create a wrapper block (list) depending on type.
+      #
+      # @param type [Symbol]
+      # @param children [Array<NotionToMd::Blocks::Block>]
+      # @return [NotionToMd::Blocks::Block]
       def new_block_for(type, children)
         case type
         when :bulleted_list_item

data/lib/notion_to_md/blocks/numbered_list_item_block.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative './bulleted_list_item_block'
-
 class NotionToMd
   module Blocks
     class NumberedListItemBlock < BulletedListItemBlock
@@ -15,7 +13,7 @@ class NotionToMd
       # 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 = Renderer.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}")

data/lib/notion_to_md/blocks/{types.rb → renderer.rb}

@@ -2,7 +2,23 @@
 
 class NotionToMd
   module Blocks
-    class Types
+    # === NotionToMd::Blocks::Renderer
+    #
+    # Stateless renderer for individual Notion block payloads into
+    # GitHub-Flavored Markdown (GFM). Each public class method expects a
+    # simplified block hash (already focused on the inner block content)
+    # and returns a Markdown string.
+    #
+    # This class is used by {NotionToMd::Blocks::Block#to_md}.
+    #
+    # @example Render a paragraph block
+    #   md = NotionToMd::Blocks::Renderer.paragraph({ rich_text: [{ type: :text, plain_text: "Hello" }] })
+    #   # => "Hello"
+    #
+    # @see NotionToMd::Blocks::Block
+    # @see NotionToMd::Blocks::Text
+    # @see NotionToMd::Blocks::TextAnnotation
+    class Renderer
       class << self
         def paragraph(block)
           return blank if block[:rich_text].empty?
@@ -111,6 +127,10 @@ class NotionToMd
           file(block)
         end
 
+        def equation(block)
+          "$$#{block['expression']}$$"
+        end
+
         private
 
         def convert_table_row(cells)

data/lib/notion_to_md/blocks/to_do_list_item_block.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative './bulleted_list_item_block'
-
 class NotionToMd
   module Blocks
     class ToDoListItemBlock < BulletedListItemBlock