{"id":14955253,"url":"https://github.com/guillermoap/notion_to_html","last_synced_at":"2025-07-18T04:35:40.411Z","repository":{"id":254786119,"uuid":"847461155","full_name":"guillermoap/notion_to_html","owner":"guillermoap","description":"Notion HTML renderer for Ruby and Rails","archived":false,"fork":false,"pushed_at":"2025-01-31T23:03:44.000Z","size":1004,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-06T07:21:49.035Z","etag":null,"topics":["notion","notion-blog","rails","renderer","ruby","ruby-on-rails"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guillermoap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-25T22:04:47.000Z","updated_at":"2025-01-31T23:00:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"44cf3472-a6be-417f-961b-280051705a40","html_url":"https://github.com/guillermoap/notion_to_html","commit_stats":{"total_commits":3,"total_committers":1,"mean_commits":3.0,"dds":0.0,"last_synced_commit":"8da4aedaeee78f956b48eafd3d6a62a3fd75675e"},"previous_names":["guillermoap/notion_to_html"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/guillermoap/notion_to_html","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guillermoap%2Fnotion_to_html","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guillermoap%2Fnotion_to_html/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guillermoap%2Fnotion_to_html/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guillermoap%2Fnotion_to_html/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guillermoap","download_url":"https://codeload.github.com/guillermoap/notion_to_html/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guillermoap%2Fnotion_to_html/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265701111,"owners_count":23813749,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["notion","notion-blog","rails","renderer","ruby","ruby-on-rails"],"created_at":"2024-09-24T13:10:45.777Z","updated_at":"2025-07-18T04:35:40.388Z","avatar_url":"https://github.com/guillermoap.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NotionToHtml\n\nNotionToHtml 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.\n\nNow you can use Notion to publish your pages directly to your Ruby web page with one click.\n\n## Table of Contents\n\n- [NotionToHtml](#notiontohtml)\n- [Table of Contents](#table-of-contents)\n- [About](#about)\n- [Installation](#installation)\n- [Dependencies](#dependencies)\n- [Setup](#setup)\n- [Configuration](#configuration)\n- [Usage](#usage)\n  - [Rendering](#rendering)\n    - [Pages](#pages)\n    - [Specific Page](#specific-page)\n    - [Customizing styles](#customizing-styles)\n    - [Overriding default styles](#overriding-default-styles)\n    - [Adding data options](#adding-data-options)\n  - [Querying](#querying)\n    - [Filtering](#filtering)\n    - [Sorting](#sorting)\n- [Examples](#examples)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n- [Code of Conduct](#code-of-conduct)\n\n## About\n\nNotionToHtml 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.\n\nYou just need to create a database in Notion, integrate it and start writing!\n\n## Installation\n\nAdd the gem to your application's Gemfile:\n```bash\nbundle add notion_to_html\n```\nOr install it yourself as:\n```bash\ngem install notion_to_html\n```\n## Dependencies\nNotionToHtml 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.\nIf you wish to use something else you can always override the default styling provided, see [Customizing styles](#customizing-styles) for more details.\n\n## Setup\nThis 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).\n\nBy default the database should have the following structure:\n![Database structure](/docs/images/database_structure.png)\n\n- _name, description \u0026 slug_ as Text\n- tags as Multi-Select\n- public as Checkbox\n- published as Date\n\nOnce 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.\n\nIf you wish to just quickly set it up, you can follow the [notion integration docs](/docs/notion_setup.md), which are taken from that tutorial.\n\n## Configuration\nTo configure NotionToHtml, you need to set up your Notion API token and database ID.\nIf 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:\n```ruby\nNotionToHtml.configure do |config|\n  config.notion_api_token = 'NOTION_API_TOKEN'\n  config.notion_database_id = 'NOTION_DATABASE_ID'\n  config.cache_store = Rails.cache\nend\n```\n\nTo get these values:\n1. The NOTION_API_TOKEN is the same one from [the setup](#get-your-api-secret).\n2. To get the NOTION_DATABASE_ID, locate the 32-character string at the end of the page’s URL.\n    ```bash\n    https://www.notion.so/myworkspace/a8aec43384f447ed84390e8e42c2e089?v=...\n                                      |--------- Database ID --------|\n    ```\n\n**Remember to keep these values secret!**\n\nNow you should be all setup!\n\nFor the full list of configuration settings, see [the configuration module](./lib/notion_to_html.rb).\n\n## Usage\n### Rendering\n#### Pages\nTo get and render a preview of the pages of your database:\n```ruby\n\u003c% NotionToHtml::Service.get_pages.each do |page| %\u003e\n  \u003c%= article.formatted_published_at %\u003e\n  \u003c%= article.id %\u003e\n  \u003c%= article.formatted_title %\u003e\n  \u003c%= article.formatted_description %\u003e\n\u003c% end %\u003e\n```\n#### Specific Page\nTo get and render a specific page:\n```ruby\n\u003c% page = NotionToHtml::Service.get_page(page_id) %\u003e\n\u003c%= page.formatted_title %\u003e\n\u003c%= page.formatted_published_at %\u003e\n\u003c% page.formatted_blocks.each do |block| %\u003e\n  \u003c%= block %\u003e\n\u003c% end %\u003e\n```\n#### Customizing styles\nNotionToHtml 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:\n```ruby\nNotionToHtml::Service.get_page(page_id)\n  .formatted_title(class: 'text-4xl md:text-5xl font-bold')\n```\nYou can also specify classes for each type of supported block like this:\n```ruby\nNotionToHtml::Service.get_page(page_id).formatted_blocks(\n  paragraph: { class: 'text-lg' }, \n  heading_1: { class: 'text-3xl md:text-4xl font-bold' }, \n  heading_2: { class: 'text-white' }, \n  heading_3: { class: 'font-bold' }, \n  quote: { class: 'italic' }, \n)\n```\n#### Overriding default styles\nIf 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`:\n```ruby\nNotionToHtml::Service.get_page(page_id)\n  .formatted_title(class: 'font-bold', override_class: true)\n```\nIt also works for `formatted_blocks`:\n```ruby\nNotionToHtml::Service.get_page(page_id)\n  .formatted_blocks(\n    paragraph: { class: 'text-lg', override_class: true }, \n    quote: { class: 'italic' } \n)\n```\n#### Adding data options\nIf you want to integrate stimulus you can add data properties by specifying the `data:` option when calling the formatter:\n```ruby\nNotionToHtml::Service.get_page(page_id).formatted_blocks(\n  paragraph: { class: 'text-lg', data: { controller: 'test' } } }, \n  heading_1: { class: 'text-3xl md:text-4xl font-bold' }, \n  heading_2: { class: 'text-white', data: { controller: 'click' } }, \n  heading_3: { class: 'font-bold' }, \n  quote: { class: 'italic' }, \n)\n```\n### Querying\nBy 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`.\n\n#### Filtering\nYou can filter the results by specifying a name, description, tag and/or a specific slug:\n```ruby\nNotionToHtml::Service.get_pages(name: 'Ruby', description: 'ruby on rails', tag: 'web', slug: 'test-slug')\n```\nThis will return all the pages that have at least one of those specified attributes.\n#### Sorting\nThe default sorting is by the `published` Date column in the database\n\n### Examples\nTo see how the default renderings of the supported blocks look, go over to the [examples](/examples/).\n\n## Development\n\nAfter 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.\n\nTo 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).\n\n## Contributing\n\nBug reports and pull requests are welcome on [Github](https://github.com/guillermoap/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).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguillermoap%2Fnotion_to_html","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguillermoap%2Fnotion_to_html","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguillermoap%2Fnotion_to_html/lists"}