🚀 jekyll-notion & notion_to_md 3.0.0 Beta

Over the last week — during a transition period between jobs — I found the perfect time to sit down and rework both libraries. I wasn’t too pleased with the old architecture, so I redesigned things to be better scoped and clearer: removing what wasn’t really needed, and adding some functionality I had missed when using them myself. The result is the beginning of a new major version for both gems.

✨ What’s New in notion_to_md

This gem started as a quick way to turn Notion pages into Markdown for the Ruby ecosystem. It also serves as the foundation for jekyll-notion. With this beta release, it grows up a bit:

• Pagination support: large Notion pages are now fully handled, no more cut-off blocks.
• Database support: you can fetch a database and automatically download all its pages.
• Cleaner architecture: more consistent namespacing and method naming make the codebase easier to follow and maintain.
• Docs upgrade: improved inline YARD documentation.

✨ What’s New in jekyll-notion

The sole purpose of jekyll-notion is to make Notion a simple CMS for Jekyll. In version 3.x it gets tighter integration with the new notion_to_md and some long-requested improvements:

• Pagination built-in: it now leverages the improved notion_to_md converter under the hood.
• Simplified caching: cache files are easier to identify (title + id), and easy to delete if you need a reset.
• Automatic detection: new pages in your databases show up automatically when rebuilding a site.
• Sensitive data filters: documentation now explains how to redact tokens or other private values from cached files.

⚠️ What About v2

This is still a beta release. Expect some rough edges and breaking changes before the final 3.0.0.

👉 Most importantly: once 3.0.0 is stable, the 2.x series will no longer be maintained.

If you’re running v2, now is a good time to test the betas. In principle, no migration should be required — except if you’ve tinkered with the internals of either library. In that case, you may need to adjust some code, though it shouldn’t be a heavy lift. At the most basic level, everything should keep working as before.

📦 How to Try It

Add the gems with --pre:

gem "jekyll-notion", "3.0.0.beta1"
gem "notion_to_md", "3.0.0.beta2"

Or install directly:

gem install jekyll-notion --pre
gem install notion_to_md --pre

🔮 What Lies Ahead

I’m not entirely sure how both libraries will evolve in terms of features.

• For notion_to_md, it may grow by supporting more Notion block types and elements.
• For jekyll-notion, I’m considering adding a polling mechanism that would allow databases and pages to update automatically while developing a site.

What is clear is that both libraries will continue to be maintained for the long run — mainly by keeping up with Notion API changes through notion-ruby-client.

🙏 Thanks

These projects started as small experiments so my wife could manage her site’s content easily without messing with code or paying for more complicated solutions. Both projects grew with the feedback of people actually using them. I’m grateful to everyone who opened issues, sent patches, or just wrote to say they were using them on their sites.

I also want to thank Nicolas Goutay and others who built and maintain the notion-ruby-client gem — it made the development and upkeep of both libraries much easier. And of course, thanks to Notion itself. It’s quite a great app.

💡 Give It a Try

If you give the betas a try, let me know how it goes — bugs, surprises, or even just success stories. You can reach me through the GitHub repositories (jekyll-notion or notion_to_md) or simply send me an email at hola@enrq.me. Your feedback will help shape the final release.