jekyll-fetch-notion 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42f67d3357969f45294781b7901ad390ce89839a322db0c7138026c3e63a4d75
+  data.tar.gz: 43bece5765cdb7419279f4f517cd4546052e0112e4a5bb326eb060691523dd3a
+SHA512:
+  metadata.gz: 5aa2e9d66557492d0f88d2543309e881279fce8567fc01d0bee5de2fd429c22edbc87039a4d43ec8fb2a1cd1debebf4a91b428d33adc8b087bd68669bb0ca3af
+  data.tar.gz: c692a7f3a600909f4b85cd73a505a525491f31c059e03b6f190f9c45978992e6898ce77fa0fc35fabee5985d2b4a6a8413ec917fed3987c40f3b92d9ba26de8c

data/README.md

@@ -0,0 +1,198 @@
+# jekyll-fetch-notion
+
+The Jekyll plugin introduces the `fetch_notion` command. This command fetches all Notion
+content as specified by the `_config.yml` file and places it directly into your git
+repository. This project is a fork of [jekyll-notion][1], created due to incompatible
+synchronization methods. You can find more details in [this pull request][10].
+
+*Note: Data and page fetching are planned for future releases but are not yet available.*
+
+The original project was designed with the idea that Notion content should be fetched
+during site building and not tracked by git. This project, however, takes a different
+approach. It arranges your workflow so that your Notion content is git-tracked and
+fetched before site building.
+
+I believe this method aligns better with Jekyll's "ideology" and also offers several
+advantages:
+
+- Your Notion content is git-tracked and preserved. This ensures a smooth transition from
+  Notion back to plain `.md` editing or to another synchronization tool. As Jekyll is a
+  static site generator, everything remains static.
+- Separating Notion synchronization from site building simplifies the process and
+  provides you more precise control. For example, you again can git-clone and build a
+  site as-is without Notion token.
+
+However, every implementation has its own pros and cons. Choose the one that best suits
+your needs.
+
+For more insights into my experience with `jekyll-fetch-notion`, check out these posts:
+
+- [Yet another way to establish Notion + Jekyll synchronization][12]
+- [Notion + Jekyll images synchronization][11]
+
+## Installation
+
+Use `gem` to install:
+
+```bash
+gem install 'jekyll-fetch-notion'
+```
+
+Or add it to the `Gemfile`:
+
+```ruby
+gem 'jekyll-fetch-notion'
+```
+
+And then update your jekyll plugins property in `_config.yml`:
+
+```yml
+plugins:
+  - jekyll-fetch-notion
+```
+
+## Usage
+
+Before using the gem, create an integration and generate a secret token. For more in-depth
+instructions refer to the Notion "Getting Started" [guide][2].
+
+Once you have your secret token, make sure to export it into an environment variable named
+`NOTION_TOKEN`:
+
+```bash
+export NOTION_TOKEN=<secret_...>
+```
+
+Then you can run command to fetch all the Notion content and place it inside your's site
+repository:
+
+```bash
+jekyll fetch_notion
+```
+
+Then you probably need to stage, commit and push all the fetched files to trigger your
+default CI build flow and make your updated site deployed.
+
+### Databases
+
+Once the [notion database][3] has been shared, specify the database `id` in the
+`_config.yml` file as follows:
+
+```yml
+notion:
+  databases:
+    - id: 5cfed4de3bdc4f43ae8ba653a7a2219b
+```
+
+By default, the notion pages in the database will be loaded into the `posts` collection.
+
+We can also define multiple databases as follows:
+
+```yml
+collections:
+  - recipes
+  - films
+
+notion:
+  databases:
+    - id: b0e688e199af4295ae80b67eb52f2e2f
+    - id: 2190450d4cb34739a5c8340c4110fe21
+      collection: recipes
+    - id: e42383cd49754897b967ce453760499f
+      collection: films
+```
+
+After running `jekyll fetch_notion` command, the `posts`, `recipes` and `films`
+collections will be fetched with pages from the notion databases.
+
+#### Database options
+
+Each dabatase support the following options.
+
+- `id`: the notion database unique identifier
+- `collection`: the collection each page belongs to (posts by default)
+- `filter`: the database [filter property][4]
+- `sorts`: the database [sorts criteria][5]
+
+```yml
+notion:
+  databases:
+    - id: e42383cd49754897b967ce453760499f
+      collection: posts
+      filter: { "property": "Published", "checkbox": { "equals": true } }
+      sorts: [{ "timestamp": "created_time", "direction": "ascending" }]
+```
+
+#### Posts date
+
+The `created_time` property of a notion page is used to set the date in the post filename.
+This is the date used for the `date` variable of the [predefined variables for posts][6].
+
+It's important to note that the `created_time` cannot be modifed. However, if you wish to
+change the date of a post, you can create a new page property named "date" (or "Date").
+This way, the posts collection will use the `date` property for the post date variable
+instead of the `created_time`.
+
+### Notion properties
+
+Notion page properties are set for each document in the front matter.
+
+Please, refer to the [notion_to_md][8] gem to learn more.
+
+### Page filename
+
+There are two kinds of documents in Jekyll: posts and others.
+
+When the document is a post, the filename format contains the `created_time` property
+plus the page title as specified in [jekyll docs][9].
+
+```
+YEAR-MONTH-DAY-title.MARKUP
+```
+
+The filename for any other document is the page title.
+
+## Alternatives
+
+Actually, there are a lot of alternatives available, but, however, mostly all of them are
+not so mature and hard to extend. This one (like `jekyll-notion`) is tested by time and
+easy to extend because of `notion_to_md` usage.
+
+## License
+
+```
+MIT License
+
+Copyright (c) 2024 Enrique Arias, Daniil Sivak
+
+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.
+```
+
+[1]: https://github.com/emoriarty/jekyll-notion
+[2]: https://developers.notion.com/docs/getting-started
+[3]: https://developers.notion.com/docs/working-with-databases
+[4]: https://developers.notion.com/reference/post-database-query-filter
+[5]: https://developers.notion.com/reference/post-database-query-sort
+[6]: https://jekyllrb.com/docs/front-matter/#predefined-variables-for-posts
+[7]: https://jekyllrb.com/docs/permalinks/#front-matter
+[8]: https://github.com/emoriarty/notion_to_md/
+[9]: https://jekyllrb.com/docs/posts/#creating-posts
+[10]: https://github.com/emoriarty/jekyll-notion/pull/68
+[11]: https://seroperson.me/2023/11/16/notion-jekyll-images-synchronization/
+[12]: https://seroperson.me/2023/08/26/yet-another-way-to-establish-notion-jekyll-synchronization/

data/lib/jekyll-fetch-notion/abstract_notion_resource.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module JekyllFetchNotion
+  class AbstractNotionResource
+    def initialize(config:)
+      @notion = Notion::Client.new
+      @config = config
+    end
+
+    def config
+      @config || {}
+    end
+
+    def id
+      config["id"]
+    end
+
+    def fetch
+      raise "Do not use the AbstractNotionResource class. Implement the fetch method in a subclass."
+    end
+
+    def collection_name
+      raise "Do not use the AbstractGenerator class. Implement the collection_name method in a subclass."
+    end
+
+    def data_name
+      raise "Do not use the AbstractGenerator class. Implement the data_name method in a subclass."
+    end
+
+    protected
+
+    def id?
+      if id.nil? || id.empty?
+        Jekyll.logger.warn("Jekyll Notion:",
+          "Database or page id is not provided. Cannot read from Notion.")
+        return false
+      end
+      true
+    end
+
+    def build_blocks(block_id)
+      NotionToMd::Blocks.build(block_id: block_id) do |nested_id|
+        @notion.block_children({block_id: nested_id})
+      end
+    end
+  end
+end

data/lib/jekyll-fetch-notion/commands/fetch_notion.rb

@@ -0,0 +1,45 @@
+module JekyllFetchNotion
+  class FetchCommand < Jekyll::Command
+    def self.init_with_program(p)
+      p.command(:fetch_notion) do |c|
+        c.syntax "fetch_notion [options]"
+        c.description "Fetches Notion content and places it in collection's directory"
+
+        c.action do |args, options|
+          process(args, options)
+        end
+      end
+    end
+
+    def self.process(args = [], options = {})
+      @config = configuration_from_options(options)
+
+      return unless notion_token?
+
+      # requires plugins (and _plugins/ directory) to be able to
+      # define custom notion_to_md blocks via monkey-patching
+      Jekyll::Site.new(@config)
+
+      config_databases.each do |db_config|
+        db = NotionDatabase.new(config: db_config)
+        CollectionGenerator.new(
+          notion_resource: db,
+          plugin: nil,
+          config: @config
+        ).generate
+      end
+    end
+
+    def self.notion_token?
+      if ENV["NOTION_TOKEN"].nil? || ENV["NOTION_TOKEN"].empty?
+        Jekyll.logger.warn("Jekyll Notion:", "NOTION_TOKEN not provided. Cannot read from Notion.")
+        return false
+      end
+      true
+    end
+
+    def self.config_databases
+      @config["notion"]["databases"] || []
+    end
+  end
+end

data/lib/jekyll-fetch-notion/factories/database_factory.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module JekyllFetchNotion
+  class DatabaseFactory
+    def self.for(notion_resource:, site:, plugin:)
+      if notion_resource.data_name.nil?
+        CollectionGenerator.new(
+          notion_resource: notion_resource,
+          site: site,
+          plugin: plugin,
+          config: site.config
+        )
+      else
+        DataGenerator.new(
+          notion_resource: notion_resource,
+          site: site,
+          plugin: plugin
+        )
+      end
+    end
+  end
+end

data/lib/jekyll-fetch-notion/file_creator.rb

@@ -0,0 +1,29 @@
+module JekyllFetchNotion
+  class FileCreator
+    attr_reader :path, :content
+    def initialize(path, content)
+      @path = path
+      @content = content
+    end
+
+    def create!
+      ensure_directory_exists
+      write_file
+    end
+
+    private
+
+    def ensure_directory_exists
+      dir = File.dirname @path
+      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+    end
+
+    def write_file
+      File.open(@path, "w") do |f|
+        f.puts(@content)
+      end
+
+      Jekyll.logger.info "File #{@path} #{"OK".green}"
+    end
+  end
+end

data/lib/jekyll-fetch-notion/generators/abstract_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module JekyllFetchNotion
+  class AbstractGenerator
+    def initialize(notion_resource:, plugin:)
+      @notion_resource = notion_resource
+      @plugin = plugin
+    end
+
+    def generate
+      raise "Do not use the AbstractGenerator class. Implement the generate method in a subclass."
+    end
+
+    def resource_id
+      @notion_resource.id
+    end
+  end
+end

data/lib/jekyll-fetch-notion/generators/collection_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module JekyllFetchNotion
+  class CollectionGenerator < AbstractGenerator
+    attr_reader :config
+
+    def initialize(notion_resource:, plugin:, config:)
+      super(
+        notion_resource: notion_resource,
+        plugin: plugin
+      )
+      @config = config
+    end
+
+    def generate
+      @notion_resource.fetch.each do |page|
+        make_doc(page)
+        log_new_page(page)
+      end
+    end
+
+    private
+
+    def make_doc(page)
+      FileCreator.new(make_path(page), make_md(page)).create!
+    end
+
+    def make_path(page)
+      "#{@config["source"]}/_#{@notion_resource.collection_name}/#{make_filename(page)}"
+    end
+
+    def make_filename(page)
+      if @notion_resource.collection_name == "posts"
+        "#{date_for(page).strftime("%Y-%m-%d")}-#{Jekyll::Utils.slugify(page.title, mode: "latin")}.md"
+      else
+        "#{Jekyll::Utils.slugify(page.title, mode: "latin")}.md"
+      end
+    end
+
+    def make_md(page)
+      NotionToMd::Converter
+        .new(page_id: page.id)
+        .convert(frontmatter: true)
+    end
+
+    def log_new_page(page)
+      Jekyll.logger.info("Jekyll Notion:", "Page => #{page.title}")
+    end
+
+    def date_for(page)
+      # The "date" property overwrites the Jekyll::Document#data["date"] key
+      # which is the date used by Jekyll to set the post date.
+      Time.parse(page.props["date"]).to_date
+    rescue TypeError, NoMethodError
+      # Because the "date" property is not required,
+      # it fallbacks to the created_time which is always present.
+      Time.parse(page.created_time).to_date
+    end
+  end
+end

data/lib/jekyll-fetch-notion/notion_database.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module JekyllFetchNotion
+  class NotionDatabase < AbstractNotionResource
+    # Returns an empty array or a NotionToMd:Page array
+    def fetch
+      return [] unless id?
+
+      @fetch ||= @notion.database_query(query)[:results].map do |page|
+        NotionToMd::Page.new(
+          page: page,
+          blocks: build_blocks(page.id)
+        )
+      end
+    end
+
+    def filter
+      config["filter"]
+    end
+
+    def sorts
+      config["sorts"]
+    end
+
+    def collection_name
+      config["collection"] || "posts"
+    end
+
+    def data_name
+      config["data"]
+    end
+
+    private
+
+    def query
+      {
+        database_id: id,
+        filter: filter,
+        sorts: sorts
+      }.compact
+    end
+  end
+end

data/lib/jekyll-fetch-notion/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JekyllFetchNotion
+  VERSION = "0.1.0"
+end

data/lib/jekyll-fetch-notion.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "notion"
+require "notion_to_md"
+require "logger"
+require "jekyll-fetch-notion/commands/fetch_notion"
+
+NotionToMd::Logger.level = Logger::ERROR
+
+Notion.configure do |config|
+  config.token = ENV["NOTION_TOKEN"]
+end
+
+module JekyllFetchNotion
+  autoload :DatabaseFactory, "jekyll-fetch-notion/factories/database_factory"
+  autoload :AbstractGenerator, "jekyll-fetch-notion/generators/abstract_generator"
+  autoload :CollectionGenerator, "jekyll-fetch-notion/generators/collection_generator"
+  autoload :AbstractNotionResource, "jekyll-fetch-notion/abstract_notion_resource"
+  autoload :NotionDatabase, "jekyll-fetch-notion/notion_database"
+  autoload :FileCreator, "jekyll-fetch-notion/file_creator"
+end

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-fetch-notion
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Enrique Arias
+- Daniil Sivak
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-01-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: notion-ruby-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: notion_to_md
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+- !ruby/object:Gem::Dependency
+  name: rubocop-jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+description:
+email:
+- emoriarty81@gmail.com
+- seroperson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/jekyll-fetch-notion.rb
+- lib/jekyll-fetch-notion/abstract_notion_resource.rb
+- lib/jekyll-fetch-notion/commands/fetch_notion.rb
+- lib/jekyll-fetch-notion/factories/database_factory.rb
+- lib/jekyll-fetch-notion/file_creator.rb
+- lib/jekyll-fetch-notion/generators/abstract_generator.rb
+- lib/jekyll-fetch-notion/generators/collection_generator.rb
+- lib/jekyll-fetch-notion/notion_database.rb
+- lib/jekyll-fetch-notion/version.rb
+homepage: https://github.com/seroperson/jekyll-fetch-notion
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.22
+signing_key:
+specification_version: 4
+summary: A Jekyll plugin to generate pages from Notion
+test_files: []