notion_to_html 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5c9fc0703ad943d3ec964a2c1f9eb69750dcbbe49fbd271f2f2f213d290d1e5e
+  data.tar.gz: dfdd2d0f9738e991d90d083898d288dcb0b7019a9415fc82f9d83773ea030262
+SHA512:
+  metadata.gz: fe05f80c2b3e452639a0019ad6d2f215e6953b05e13434cc390b0827a1a3294db07e8f71fac9992ec2cc8d57b8f87ec02e27191d98690c1c29abc91a2a108548
+  data.tar.gz: dd192dd44381b12863c88470fe48b4811b1b3fa57722ae6e8cd1ce2c72daa12ac4ea42207d841fa678cfb8dc91315f3e2e129ab31b38c32fba0bd7ce1301b1a2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Guillermo Aguirre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,205 @@
+# NotionToHtml
+
+NotionToHtml is a Ruby gem designed to integrate Notion with Ruby applications. It provides a set of tools for rendering Notion pages and blocks, allowing you to maintain a database of pages in Notion while rendering them real time in you application with ease.
+
+Now you can use Notion to publish your pages directly to your Ruby web page with one click.
+
+## Table of Contents
+
+- [NotionToHtml](#notiontohtml)
+- [Table of Contents](#table-of-contents)
+- [About](#about)
+- [Installation](#installation)
+- [Dependencies](#dependencies)
+- [Setup](#setup)
+  - [Notion Integration](#notion-integration)
+    - [Create your integration in Notion](#create-your-integration-in-notion)
+    - [Get your API secret](#get-your-api-secret)
+    - [Give your integration page permissions](#give-your-integration-page-permissions)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Rendering](#rendering)
+    - [Pages](#pages)
+    - [Specific Page](#specific-page)
+    - [Customizing styles](#customizing-styles)
+    - [Overriding default styles](#overriding-default-styles)
+  - [Querying](#querying)
+    - [Filtering](#filtering)
+    - [Sorting](#sorting)
+- [Examples](#examples)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
+## About
+
+NotionToHtml allows you to seamlessly integrate Notion pages and blocks into your Ruby application. It provides a set of renderers for various Notion block types, including headings, paragraphs, images, and more. With NotionToHtml, you can easily display and format Notion content in your views.
+
+You just need to create a database in Notion, integrate it and start writing!
+
+## Installation
+
+Add the gem to your application's Gemfile:
+```bash
+bundle add notion_to_html
+```
+Or install it yourself as:
+```bash
+gem install notion_to_html
+```
+## Dependencies
+NotionToHtml uses [tailwindcss](https://tailwindcss.com/) classes to define a default styling that mimics Notion's own styling, so make sure to inlcude it in your application.
+If you wish to use something else you can always override the default styling provided, see []() for more details.
+
+## Setup
+This gem is currently very opinionated on how it expects the Notion database to be defined. If you wish to customize this you can override the methods defined in [NotionToHtml::Service](./lib/notion_to_html/service.rb).
+
+By default the database should have the following structure:
+![Database structure](/docs/images/database_structure.png)
+
+- _name, description & slug_ as Text
+- tags as Multi-Select
+- public as Checkbox
+- published as Date
+
+Once you have the database created you will have to setup a Notion Integration, so the Notion API can communicate with your database. For this you will have to follow the [Create Your Integration In Notion](https://developers.notion.com/docs/create-a-notion-integration#create-your-integration-in-notion) tutorial.
+
+If you wish to just quickly set it up, you can follow the relevant steps below, which are taken from that tutorial.
+
+### Notion Integration
+#### Create your integration in Notion
+The first step to building any integration (internal or public) is to create a new integration in Notion’s integrations dashboard: <https://www.notion.com/my-integrations>.
+1. Click `+ New Integration`.
+![Create integration](/docs/images/new_integration.png)
+2. Enter the integration name and select the associated workspace for the new integration.
+![Select workspace](/docs/images/new_integration_select_workspace.png)
+
+#### Get your API secret
+API requests require an API secret to be successfully authenticated.
+1. Visit the Configuration tab to get your integration’s API secret (or “Internal Integration Secret”).
+![API secret](/docs/images/get_api_key.png)
+**Remember to keep your API secret a secret!**
+Any value used to authenticate API requests should always be kept secret. Use environment variables and avoid committing sensitive data to your version control history.
+If you do accidentally expose it, remember to “refresh” your secret.
+
+#### Give your integration page permissions
+The database that we’re about to create will be added to a parent Notion page in your workspace. For your integration to interact with the page, it needs explicit permission to read/write to that specific Notion page.
+
+To give the integration permission, you will need to:
+1. Go to the page with the database you created above.
+2. Click on the ... More menu in the top-right corner of the page.
+3. Scroll down to + Add Connections.
+4. Search for your integration and select it.
+5. Confirm the integration can access the page and all of its child pages.
+![alt text](/docs/images/permissions.gif)
+6. You can then limit the integrations permission to just `Read Contents`:
+![alt text](/docs/images/permissions.png)
+
+Now you're finally ready to config the gem!
+
+### Configuration
+To configure NotionToHtml, you need to set up your Notion API token and database ID.
+If you're using Rails add an initializer file in your Rails application, such as `config/initializers/notion_to_html.rb`, and include the following configuration block:
+```ruby
+NotionToHtml.configure do |config|
+  config.notion_api_token = 'NOTION_API_TOKEN'
+  config.notion_database_id = 'NOTION_DATABASE_ID'
+end
+```
+
+To get these values:
+1. The NOTION_API_TOKEN is the same one from [the setup](#get-your-api-secret).
+2. To get the NOTION_DATABASE_ID, locate the 32-character string at the end of the page’s URL.
+    ```bash
+    https://www.notion.so/myworkspace/a8aec43384f447ed84390e8e42c2e089?v=...
+                                      |--------- Database ID --------|
+    ```
+
+**Remember to keep these values secret!**
+
+Now you should be all setup!
+
+## Usage
+### Rendering
+#### Pages
+To get and render a preview of the pages of your database:
+```ruby
+<% NotionToHtml::Service.get_pages.each do |page| %>
+  <%= article.formatted_published_at %>
+  <%= article.id %>
+  <%= article.formatted_title %>
+  <%= article.formatted_description %>
+<% end %>
+```
+#### Specific Page
+To get and render a specific page:
+```ruby
+<% page = NotionToHtml::Service.get_page(page_id) %>
+<%= page.formatted_title %>
+<%= page.formatted_published_at %>
+<% page.formatted_blocks.each do |block| %>
+  <%= block %>
+<% end %>
+```
+#### Customizing styles
+NotionToHtml ships with default css classes for each supported block. You can add your own set of styling on top by specifying the `class:` option when calling the formatter:
+```ruby
+NotionToHtml::Service.get_page(page_id)
+  .formatted_title(class: 'text-4xl md:text-5xl font-bold')
+```
+You can also specify classes for each type of supported block like this:
+```ruby
+NotionToHtml::Service.get_page(page_id).formatted_blocks(
+  paragraph: 'text-lg', 
+  heading_1: 'text-3xl md:text-4xl font-bold', 
+  heading_2: 'text-white', 
+  heading_3: 'font-bold', 
+  quote: 'italic', 
+)
+```
+#### Overriding default styles
+If you feel like you want a clean slate regarding styling you can override the provided default styles by setting the `override_class` option to `true`:
+```ruby
+NotionToHtml::Service.get_page(page_id)
+  .formatted_title(class: 'font-bold', override_class: true)
+```
+It also works for `formatted_blocks`:
+```ruby
+NotionToHtml::Service.get_page(page_id)
+  .formatted_blocks(
+    paragraph: { class: 'text-lg', override_class: true }, 
+    quote: 'italic' 
+)
+```
+### Querying
+By default the `NotionToHtml::Service` is setup to follow the database structure sepcified above. This way it will only return pages that have been marked as `public`.
+
+#### Filtering
+You can filter the results by specifying a tag and/or a specific slug:
+```ruby
+NotionToHtml::Service.get_pages(tag: 'web', slug: 'test-slug')
+```
+#### Sorting
+The default sorting is by the `published` Date column in the database
+
+### Examples
+To see how the default renderings of the supported blocks look, go over to the [examples](/examples/).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/guillermoaguirre1@gmail.com/notion_to_html. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Notion::Rails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](/CODE_OF_CONDUCT.md).

data/lib/notion_to_html/base_block.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+# The NotionToHtml::BaseBlock class represents a block in a Notion page, handling its attributes and rendering.
+# This class processes the raw data of a block fetched from the Notion API and makes
+# it accessible through various attributes. It also provides methods to render formatted
+# output for different block types like paragraphs, headings, lists, quotes, and media.
+
+module NotionToHtml
+  class BaseBlock
+    include NotionToHtml::Renderers
+
+    # @return [String] the ID of the block.
+    attr_reader :id
+    # @return [String] the creation timestamp of the block.
+    attr_reader :created_time
+    # @return [String] the last edited timestamp of the block.
+    attr_reader :last_edited_time
+    # @return [String] the user who created the block.
+    attr_reader :created_by
+    # @return [String] the user who last edited the block.
+    attr_reader :last_edited_by
+    # @return [Hash] the parent of the block (e.g., page ID).
+    attr_reader :parent
+    # @return [Boolean] whether the block is archived.
+    attr_reader :archived
+    # @return [Boolean] whether the block has children.
+    attr_reader :has_children
+    # @return [String] the type of the block (e.g., 'paragraph', 'heading_1').
+    attr_reader :type
+    # @return [Hash] the properties of the block, specific to its type.
+    attr_reader :properties
+
+    # @return [Array<BaseBlock>] the children blocks of this block.
+    attr_accessor :children
+    # @return [Array<BaseBlock>] the sibling blocks of this block.
+    attr_accessor :siblings
+
+    # The list of block types that can be rendered.
+    BLOCK_TYPES = %w[
+      paragraph
+      heading_1
+      heading_2
+      heading_3
+      bulleted_list_item
+      numbered_list_item
+      quote
+      callout
+      code
+      image
+      embed
+      video
+    ].freeze
+
+    # Initializes a new BaseBlock object.
+    # @param data [Hash] The raw data of the block from the Notion API.
+    def initialize(data)
+      @id = data['id']
+      @created_time = data['created_time']
+      @last_edited_time = data['last_edited_time']
+      @created_by = data['created_by'] # TODO: handle user object
+      @last_edited_by = data['last_edited_by'] # TODO: handle user object
+      @parent = data['parent'] # TODO: handle page_id type
+      @archived = data['archived']
+      @has_children = data['has_children']
+      @children = []
+      @siblings = []
+      @type = data['type']
+      @properties = data[@type]
+    end
+
+    # Renders the block based on its type.
+    # @param options [Hash] Additional options for rendering the block.
+    # @return [String] The rendered block as HTML.
+    def render(options = {})
+      case @type
+      when 'paragraph'
+        render_paragraph(rich_text, class: options[:paragraph])
+      when 'heading_1'
+        render_heading_1(rich_text, class: options[:heading_1])
+      when 'heading_2'
+        render_heading_2(rich_text, class: options[:heading_2])
+      when 'heading_3'
+        render_heading_3(rich_text, class: options[:heading_3])
+      when 'table_of_contents'
+        render_table_of_contents
+      when 'bulleted_list_item'
+        render_bulleted_list_item(rich_text, @siblings, @children, 0, class: options[:bulleted_list_item])
+      when 'numbered_list_item'
+        render_numbered_list_item(rich_text, @siblings, @children, 0, class: options[:numbered_list_item])
+      when 'quote'
+        render_quote(rich_text, class: options[:quote])
+      when 'callout'
+        render_callout(rich_text, icon, class: options[:callout])
+      when 'code'
+        render_code(rich_text, class: options[:code], language: @properties['language'])
+      when 'image', 'embed'
+        render_image(*multi_media, class: options[:image])
+      when 'video'
+        render_video(*multi_media, class: options[:video])
+      else
+        'Unsupported block'
+      end
+    end
+
+    # Retrieves the rich text content of the block.
+    # @return [Array<Hash>] The rich text content.
+    def rich_text
+      @properties['rich_text'] || []
+    end
+
+    # Retrieves the icon associated with the block.
+    # @return [Array<Hash>] The icon data.
+    def icon
+      icon = @properties['icon']
+      @properties['icon'][icon['type']] || []
+    end
+
+    # Retrieves the multimedia data for the block.
+    # @return [Array] The multimedia data (URL, expiry time, caption, type).
+    def multi_media
+      case @properties['type']
+      when 'file'
+        [@properties.dig('file', 'url'), @properties.dig('file', 'expiry_time'), @properties['caption'], 'file']
+      when 'external'
+        [@properties.dig('external', 'url'), nil, @properties['caption'], 'external']
+      else
+        [@properties['url'], nil, @properties['caption'], nil]
+      end
+    end
+  end
+end

data/lib/notion_to_html/base_page.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# The NotionToHtml::BasePage class represents a Notion page, handling its attributes and rendering.
+# This class processes the raw data of a page fetched from the Notion API and makes
+# it accessible through various attributes. It also provides methods to render formatted
+# output for the page's title, description, and published date.
+
+module NotionToHtml
+  class BasePage
+    include NotionToHtml::Renderers
+
+    # @return [String] the ID of the page.
+    attr_reader :id
+    # @return [String] the creation timestamp of the page.
+    attr_reader :created_time
+    # @return [String] the last edited timestamp of the page.
+    attr_reader :last_edited_time
+    # @return [String] the user who created the page.
+    attr_reader :created_by
+    # @return [String] the user who last edited the page.
+    attr_reader :last_edited_by
+    # @return [Hash, nil] the cover image of the page.
+    attr_reader :cover
+    # @return [Hash, nil] the icon of the page.
+    attr_reader :icon
+    # @return [Hash] the parent of the page (e.g., database ID).
+    attr_reader :parent
+    # @return [Boolean] whether the page is archived.
+    attr_reader :archived
+    # @return [Hash] the properties of the page.
+    attr_reader :properties
+    # @return [String, nil] the publication date of the page.
+    attr_reader :published_at
+    # @return [Array<Hash>, nil] the tags associated with the page.
+    attr_reader :tags
+    # @return [Array<Hash>, nil] the title of the page.
+    attr_reader :title
+    # @return [String, nil] the slug of the page.
+    attr_reader :slug
+    # @return [Array<Hash>, nil] the description of the page.
+    attr_reader :description
+    # @return [String] the URL of the page.
+    attr_reader :url
+
+    # Initializes a new BasePage object.
+    # @param data [Hash] The raw data of the page from the Notion API.
+    def initialize(data)
+      @id = data['id']
+      @created_time = data['created_time']
+      @last_edited_time = data['last_edited_time']
+      @created_by = data['created_by'] # TODO: handle user object
+      @last_edited_by = data['last_edited_by'] # TODO: handle user object
+      @cover = data['cover'] # TODO: handle external type
+      @icon = data['icon'] # TODO: handle emoji type
+      @parent = data['parent'] # TODO: handle database_id type
+      @archived = data['archived']
+      @properties = data['properties'] # TODO: handle properties object
+      process_properties
+      @url = data['url']
+    end
+
+    # Renders the formatted title of the page.
+    # @param options [Hash] Additional options for rendering the title.
+    # @return [String] The formatted title.
+    def formatted_title(options = {})
+      render_heading_1(@title, options)
+    end
+
+    # Renders the formatted description of the page.
+    # @param options [Hash] Additional options for rendering the description.
+    # @return [String] The formatted description.
+    def formatted_description(options = {})
+      render_paragraph(@description, options)
+    end
+
+    # Renders the formatted publication date of the page.
+    # @param options [Hash] Additional options for rendering the publication date.
+    # @return [String] The formatted publication date.
+    def formatted_published_at(options = {})
+      render_date(@published_at, options)
+    end
+
+    private
+
+    # Processes the properties of the page and assigns them to the relevant attributes.
+    # @return [void]
+    def process_properties
+      @tags = @properties['tags']
+      @title = @properties.dig('name', 'title')
+      @slug = @properties['slug']
+      @published_at = @properties.dig('published', 'date', 'start')
+      @description = @properties.dig('description', 'rich_text')
+    end
+  end
+end

data/lib/notion_to_html/page.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# The NotionToHtml::Page class represents a Notion page, containing both the metadata and blocks associated with the page.
+# This class integrates metadata and blocks, providing methods to format and render the page's content.
+
+module NotionToHtml
+  class Page
+    include NotionToHtml::Renderers
+
+    # @return [BasePage] The metadata of the page, encapsulating details like title, description, and published date.
+    attr_reader :metadata
+    # @return [Array<BaseBlock>] The blocks of the page, representing the content sections.
+    attr_reader :blocks
+
+    # Delegate methods to metadata for easy access to formatted title, description, and published date.
+    delegate :formatted_title, to: :metadata
+    delegate :formatted_description, to: :metadata
+    delegate :formatted_published_at, to: :metadata
+
+    # Initializes a new Page object.
+    # @param base_page [BasePage] The metadata of the page.
+    # @param base_blocks [Array<BaseBlock>] The blocks of the page.
+    def initialize(base_page, base_blocks)
+      @metadata = base_page
+      @blocks = base_blocks
+    end
+
+    # Formats and renders the blocks of the page.
+    # @param options [Hash] Additional options for rendering the blocks.
+    # @return [Array<String>] The rendered blocks as an array of HTML strings.
+    def formatted_blocks(options = {})
+      @blocks.map { |block| block.render(options) }
+    end
+  end
+end

data/lib/notion_to_html/renderers.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+# The NotionToHtml::Renderers module provides functionality for rendering Notion content
+# into HTML format. It includes various helper methods from ActionView to assist
+# in rendering different Notion blocks like paragraphs, headings, lists, images,
+# and more.
+
+module NotionToHtml
+  module Renderers
+    include ActionView::Helpers::AssetTagHelper
+    include ActionView::Helpers::TagHelper
+    include ActionView::Helpers::UrlHelper
+    include ActionView::Context
+
+    # Default CSS classes for different types of Notion blocks.
+    DEFAULT_CSS_CLASSES = {
+      bulleted_list_item: 'list-disc list-inside break-words',
+      callout: 'flex flex-column p-4 rounded mt-4',
+      code: 'border-2 p-6 rounded w-full overflow-x-auto',
+      date: '',
+      heading_1: 'mb-4 mt-6 text-3xl font-semibold',
+      heading_2: 'mb-4 mt-6 text-2xl font-semibold',
+      heading_3: 'mb-2 mt-6 text-xl font-semibold',
+      image: '',
+      numbered_list_item: 'list-decimal list-inside break-words',
+      paragraph: '',
+      quote: 'border-l-4 border-black px-5 py-1',
+      video: 'w-full'
+    }.freeze
+
+    # Converts text annotations to corresponding CSS classes.
+    #
+    # @param annotations [Hash] the annotations hash containing keys like 'bold', 'italic', 'color', etc.
+    # @return [String] a string of CSS classes.
+    def annotation_to_css_class(annotations)
+      classes = annotations.keys.map do |key|
+        case key
+        when 'strikethrough'
+          'line-through' if annotations[key]
+        when 'bold'
+          'font-bold' if annotations[key]
+        when 'code'
+          'inline-code' if annotations[key]
+        when 'color'
+          "text-#{annotations["color"]}-600" if annotations[key] != 'default'
+        else
+          annotations[key] ? key : nil
+        end
+      end
+      classes.compact.join(' ')
+    end
+
+    # Renders a rich text property into HTML.
+    #
+    # @param properties [Array] the rich text array containing text fragments and annotations.
+    # @param options [Hash] additional options for rendering, such as CSS classes.
+    # @return [String] an HTML-safe string with the rendered text.
+    def text_renderer(properties, options = {})
+      properties.map do |rich_text|
+        classes = annotation_to_css_class(rich_text['annotations'])
+        if rich_text['href']
+          link_to(
+            rich_text['plain_text'],
+            rich_text['href'],
+            class: "link #{classes} #{options[:class]}"
+          )
+        elsif classes.present?
+          content_tag(:span, rich_text['plain_text'], class: "#{classes} #{options[:class]}")
+        else
+          tag.span(rich_text['plain_text'], class: options[:class])
+        end
+      end.join('').html_safe
+    end
+
+    # Renders a bulleted list item.
+    #
+    # @param rich_text_array [Array] the rich text array containing the content of the list item.
+    # @param _siblings [Array] sibling list items.
+    # @param children [Array] child list items.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered list item.
+    def render_bulleted_list_item(rich_text_array, siblings, children, parent_index, options = {})
+      content_tag(:ul, **options, class: css_class_for(:bulleted_list_item, options)) do
+        render_list_items(:bulleted_list_item, rich_text_array, siblings, children, parent_index, options)
+      end
+    end
+
+    # Renders a callout block.
+    #
+    # @param rich_text_array [Array] the rich text array containing the content of the callout.
+    # @param icon [String] the icon to display in the callout.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered callout.
+    def render_callout(rich_text_array, icon, options = {})
+      content_tag(:div, **options, class: css_class_for(:callout, options)) do
+        content = tag.span(icon, class: 'mr-4')
+        content += tag.div do
+          text_renderer(rich_text_array)
+        end
+        content
+      end
+    end
+
+    # Renders a code block.
+    #
+    # @param rich_text_array [Array] the rich text array containing the code content.
+    # @param options [Hash] additional options for rendering, including the programming language.
+    # @return [String] an HTML-safe string with the rendered code block.
+    def render_code(rich_text_array, options = {})
+      # TODO: render captions
+      content_tag(:div, data: { controller: 'highlight' }) do
+        content_tag(:div, data: { highlight_target: 'source' }) do
+          content_tag(:pre, **options, class: "#{css_class_for(:code, options)} language-#{options[:language]}") do
+            text_renderer(rich_text_array, options)
+          end
+        end
+      end
+    end
+
+    # Renders a date block.
+    #
+    # @param date [Date] the date to be rendered.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered date.
+    def render_date(date, options = {})
+      # TODO: handle end and time zone
+      # date=end=, start=2023-07-13, time_zone=, id=%5BsvU, type=date
+      tag.p(date.to_date.to_fs(:long), class: css_class_for(:date, options))
+    end
+
+    # Renders a heading 1 block.
+    #
+    # @param rich_text_array [Array] the rich text array containing the content of the heading.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered heading 1.
+    def render_heading_1(rich_text_array, options = {})
+      content_tag(:h1, **options, class: css_class_for(:heading_1, options)) do
+        text_renderer(rich_text_array)
+      end
+    end
+
+    # Renders a heading 2 block.
+    #
+    # @param rich_text_array [Array] the rich text array containing the content of the heading.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered heading 2.
+    def render_heading_2(rich_text_array, options = {})
+      content_tag(:h2, **options, class: css_class_for(:heading_2, options)) do
+        text_renderer(rich_text_array)
+      end
+    end
+
+    # Renders a heading 3 block.
+    #
+    # @param rich_text_array [Array] the rich text array containing the content of the heading.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered heading 3.
+    def render_heading_3(rich_text_array, options = {})
+      content_tag(:h3, **options, class: css_class_for(:heading_3, options)) do
+        text_renderer(rich_text_array)
+      end
+    end
+
+    # Renders an image block.
+    #
+    # @param src [String] the source URL of the image.
+    # @param _expiry_time [Time] the expiration time of the image.
+    # @param caption [Array] the caption text array for the image.
+    # @param _type [String] the type of image (e.g., 'external', 'file').
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered image.
+    def render_image(src, _expiry_time, caption, _type, options = {})
+      content_tag(:figure, **options, class: css_class_for(:image, options)) do
+        content = tag.img(src: src, alt: '')
+        content += tag.figcaption(text_renderer(caption))
+        content
+      end
+    end
+
+    # Renders a numbered list item.
+    #
+    # @param rich_text_array [Array] the rich text array containing the content of the list item.
+    # @param siblings [Array] sibling list items.
+    # @param children [Array] child list items.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered list item.
+    def render_numbered_list_item(rich_text_array, siblings, children, parent_index, options = {})
+      content_tag(:ol, **options, class: css_class_for(:numbered_list_item, options)) do
+        render_list_items(:numbered_list_item, rich_text_array, siblings, children, parent_index, options)
+      end
+    end
+
+    # Renders a paragraph block.
+    #
+    # @param rich_text_array [Array] the rich text array containing the content of the paragraph.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered paragraph.
+    def render_paragraph(rich_text_array, options = {})
+      content_tag(:p, **options, class: css_class_for(:paragraph, options)) do
+        text_renderer(rich_text_array)
+      end
+    end
+
+    # Renders a quote block.
+    #
+    # @param rich_text_array [Array] the rich text array containing the content of the quote.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered quote.
+    def render_quote(rich_text_array, options = {})
+      content_tag(:div, options) do
+        content_tag(:cite) do
+          content_tag(:p, **options, class: css_class_for(:quote, options)) do
+            text_renderer(rich_text_array)
+          end
+        end
+      end
+    end
+
+    # Renders a table of contents block.
+    #
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered table of contents.
+    def render_table_of_contents(options = {})
+      content_tag(:p, 'Table of Contents', class: css_class_for(:table_of_contents, options))
+    end
+
+    # Renders a video block.
+    #
+    # @param src [String] the source URL of the video.
+    # @param _expiry_time [Time] the expiration time of the video.
+    # @param caption [Array] the caption text array for the video.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered video.
+    def render_video(src, _expiry_time, caption, type, options = {})
+      content_tag(:figure, **options, class: css_class_for(:video, options)) do
+        content = if type == 'file'
+                    video_tag(src, controls: true, **options, class: css_class_for(:video, options))
+                  elsif type == 'external'
+                    options[:class] = "#{options[:class]} aspect-video"
+                    tag.iframe(src: src, allowfullscreen: true, **options, class: css_class_for(:video, options))
+                  end
+        content += tag.figcaption(text_renderer(caption))
+        content
+      end
+    end
+
+    private
+
+    # Determines the CSS class for a given block type.
+    #
+    # @param type [Symbol] the block type (e.g., :paragraph, :heading_1, etc.).
+    # @param options [Hash] additional options for rendering.
+    # @return [String] the CSS class for the block.
+    def css_class_for(type, options)
+      if options[:override_class]
+        options[:class]
+      else
+        "#{DEFAULT_CSS_CLASSES[type]} #{options[:class]}".strip
+      end
+    end
+
+    # Renders list items (bulleted or numbered).
+    #
+    # @param list_type [Symbol] the type of list (:bulleted_list_item or :numbered_list_item).
+    # @param rich_text_array [Array] the rich text array containing the content of the list item.
+    # @param siblings [Array] sibling list items.
+    # @param children [Array] child list items.
+    # @param options [Hash] additional options for rendering.
+    # @return [String] an HTML-safe string with the rendered list items.
+    def render_list_items(type, rich_text_array, siblings, children, parent_index, options = {})
+      content = content_tag(:li, class: "#{options[:class]} ml-#{parent_index.to_i * 2}".strip) do
+        text_renderer(rich_text_array)
+      end
+      if children.present?
+        res = children.map do |child|
+          send("render_#{type}".to_sym, child.rich_text, child.siblings, child.children, parent_index.to_i + 1, options)
+        end
+        content += res.join('').html_safe
+      end
+      if siblings.present?
+        content += siblings.map do |sibling|
+          render_list_items(type, sibling.rich_text, sibling.siblings, sibling.children, parent_index.to_i, options)
+        end.join('').html_safe
+      end
+      content.html_safe
+    end
+  end
+end

data/lib/notion_to_html/service.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'notion-ruby-client'
+
+# The NotionToHtml::Service module is responsible for managing interactions with the Notion API, specifically for retrieving and processing pages and blocks.
+# This module provides a set of methods that handle queries, sorting, and filtering based on tags, slugs, and other properties.
+# It also manages the retrieval of page content, including associated blocks, and ensures that images are refreshed if their expiry time has passed.
+
+module NotionToHtml
+  class Service
+    class << self
+      # Generates the default query for fetching pages
+      # @param tag [String, nil] The tag to filter pages by, or nil to include all tags
+      # @param slug [String, nil] The slug to filter pages by, or nil to include all slugs
+      # @return [Array<Hash>] The default query to be used in the database query
+      def default_query(tag: nil, slug: nil)
+        query = [
+          {
+            property: 'public',
+            checkbox: {
+              equals: true
+            }
+          }
+        ]
+
+        if slug
+          query.push({
+            property: 'slug',
+            rich_text: {
+              equals: slug
+            }
+          })
+        end
+
+        if tag
+          query.push({
+            property: 'tags',
+            multi_select: {
+              contains: tag
+            }
+          })
+        end
+
+        query
+      end
+
+      # Provides the default sorting order for fetching pages
+      # @return [Hash] The default sorting criteria for database queries
+      def default_sorting
+        {
+          property: 'published',
+          direction: 'descending'
+        }
+      end
+
+      # Fetches a list of pages from Notion based on provided filters
+      # @param tag [String, nil] The tag to filter pages by, or nil to include all tags
+      # @param slug [String, nil] The slug to filter pages by, or nil to include all slugs
+      # @param page_size [Integer] The number of pages to fetch per page
+      # @return [Array<NotionToHtml::BasePage>] The list of pages as BasePage objects
+      def get_pages(tag: nil, slug: nil, page_size: 10)
+        __get_pages(tag: tag, slug: slug, page_size: page_size)['results'].map do |page|
+          NotionToHtml::BasePage.new(page)
+        end
+      end
+
+      # Fetches a single page by its ID
+      # @param id [String] The ID of the page to fetch
+      # @return [NotionToHtml::Page] The page as a NotionToHtml::Page object
+      def get_page(id)
+        base_page = NotionToHtml::BasePage.new(__get_page(id))
+        base_blocks = get_blocks(id)
+        NotionToHtml::Page.new(base_page, base_blocks)
+      end
+
+      # Fetches blocks associated with a given page ID
+      # @param id [String] The ID of the page whose blocks are to be fetched
+      # @return [Array<NotionToHtml::BaseBlock>] The list of blocks as BaseBlock objects
+      def get_blocks(id)
+        blocks = __get_blocks(id)
+        parent_list_block_index = nil
+        results = []
+        blocks['results'].each_with_index do |block, index|
+          block = refresh_block(block['id']) if refresh_image?(block)
+          base_block = NotionToHtml::BaseBlock.new(block)
+          base_block.children = get_blocks(base_block.id) if base_block.has_children
+          if %w[numbered_list_item].include? base_block.type
+            siblings = !parent_list_block_index.nil? &&
+                       index != parent_list_block_index &&
+                       base_block.type == results[parent_list_block_index]&.type &&
+                       base_block.parent == results[parent_list_block_index]&.parent
+            if siblings
+              results[parent_list_block_index].siblings << base_block
+              next
+            else
+              parent_list_block_index = results.length
+            end
+          else
+            parent_list_block_index = nil
+          end
+          results << base_block
+        end
+        results
+      end
+
+      # Determines if an image block needs to be refreshed based on its expiry time
+      # @param data [Hash] The data of the image block
+      # @return [Boolean] True if the image needs to be refreshed, false otherwise
+      def refresh_image?(data)
+        return false unless data['type'] == 'image'
+        return false unless data.dig('image', 'type') == 'file'
+
+        expiry_time = data.dig('image', 'file', 'expiry_time')
+        expiry_time.to_datetime.past?
+      end
+
+      private
+
+      # Accessor for the client
+      # @return [Notion::Client] The client instance used to interact with the Notion API
+      def client
+        @client ||= Notion::Client.new(token: NotionToHtml.config.notion_api_token)
+      end
+
+      # Retrieves pages from Notion using the client
+      # @param tag [String, nil] The tag to filter pages by
+      # @param slug [String, nil] The slug to filter pages by
+      # @param page_size [Integer] The number of pages to fetch per page
+      # @return [Hash] The response from the Notion API containing pages
+      def __get_pages(tag: nil, slug: nil, page_size: 10)
+        client.database_query(
+          database_id: NotionToHtml.config.notion_database_id,
+          sorts: [
+            default_sorting
+          ],
+          filter: {
+            'and': default_query(tag: tag, slug: slug)
+          },
+          page_size: page_size
+        )
+      end
+
+      # Retrieves a single page by its ID from Notion
+      # @param id [String] The ID of the page to fetch
+      # @return [Hash] The response from the Notion API containing the page
+      def __get_page(id)
+        client.page(page_id: id)
+      end
+
+      # Retrieves blocks associated with a given ID from Notion, using cache if available
+      # @param id [String] The ID of the block to fetch
+      # @return [Hash] The response from the Notion API containing the blocks
+      def __get_blocks(id)
+        NotionToHtml.config.cache_store.fetch(id) { client.block_children(block_id: id) }
+      end
+
+      # Retrieves a single block by its ID from Notion
+      # @param id [String] The ID of the block to fetch
+      # @return [Hash] The response from the Notion API containing the block
+      def __get_block(id)
+        client.block(block_id: id)
+      end
+
+      # Refreshes a block by retrieving it again from Notion
+      # @param id [String] The ID of the block to refresh
+      # @return [Hash] The response from the Notion API containing the refreshed block
+      def refresh_block(id)
+        __get_block(id)
+      end
+    end
+  end
+end

data/lib/notion_to_html/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module NotionToHtml
+  # The current version of the NotionToHtml gem.
+  VERSION = '1.0.0'
+end

data/lib/notion_to_html.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'active_support/all'
+require 'notion_to_html/renderers'
+require 'notion_to_html/base_block'
+require 'notion_to_html/base_page'
+require 'notion_to_html/page'
+require 'notion_to_html/service'
+require 'dry-configurable'
+
+module NotionToHtml
+  extend Dry::Configurable
+
+  # @!attribute [rw] notion_api_token
+  #   @return [String] The API token used to authenticate requests to the Notion API.
+  setting :notion_api_token
+
+  # @!attribute [rw] notion_database_id
+  #   @return [String] The database ID in Notion that the module will interact with.
+  setting :notion_database_id
+
+  # @!attribute [rw] cache_store
+  #   @return [ActiveSupport::Cache::Store] The cache store used to cache responses from the Notion API.
+  #   @default ActiveSupport::Cache::MemoryStore.new
+  setting :cache_store, default: ActiveSupport::Cache::MemoryStore.new
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: notion_to_html
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Guillermo Aguirre
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: notion-ruby-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.2
+description: Simple gem to render Notion blocks as HTML using Ruby
+email:
+- guillermoaguirre@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/notion_to_html.rb
+- lib/notion_to_html/base_block.rb
+- lib/notion_to_html/base_page.rb
+- lib/notion_to_html/page.rb
+- lib/notion_to_html/renderers.rb
+- lib/notion_to_html/service.rb
+- lib/notion_to_html/version.rb
+homepage: https://github.com/guillermoap/notion_to_html
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/guillermoap/notion_to_html
+  source_code_uri: https://github.com/guillermoap/notion_to_html
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Notion HTML renderer for Ruby
+test_files: []