【提案】astro-notion-blogのコンポーネント分離とnpm登録

varubogu commented 1 month ago

一定数の需要があるんじゃないかなと思って提案させていただきます。 astro-notion-blogの「NotionページをAstroに落とし込む」というロジックを別なリポジトリに分離し、npmパッケージに登録して再利用しやすくするというのはどうでしょうか？

主なメリットについて

テンプレートとコンポーネントが明示的に分離される

このリポジトリはブログとしてのテンプレートもセットになっていることがメリットでありデメリットでもあります。主なメリットは

すぐ始められる
あまり知識を持たなくても始められる

といった手軽さにありますが、その一方でカスタマイズを多くした人から見ると

更新があった時、不要なプルリクエストの可能性がある（自分のテンプレートでは使っていないパーツなど）
更新があった時、conflictが発生するおそれがある

といったように手間が増える場合があります。私もNotion見出し1～3→HTMLタグh2～h4にカスタムしているのでconflictが何度か発生しました。 ※この件についてはまた触れたいことがあるので別のIssueで触れさせていただきます。

ブログのテンプレート化がしやすくなる

上記の通り分離されるため、テンプレート化がしやすくなると思います。

既にあるAstroプロジェクトの一部としてastro-notion-blogのコンポーネントをページ単位、コンポーネント単位で取り込めるようになる

現状Astroで運営しているサイトがあり、後からastro-notion-blogを知ったという場合でもnpmパッケージを取り込んで多少弄るだけで使えるようになります。また、私は右側のサイドメニューを追加して常にHeadlineを表示しているのですが、そういったこともしやすくなります。

更新があった場合、`npm update`で解決する

プルリクを取り込む作業よりも、競合が確実に発生しなくなる分だけ若干手軽さが増えると思います。

componentsディレクトリの内容がすっきりする

プロジェクトから以下が消えるので多少スッキリします。（微差）

src/components/notion-blocks配下一式
src/components/NotionBlocks.astro

（おそらく）astro-notion-blogのコンポーネントをオーバーライドして使える

上記の通り、コンポーネントをカスタマイズした場合は現状だとconflictになる恐れがあります。しかし、npmパッケージにすることによってオリジナルの実装を残したままコンポーネントをオーバーライドすることができるようになる…はずです。（やってみないとわからない）例えば見出し1の出力を、現状のh3タグからh2タグに変えたい場合、コードを流用して以下のように書くことができます。

元コード https://github.com/otoyo/astro-notion-blog/blob/main/src/components/notion-blocks/Heading1.astro

---
- import * as interfaces from '../../lib/interfaces.ts'
- import { buildHeadingId } from '../../lib/blog-helpers.ts'
- import RichText from './RichText.astro'
- import NotionBlocks from '../NotionBlocks.astro'
+ import * as interfaces from 'astro-notion/lib/interfaces.ts'
+ import { buildHeadingId } from 'astro-notion/lib/blog-helpers.ts'
+ import RichText from 'astro-notion/component/RichText.astro'
+ import NotionBlocks from '.astro-notion/component/NotionBlocks.astro'

export interface Props {
  block: interfaces.Block
  headings: interfaces.Block[]
}

const { block, headings } = Astro.props

const id = buildHeadingId(block.Heading1)
---

{
  block.Heading1.IsToggleable ? (
    <details class="toggle">
      <summary>
        <a href={`#${id}`} id={id}>
-          <h3>
+          <h2>
            {block.Heading1.RichTexts.map((richText: interfaces.RichText) => (
              <RichText richText={richText} />
            ))}
-          </h3>
+          </h2>
        </a>
      </summary>
      <div>
        {block.Heading1.Children && (
          <NotionBlocks blocks={block.Heading1.Children} headings={headings} />
        )}
      </div>
    </details>
  ) : (
    <a href={`#${id}`} id={id}>
-      <h3>
+      <h2>
        {block.Heading1.RichTexts.map((richText: interfaces.RichText) => (
          <RichText richText={richText} />
        ))}
-      </h3>
+      </h2>
    </a>
  )
}

<style>
-  h3 {
+  h2 {
    margin: 1.1em 0 0.3em;
    color: var(--fg);
    font-size: 1.8rem;
  }
  @media (max-width: 640px) {
-    h3 {
+    h2 {
      font-size: 1.3rem;
    }
  }

  .toggle {
    margin: 2rem 0 0;
  }
  @media (max-width: 640px) {
    .toggle {
      margin: 1.4rem 0 0;
    }
  }

  .toggle > summary {
    cursor: pointer;
  }

  .toggle > summary > a {
    display: inline;
  }

  .toggle > summary > a > h3 {
    display: inline;
  }

  .toggle > div {
    margin-left: 1em;
  }
</style>

分離のデメリット

リポジトリやnpmなど、管理対象が増える

最後に

もしotoyoさんがこれをやらない場合、私がそれを代わりにやってもいいでしょうか？ライセンス的にはそれをやっても大丈夫だと思うのですが、オーナーを差し置いてやるのもなぁとも思ってるので… GitHubリポジトリとnpmのオーナーをotoyoさん、コンポーネントの分離作業は私が行うでも構いません。

やる場合はこのリポジトリをforkしてブログ部分を削ぎ落とす感じになるかなと思います。メインの修正はこのリポジトリとして、forkしたコンポーネントのリポジトリはそれを取り込む。コンポーネントではなくブログに関する修正の場合、コンポーネントリポジトリはconflictを起こすと思いますが、このリポジトリを既に使っている方は私含め大勢いらっしゃると思いますし、下手にこのリポジトリを移行するとconflict祭りになるのが予想されるのでこのやり方になるかなと。過去のコミット履歴を引き継ぐという意味でも。より良いリポジトリ構成案があればそちらでもOKです。

ご検討よろしくお願いします。

otoyo commented 1 month ago

@varubogu 提案ありがとうございます。

更新があった時、不要なプルリクエストの可能性がある（自分のテンプレートでは使っていないパーツなど）更新があった時、conflictが発生するおそれがある

これらが解決したい問題ということ承知しました。こういった問題があることは開発者としても把握していました。問題を解決するために提案いただいた下記の手段もおもしろいと思います。

astro-notion-blogの「NotionページをAstroに落とし込む」というロジックを別なリポジトリに分離し、npmパッケージに登録して再利用しやすくする

一方、開発者の意図として astro-notion-blog を通してプログラミングに親しんでほしいというのがあり、Notionのデータ構造をどのようにHTMLに変換しているのかの部分を別パッケージにしてしまうと、煩雑さが減る反面、プログラミング初学者にとって該当コードの参照が難しくなるというデメリットもあります。さらに、Notionのデータ構造をHTMLに変換するためのライブラリはすでにいくつか存在するので、astro-notion-blogでやる必要性は薄いように感じます。また、更新時にコンフリクトが発生するという指摘については、最近で言えば活発にコミットをしていないので問題にはなっていないのではないかと思っています。

astro-notion-blogはOSSなので、ライセンスにさえ従っていただければご自身のリポジトリで自由に改変・再配布いただけます。私の許可を得る必要はないのでご安心ください。

varubogu commented 1 month ago

@otoyo ご確認ありがとうございます。

さらに、Notionのデータ構造をHTMLに変換するためのライブラリはすでにいくつか存在するので

これについては、Notionの構造をHTMLやmarkdownに落とし込むのはあると思いますが、直接Astroに落とし込むというものは現状他に無いと思います。それで今回コンポーネント化の提案をさせていただいたという感じです。

astro-notion-blogはOSSなので、ライセンスにさえ従っていただければご自身のリポジトリで自由に改変・再配布いただけます。私の許可を得る必要はないのでご安心ください。

ありがとうございます。上記に挙げた件、以下のリポジトリで進めていきます。 https://github.com/varubogu-organization/astro-notion-component

otoyo / astro-notion-blog