![\"riebeckite-logo-horizontal.png\"](\"/assets/riebeckite-logo-horizontal.png\"){kind=logo}
Riebeckite publishes Markdown and Obsidian-style notes as a static site. Write in content/, add plugins for search, diagrams, and localization, choose a theme, and build a static site you can deploy anywhere.
New here? Start with Getting Started. For every section in one place, see the Documentation index.
\nGetting a first site running goes: Quick Start → Installation → First Content → Presets → Deployment.
\n| I want to… | \nGo to | \n
|---|---|
| Use Riebeckite for the first time | \nQuick Start | \n
| Create a site and deploy it today | \nQuick Start → Deployment | \n
Choose which create-riebeckite preset to use | \n Presets | \n
| Write and organize articles | \nGuides / Writing content | \n
| Publish an Obsidian vault | \nGuides / Obsidian | \n
| Keep content and site in separate repositories | \nGuides / Content repositories | \n
| Build a multilingual site | \nGuides / Localization | \n
| Deploy to Cloudflare Workers / GitHub Actions | \nGuides / Deployment | \n
| Upgrade Riebeckite or read migration notes | \nGuides / Upgrading | \n
| Find and install a Plugin | \nPlugins | \n
| See Plugins in action | \nPlugin Showcase | \n
| Change the look of my site | \nThemes | \n
| Keep the site usable for more people | \nAccessibility | \n
| Understand the trust model | \nSecurity model | \n
| Look up configuration, CLI, or an API | \nReference | \n
| Understand how Riebeckite works inside | \nFramework | \n
| Contribute to Riebeckite itself | \nFramework / Development | \n
my-site/\n├─ content/ Markdown pages and assets\n├─ app/ Site UI generated by the preset\n├─ riebeckite.config.ts Site title, URL, theme, and plugins\n└─ package.json Local commandsA site author mainly edits content/ and riebeckite.config.ts. Internal architecture is documented in Framework.
For coding agents and automation, use the concise, rule-oriented Agent documentation.
\n","summary":"Riebeckite is an open-source framework for publishing Markdown and Obsidian notes as a website.","tags":[]},{"id":"https://riebeckite.dev/README","url":"https://riebeckite.dev/README","title":"README","content_html":"\nRiebeckite は、Markdown や Obsidian のノートから公開サイトを作るためのフレームワークです。
\nMarkdown を content/ に置くだけのシンプルなサイトから、プラグイン、テーマ、多言語化、外部の Obsidian Vault を使うサイトまで構築できます。
初めて使う場合は、Riebeckite のリポジトリをクローンする必要はありません。
\ncreate-riebeckite から新しいサイトを作成します。
基本的な流れは次のとおりです。
\nflowchart LR\n Create[\"サイトを作る\"]\n Content[\"Markdownを書く\"]\n Dev[\"ブラウザで確認\"]\n Build[\"ビルド\"]\n Deploy[\"デプロイ\"]\n \n Create --> Content\n Content --> Dev\n Dev --> Build\n Build --> Deployまず クイックスタート から始めてください。
\n順番に進めたい場合は、
\n\nの順で読めます。
\n全章の一覧は ドキュメント索引 にあります。
\nサイトを作成したら、基本的には次の流れで使います。
\ncreate-riebeckite\n ↓\ncontent/ に Markdown を書く\n ↓\nriebeckite dev\n ↓\nブラウザで確認\n ↓\nriebeckite build\n ↓\ndeploy普段サイトを作るだけなら、Riebeckite 本体の内部構造を理解する必要はありません。
\n目的に近いページから読めます。
\n| 目的 | \n読むページ | \n
|---|---|
| 初めて Riebeckite を使う | \nクイックスタート | \n
| インストール方法を確認する | \nインストール | \n
| 最初の記事を書く | \n最初の記事 | \n
| サイトの構成を選ぶ | \nプリセット | \n
| デプロイする | \nデプロイ | \n
| デプロイ先ごとの手順を確認する | \nデプロイガイド | \n
| Markdown と frontmatter の書き方を知る | \nコンテンツの書き方 | \n
| Obsidian Vault を公開する | \nObsidian | \n
| コンテンツとサイトを別リポジトリにする | \nコンテンツリポジトリ | \n
| 多言語サイトを作る | \n多言語化 | \n
| Riebeckite を更新する | \nUpgrading | \n
| プラグインを探す | \nプラグイン | \n
| テーマを選ぶ | \nテーマ | \n
| アクセシビリティの責任範囲を確認する | \nアクセシビリティ | \n
| セキュリティと信頼モデルを確認する | \nセキュリティモデル | \n
| 設定や CLI、Public API を調べる | \nリファレンス | \n
| Riebeckite の内部構造を理解する | \nフレームワーク | \n
| Riebeckite 本体を開発する | \nフレームワーク開発 | \n
Riebeckite のドキュメントは、目的ごとに分かれています。
\nflowchart TD\n Docs[\"Riebeckite Docs\"]\n \n Docs --> Getting[\"Getting Started<br/>使い始める\"]\n Docs --> Guides[\"Guides<br/>具体的な作業\"]\n Docs --> Plugins[\"Plugins<br/>機能を追加する\"]\n Docs --> Themes[\"Themes<br/>見た目を選ぶ\"]\n Docs --> Reference[\"Reference<br/>設定・CLI・API\"]\n Docs --> Framework[\"Framework<br/>内部構造\"]\n \n Framework --> Development[\"Development<br/>本体開発\"]初めて Riebeckite を使う人向けのページです。
\nサイトの作成から最初の記事、プリセット、デプロイまでを扱います。
\n具体的な目的を達成するための手順です。
\nたとえば、
\nといった作業を扱います。
\nRiebeckite に機能を追加するプラグインを探すためのページです。
\n記事表示、検索、グラフ、Mermaid、Excalidraw など、必要な機能に応じてプラグインを追加できます。
\nサイトの見た目を変更するテーマを探すためのページです。
\nテーマを変更しても、コンテンツやプラグインの機能そのものは変わりません。
\n設定値、CLI コマンド、Public API を調べるための資料です。
\n「この設定は何を意味するのか」「この API は何を提供するのか」を確認したいときに利用します。
\nRiebeckite の内部構造を理解したい人向けです。
\nコンテンツシステム、プラグインシステム、テーマシステム、ビルドシステム、HonoX 連携などを説明します。
\n通常のサイト利用では読む必要はありません。
\nRiebeckite には大きく2つの使い方があります。
\nflowchart TD\n User{\"あなたの目的\"}\n \n User -->|\"Riebeckiteでサイトを作る\"| Site[\"create-riebeckite\"]\n User -->|\"Riebeckite自体を開発する\"| Framework[\"Riebeckiteリポジトリ\"]\n \n Site --> Getting[\"Getting Started / Guides\"]\n Framework --> Dev[\"フレームワーク開発\"]Riebeckite のリポジトリはクローンしません。
\ncreate-riebeckite から始めます。
create-riebeckite\n ↓\n生成されたサイト\n ↓\ncontent/\n ↓\ndev / build\n ↓\ndeploy普段利用するのは、生成されたサイト側です。
\nRiebeckite 自体へ変更を加える場合だけ、リポジトリをクローンします。
\nこの場合は、
\npnpm コマンドpackages/*apps/webなどを扱います。
\n詳しくは フレームワーク開発 を参照してください。
\napps/web は Riebeckite のドキュメント兼参照アプリです。一般ユーザーがサイトを作るためのテンプレートではありません。
どこを読めばよいか分からない場合は、次の基準で選べます。
\nflowchart TD\n Start[\"何をしたい？\"]\n \n Start --> First{\"初めて使う？\"}\n First -->|Yes| Getting[\"Getting Started\"]\n First -->|No| Task{\"具体的な作業をしたい？\"}\n \n Task -->|Yes| Guides[\"Guides\"]\n Task -->|No| API{\"設定・CLI・APIを調べたい？\"}\n \n API -->|Yes| Reference[\"Reference\"]\n API -->|No| Internal{\"内部の仕組みを知りたい？\"}\n \n Internal -->|Yes| Framework[\"Framework\"]\n Internal -->|No| Plugins[\"Plugins / Themes\"]簡単に分けると、
\n初めて使う\n → Getting Started\n \n具体的な作業をする\n → Guides\n \n機能や見た目を追加する\n → Plugins / Themes\n \n設定・CLI・APIを調べる\n → Reference\n \n内部構造を理解する\n → Framework\n \nRiebeckite本体を変更する\n → Framework Developmentです。
\nCoding Agent 向けの短い開発ルールは agents に分けています。
\n","summary":"Riebeckite ドキュメント Riebeckite は、 Markdown や Obsidian のノートから公開サイトを作るためのフレームワーク です。 Markdown を content/ に置くだけのシンプルなサイトから、プラグイン、テーマ、多言語化、外部の Obsidian Vault を使うサイトまで","tags":[]},{"id":"https://riebeckite.dev/assets/HW","url":"https://riebeckite.dev/assets/HW","title":"HW","content_html":"\n⚠ Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠ You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'
\nHello Riebeckite!
\nBy Rerurate_514
\nriebeckite.dev
\nac4cfc9875041e60cc32b2ff448c2192786e0f2f: riebecite-ogp.png
\n%%
\n![riebecite-ogp.png](\"/assets/riebecite-ogp.png\"){kind=link}
N4KAkARALgngDgUwgLgAQQQDwMYEMA2AlgCYBOuA7hADTgQBuCpAzoQPYB2KqATLZMzYBXUtiRoIACyhQ4zZAHoFAc0JRJQgEYA6bGwC2CgF7N6hbEcK4OCtptbErHALRY8RMpWdx8Q1TdIEfARcZgRmBShcZQUebR4ADm0ARho6IIR9BA4oZm4AbXAwUDBSiBJuCAB2UgARCgArZQBFAAU00shYREqoLCgOssxuZwA2ABYq7UmABirRgGYZxYWA\n \nTlGAVn4ymBHk0dHtNYT9nhnxjaXxviLIChJ1bmTVpKqq5IST5JmFjeSN0Y3TpSBCEZTSbgLOLPVawuHw2GjbaQazKYLcGbIiDMKCkNgAawQAGE2Pg2KRKgBiZIIGk0waQTS4bD45R4oQcYgkskUiS46zMOC4QI5BkQABmhHw+AAyrB0RJBB4xTi8YSAOoPSTcIFlVUEhBymAK9BKipY9ngjjhPJoZJYthC7BqXZ2maY24QNnCOAASWIttQ+QAulj\n \nxeQsv7uBwhNKsYROVhKrgZmL2ZzrcxAzG456wghiE9RskeB8qqsZltPYwWOwuGhxr8sTXWJwAHKcMQ65IlqoJWFVcbx5i1DJ9QtocUEMJYzTCTkAUWCWRygZDWKEcGIuHHT3LPZOm1WkyHnuwgR3Bb3Fb760WlYWWLJLKvk+nCCxfUwAwkAAkgmSqAAEqEAgmgICyagIAAhGmlAACr9JU/7SmwwGgeBkF9LBYacFAMqEEY4i8Aks6hAgABieEEUR\n \n0axvguE5BRuD6FKrqoFUn79AAgkQyj1ugwTigMzZMFA5gELxYICdAjpinoOS4AmTBRmgOYMZ65JggmBCId+yEAWhIFgRB+JQThnq4EIUBsEB4SEcRuJCB+npENa/5ghCdopFWwL4Lg4H4K0bCsOJnB0bmwKSKEelQAAMgm+LcFO+Azq5iURfgRQAL7bCUZQVBI6pwNxyQwDwCBxWK3TEdASFYsMaDOJcUy9gs4yLDwSyApxnrsc4CxJAs8ztQCMw\n \n8Ks7wnFi9zEI8drPCkw2rGsFwLCWvllJIoLgj+qAfNoPyjcNPwTDw4yVliqImh6wL6oS3LklSdK0kgZEst6HJcqST18uQHCCsK2QiZ6krSkaJrYqS5p5riBqanN2poLqAhw4SEO1WahYWsIVo2k8DpOi6Tzulin1+gGBShqDEYIKpqDqfGiaNeguAbGm87EJm2b0Vi+YTqgfzjAkowVhsvXAi2dbcBs4z2tWTCthwHYcF2drjC8CQa4Nw6jsEu5v\n \nqlLnAnOX1LpkwNrtTwKbtuBv7fuHz7ICCRnFi54hPbyTlnM/aDnM61PmwL4CylaXAl+e0QAAQjAwFMCIl4APpC3BFCxZUsfx6Qid9CnyTjGK4rUQ5TzjNMPCjPME2AqsyRrDwm2MuRVE5DRxGM6DeHMax+DsU3dXflJ/GVEJIOS2JEn4MPMk2XA8l4Up1qkPTnfAlp/i6UhEhZ3ZOfkHnqdXdZtn2bRaBOcbZRuQgHm7U88QD/5gXBaF0tqbznrR\n \ncwsUJRwSWG3DtfDKH9pQ5Typ6Qq6BfQcE0AAKVGAAVXoElT88BaqEH0NEN6noWZjCWNMUYWtxofGPO6VYWJ+r1ziAsYssIfgdQWLQ08wJZrzX2oCbQ/tvZixeBsGYCQB7bU8ntQR8Qq6lnGHLcs7xJhXQ4GiYit09Ro2JD9Xk6B+QAyFCKceZQmQfXTN9HkvR/qA10UXKUsp5S1WitgDQgQVSqIRuw+Wd1VEY0qFjDmfhJDcwJppImsASbKMgEY/\n \nxoCNJ3QQK+VALw5ZIgVrWcKdpiyiWScrTsxEC51wBIIkWG4tyXgFjwg8zt66Dl1mOWJYcr6QHJv6K2s5ObmxXLkKmT4QEM0/n5YOhJQ7vjDLTVePStoxX6H/ABqBanuwvF7R2h4ur+zDFKOmAsIDMnGNgcU2AXhVH4XLBAowZjYGwFCTQPBxTiikQkbApZVg8D7KMBAMxxSXJVO4YihROhgDcZ0ZItxrZlHPHJSJTNiBJgkLgUYEBwFFHypAKBEA\n \ngL0GYgAWQXAALSENVdBvR6q4JGBMBYRxK5LH4f8AunxKEjF+NoDYPAupV2uBdB5giZpam4OWaYPxBGNiqDMHs7wKFfx2l5faA9rpKL5qox6GiIDUlevSd6rIjFytMQKHRwNLHgxsV46G2NYZqgQC4pGvAZXGs8YqA1Pi8ZZgCevIJ7FvihK9OyCmTSaYsTWZlcFkLWYJB8RmfGYK8wxJKRcBlk0Vquqlik1ARD0lKxVmrQWsJvZCyqfrGpgzPSm0\n \nXMuS2vrPS22KdeMpRDvbnVmZ7WJpSnYHEHE2VyfSc1Gy4vpCQpAMKmSgtoCF9A04Zy7T2rCCB+0IEHYxfCpc7QowgEyMIrcZ3n26ZFMoxcmIsTYjLDtUAZ6jwQMJMUNZxLuAPXyOS7tF7KRXgLNeZQN46XwMO9A3aTJjonVOyyJ87KsFXZfTp7kxV7WSI/J8AUgivzUO/NdUSxk/wmV02pcLSgIvKOsowAA1UgAANAA8hQfE0dcU9D5AS4EeCDjl\n \n3LLLYWTaKwvBpU1c68R9kAkGlURIDzBUcsRjLcRawHlLFWOLH4G0sTCPvmgKEKQETycRPIxRGILUGnVRIRVL0xQGNVZzdTmizFatFCs3VxpMY2tUxqTlyNLOGj1da5UONfERP2oTZkxM3SuoaZTNA64vWRnvaMxFzNkxVCDVzENcG+bhqeINS4RCLikSSUrLlSa6wpuIschIgrGyusICOapAtAN5paYW1cxabZFPmXXBtFwpEiuBB7MtdoFn7DWJ\n \nsFh19W0DPbZ6SOlQh3b3QEXEuq7EhkSXaNjuQWJTd23X3VLfWeJ8RkmPE9k9z0rd6Fes8N7l4jPXZAJ9HAt6duG8fGyf7Z2oGK35ZSd9xVgf+BBl+IUYPxofZAb+v9kPvhyuAa2Gy4BwDlJebg+VoDbSyKPERgwGCgQoNHZkumvr6YVVcjH4o4fYBELo30fR9BymNWjzTr1se4+BvjzISPDF6fURq7RQNjNFAgDj0geOCcUSsVa00FmWds455kOU\n \n5h8QwA4GwPoRO1P040y9ZV/OKc5Cp4T5xWoADSCB2IQCyI4IQ+hyfs8pwTqXhIsPCisJoKUHn0AKRxNYPRrPFdQGVybuzZn9WOYV4bpXBOgK4z8ZFv5jvvfO4J/hp1ITtjB8F/oZdPcd1oE2tHo3mRl3tyeLqZPPvMixQvYJI9DuBcp5V8Kfd7O2AUG2rgQL66s+h8yAuTk3Fy+V5COs4UeIqBR6L9n/QzfO/wTxV2zmBuY8UVpn7k0D7sQgulLh\n \nrlaxH4bArGcfZLx9hR+YLP/AABNHUjZ4iTQSN1Dq1wqiBxZ0YNgBhwfVgIM5B+ona6jFQ5AHv9f9B+6+i5iARi4dshIHT2RmUTdUAL6HnkTyjwAOIDRTYAhUbwCmCB6yAVAOMV+lQHQ2jlJHWVIGUCZAAAoeFqAHYKESDiCZh6UABKMUOyZQWMYUSoXAggs4IcXgc4Yglg8gqg2FUoXKfndReCR0VoEXQMdDDINpV3CrMocQ4GGnFHTkKQxkIQF8\n \nKALnaURQ7EM9UXDsSXVRDQnEEXGAHQhAOQz6BQyJV/WbHIQQuAYQlkHmWvd/V3cPMKAGKQiUCfbICFbtBRW/YEbIRA2JW7YFIgCAm7HOOpCAE7aHC+CIh0ayG+bgYIyALBUgQkUgNsb1JIuIz0VI9IhAzQJA7I5ySwuwBoCCXIGUE7OAWA+Ak7QottFA5kcSRgQQ0kPwsoGqLxDIbAVw+SIQHEAwQfMjKLFtEOZKXNYEcMAwGUHovowBSI/yHEbi\n \nXowgVo6/fATKSwxwZgQIkkHIfoNFbIHFBYqPS3TkBMZQVoQIcUJgbIVNDAeoooqPfLNFEgOANgBMfCaouAS4gooo2I5yM4tgTAWY4IVYzgWo2qBSKIBMOHBMOAayUcMwB4qyGyHgvgyAMGcIcHbKEAbKIAA=%%
\n","summary":"⚠ Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠ You can decompress Drawing data with the command palette: 'Decompress current Excalidra","tags":["excalidraw"]},{"id":"https://riebeckite.dev/en/docs/","url":"https://riebeckite.dev/en/docs/","title":"Documentation","content_html":"\nStart with Getting Started to create and publish a Riebeckite site. Use the sections below to explore the framework, extend it with plugins, and customize its appearance.
\n\n","summary":"Documentation Start with Getting Started to create and publish a Riebeckite site. Use the sections below to explore the framework, extend it with plugins, and c","tags":[]},{"id":"https://riebeckite.dev/docs/","url":"https://riebeckite.dev/docs/","title":"ドキュメント","content_html":"\nRiebeckite でサイトを作成して公開するまでの流れは、Getting Started から確認できます。フレームワークの仕組み、Plugin による拡張、見た目の調整は、以下の各章を参照してください。
\n\n","summary":"ドキュメント Riebeckite でサイトを作成して公開するまでの流れは、 Getting Started から確認できます。フレームワークの仕組み、Plugin による拡張、見た目の調整は、以下の各章を参照してください。 Getting Started ガイド フレームワーク Plugin Theme リファレンス","tags":[]},{"id":"https://riebeckite.dev/en/docs/accessibility","url":"https://riebeckite.dev/en/docs/accessibility","title":"Accessibility","content_html":"\nRiebeckite aims to follow WCAG 2.2 AA guidance, but it does not make a blanket compliance claim. The accessibility of a published site depends on Riebeckite, the selected Theme, enabled Plugins, author content, and custom code.
\nRiebeckite uses native HTML first and adds ARIA only when native HTML cannot express the needed behavior or state.
\nlang, viewport metadata, page title, and theme attributes.header, main, article, aside, footer, and nav where those structures exist.<a href> elements, and actions use real <button type=\"button\"> elements.alt text or mark decorative images with empty alt.When a Plugin renders UI:
\ndiv or span elements.Escape, and restore focus to the opener.aria-expanded, aria-pressed, aria-current, and aria-selected synchronized with the real state.prefers-reduced-motion for motion that could distract or block understanding.Themes are responsible for visual accessibility:
\n:focus-visible style.prefers-reduced-motion / prefers-reduced-motion: no-preference.alt text for meaningful images and empty alt for decorative images.The official audit covers Core/HonoX rendering, generated scaffolds and presets, official Themes (default, minimal, gruvbox, tokyonight, sakura, rerurate), and official UI-generating Plugins including search, color mode, UX helpers, table of contents, lightbox, gallery, local graph, garden explorer, code tabs, code enhance, share, properties, recent/related posts, taxonomy, query/dataview/bases, flashcards, kanban, media, and diagram/visual Plugins.
Riebeckiteでは、キーボード操作やスクリーンリーダー、文字の見やすさなど、さまざまな環境でサイトを利用できることを大切にしています。
\nWCAG 2.2 AAを参考にしていますが、最終的なサイトのアクセシビリティは、使用するThemeやPlugin、記事の内容、独自に追加したコードによっても変わります。
\nRiebeckiteが生成する基本的なページでは、ブラウザや支援技術がページの構造や操作方法を正しく理解できるようにしています。
\nたとえば、
\nといった対応を行っています。
\n画像については、Riebeckiteが内容を推測して説明文を自動生成することはありません。意味のある画像には、記事やPlugin側で適切な説明を付けてください。
\nボタンやメニューなどのUIを持つPluginでは、マウス以外でも操作できるようにしてください。
\n基本的には、次の点を意識すれば十分です。
\ndiv や span はできるだけ使わないEscape でも閉じられるようにするGraph、Chart、Mapなどの視覚的なコンテンツでは、複雑な図そのものを無理に読み上げ可能にするより、必要に応じて説明文やキャプション、元データなどの代替情報を用意してください。
\nThemeでは、特に「見やすさ」と「操作している場所の分かりやすさ」が重要です。
\n次の点に注意してください。
\n特に outline: none などでキーボード操作時の表示を消す場合は、代わりに現在位置が分かる表示を用意してください。
記事側でも、少し意識するだけで読みやすさを改善できます。
\n公開前に、マウスを使わず Tab キーだけでも主要な操作ができるか確認してみるのもおすすめです。
Riebeckiteでは、標準のページ構造だけでなく、公式ThemeやUIを持つ公式Pluginについてもアクセシビリティを確認しています。
\nSearch、Color Mode、目次、Lightbox、Gallery、Graphなどの操作を伴う機能や、各Themeでの文字・リンク・フォーカス表示などが主な対象です。
\nただし、Riebeckiteを使っているだけで、すべてのサイトが自動的にアクセシブルになるわけではありません。
\n使用するThemeやPlugin、記事の内容も含めて、サイト全体で使いやすさを考えることが大切です。
\n","summary":"アクセシビリティ Riebeckiteでは、キーボード操作やスクリーンリーダー、文字の見やすさなど、さまざまな環境でサイトを利用できることを大切にしています。 WCAG 2.2 AAを参考にしていますが、最終的なサイトのアクセシビリティは、使用するThemeやPlugin、記事の内容、独自に追加したコードによっても変わ","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/","url":"https://riebeckite.dev/en/docs/framework/","title":"Framework","content_html":"\nFramework documentation is for people who want to understand or develop Riebeckite itself. If you only want to build a site, start with Getting Started and use Reference when you need exact fields or commands.
\n| I want to understand… | \nPage | \n
|---|---|
| Package ownership and dependency direction | \nArchitecture | \n
| How Markdown and assets become pages | \nContent system | \n
| How plugins are resolved and run | \nPlugin system | \n
| How plugins provide standalone pages | \nPage system | \n
| How themes interact with CSS and plugin output | \nTheme system | \n
| Incremental builds, build state, and plugin cache | \nBuild system | \n
| How plugins declare build dependencies | \nBuild dependency contract | \n
| The HonoX/Vite adapter boundary | \nHonoX integration | \n
| Diagnostics and Doctor | \nDiagnostics | \n
| Read-only inspection commands | \nInspector | \n
| Logger, Tracer, and Profiler | \nObservability | \n
| Test layout and golden files | \nTesting | \n
| The monorepo development workflow | \nDevelopment | \n
The Riebeckite monorepo clone workflow is intentionally here, not in Getting Started. Use it only when you are changing Riebeckite itself: Development.
\n","summary":"Framework Framework documentation is for people who want to understand or develop Riebeckite itself. If you only want to build a site, start with Getting Starte","tags":[]},{"id":"https://riebeckite.dev/docs/framework/","url":"https://riebeckite.dev/docs/framework/","title":"Framework","content_html":"\nこの章では、Riebeckite 自体がどのように動いているかを説明します。
\n対象となるのは、
\nです。
\nRiebeckite を使って自分のサイトを作りたいだけなら、この章を最初から読む必要はありません。Getting Started から始めてください。
\nflowchart LR\n Start[\"Riebeckiteを使いたい\"]\n \n Start --> Q{\"何をしたい？\"}\n \n Q -->|\"サイトを作る\"| GettingStarted[\"Getting Started\"]\n Q -->|\"仕組みを理解する\"| Framework[\"Framework\"]\n Q -->|\"Riebeckite本体を開発する\"| Framework\n \n Framework --> Architecture[\"Architecture\"]\n Framework --> Development[\"Development\"]目的に合わせて、必要なページだけ読めます。
\n| 知りたいこと | \nページ | \n
|---|---|
| Riebeckite 全体の構造 | \nArchitecture | \n
| Markdown や Content がどう処理されるか | \nContent System | \n
| Plugin がどう動くか | \nPlugin System | \n
| Plugin が独立したページを提供する仕組み | \nPage System | \n
| Theme が見た目を変更する仕組み | \nTheme System | \n
| Build と Incremental Build の仕組み | \nBuild System | \n
| Plugin が build dependency を宣言する仕組み | \nBuild Dependency Contract | \n
| Riebeckite と HonoX / Vite の接続 | \nHonoX Integration | \n
| 設定や Content の問題を調べる | \nDiagnostics | \n
| 解決済みの設定や状態を確認する | \nInspector | \n
| Log / Trace / Performance を調べる | \nObservability | \n
| Riebeckite のテストを書く・実行する | \nTesting | \n
| Riebeckite 本体を開発する | \nDevelopment | \n
まず Architecture を読むのがおすすめです。
\nRiebeckite は大きく、
\nflowchart BT\n App[\"Application\"]\n Integration[\"Integration\"]\n Plugin[\"Plugin\"]\n Theme[\"Theme\"]\n Core[\"Core\"]\n \n App --> Integration\n Integration --> Core\n Plugin --> Core\n Theme --> Coreという責務に分かれています。
\nArchitecture を読んだあと、変更したい領域に応じて Content System、Plugin System、Theme System などへ進むと理解しやすくなります。
\nRiebeckite repository を clone して Framework 自体を変更する場合は、Development を参照してください。
\nDevelopment では、
\npnpm installpnpm コマンドpackages/* の構成apps/webなどを扱います。
\nRiebeckite repository 自体を開発する\n → Framework / Development\n \nRiebeckite を使ってサイトを作る\n → Getting Startedapps/web は Riebeckite の Documentation / Reference Application です。
一般ユーザーが Riebeckite を使うために apps/web をコピーしたり、Riebeckite monorepo を clone したりする必要はありません。
Framework 章では、Riebeckite の内部設計と Framework 開発を扱います。
\n一方、
\nといった通常の利用方法は Getting Started や Guides で説明します。
\nこの境界を分けることで、Riebeckite を使うだけの人が Framework 内部の知識を覚えなくてもサイトを作れるようにしています。
\n","summary":"Framework この章では、 Riebeckite 自体がどのように動いているか を説明します。 対象となるのは、 Riebeckite の内部構造を理解したい人 Plugin や Theme の仕組みを詳しく知りたい人 Riebeckite 本体を開発・変更したい人 です。 Riebeckite を使って自分のサ","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/architecture","url":"https://riebeckite.dev/en/docs/framework/architecture","title":"architecture.en","content_html":"\nRiebeckite is a pnpm workspace with intentionally one-way dependencies.
\n| Area | \nOwns | \nMust not own | \n
|---|---|---|
packages/core | \n portable contracts, configuration, content orchestration, manifests, graphs, pipelines, plugin runtime, observability, and theme contracts | \nHonoX/Vite APIs, a named plugin, or application UI | \n
packages/plugins/* | \n reusable Markdown, HTML, metadata, asset, diagnostic, browser, and Page Type capabilities | \napplication routes or framework-specific routing | \n
packages/integrations/* | \n framework, bundler, and platform adapters | \nreusable domain policy already represented by Core | \n
packages/themes/* | \n presentation configuration and CSS | \ncomponents, routes, plugins, or content loading | \n
apps/web | \n the concrete routes, islands, application components, and Worker deployment | \nreusable framework contracts | \n
packages/cli | \n Node-oriented commands and build tooling | \nrequest-time application behavior | \n
Application -> Integration -> Core\nPlugin --------------------> Core contracts\nTheme ---------------------> Core theme contract\nCLI -----------------------> Core and integration APIsCore must never gain a reverse dependency on HonoX, a theme, a plugin, or the application. Put a concern at the first layer that can own it without importing an outer layer.
\nContentSource discovers and reads source material and supplies source metadata. ContentManager interprets that material, resolves each entry's public location, runs the pipeline and plugin hooks, creates the manifest and graph, and coordinates content-related work. Public URLs come from the resolved location (ContentManager.getContentLocations(): the Core default resolver, then resolveContentLocations plugin hooks); consumers read the resolved permalink and never derive a URL from a slug or filesystem path. A feature that needs files should use the source contract rather than adding a second filesystem scanner.
ContentSource -> ContentManager -> resolve public locations\n |-> parse/process pipeline\n |-> plugin hooks\n |-> manifest and content graph\n `-> integration/application renderingPlugins may extend the process through published contracts; they do not become a hidden second application layer. A Page Type contributes a framework-independent body and public paths, while the integration resolves it through a generic route and the application retains the document frame. Themes only style the rendered result through theme configuration, CSS tokens, stable hooks, and data-* attributes; they do not branch on Page Type IDs. See Page system.
The CLI, Inspector, Doctor, profiler traces, incremental state at .riebeckite/build/content-state.json, and filesystem plugin caches belong to Node/build time. They are not mutable dependencies of the Cloudflare Workers request runtime. Runtime code consumes generated application output and stable content data, not a writable .riebeckite directory.
This boundary keeps deployments reproducible: a failed build does not mutate the previous valid state, and a request cannot depend on local files that do not exist in a Worker.
\napps/web.See Content system, Plugin system, Theme system, and HonoX integration before changing a boundary.
\n","summary":"Architecture Package ownership Riebeckite is a pnpm workspace with intentionally one-way dependencies. Area Owns Must not own packages/core portable contracts, ","tags":[]},{"id":"https://riebeckite.dev/docs/framework/architecture","url":"https://riebeckite.dev/docs/framework/architecture","title":"architecture","content_html":"\nRiebeckite は、Core を中心に Plugin、Integration、Theme、Application を分離した pnpm workspace です。
\n重要な原則は、内側の package が外側の実装を知らないことです。
\nたとえば Core はコンテンツ処理の仕組みを提供しますが、
\nといったことは知りません。
\nflowchart BT\n App[\"Application<br/>apps/web\"]\n Integration[\"Integration<br/>packages/integrations/*\"]\n CLI[\"CLI<br/>packages/cli\"]\n Plugin[\"Plugin<br/>packages/plugins/*\"]\n Theme[\"Theme<br/>packages/themes/*\"]\n Core[\"Core<br/>packages/core\"]\n \n App --> Integration\n Integration --> Core\n CLI --> Integration\n CLI --> Core\n Plugin --> Core\n Theme --> Core矢印は依存方向です。
\nCore から Plugin、Integration、Application などへの逆向きの依存は作りません。
\nRiebeckite のコードは、責務ごとに package を分けています。
\n| 場所 | \n主な責務 | \n
|---|---|
packages/core | \n Riebeckite の共通基盤 | \n
packages/plugins/* | \n 再利用可能な機能拡張 | \n
packages/integrations/* | \n Framework / Bundler / Platform との接続 | \n
packages/themes/* | \n Theme と CSS | \n
packages/cli | \n CLI と Node 上の Build Tooling | \n
apps/web | \n 実際の Site Application | \n
packages/coreCore は、特定の Web framework に依存しない Riebeckite の基盤です。
\n主に次の機能を所有します。
\nCore は portable であることを重視します。
\nそのため、
\nHonoX\nVite\nCloudflare\n特定の Plugin\nSite 固有の UIなどへ依存させません。
\npackages/plugins/*Plugin は、複数の Site で再利用できる機能を追加します。
\nたとえば、
\nなどです。
\nPlugin は Core が公開している contract を利用して機能を拡張します。
\nflowchart LR\n Plugin[\"Plugin\"] --> Contract[\"Core Plugin Contract\"]\n Contract --> Pipeline[\"Content Pipeline\"]Plugin のために Core が特定 Plugin の実装を知るような依存関係にはしません。
\npackages/integrations/*Integration は Riebeckite と外部技術を接続します。
\nたとえば @riebeckite/honox は、
Riebeckite Core\n ↕\nHonoX / Viteを接続する役割を持ちます。
\nFramework、Bundler、Platform 固有の処理は Core ではなく Integration に配置します。
\n詳しくは HonoX Integration を参照してください。
\npackages/themes/*Theme は Site の見た目を変更します。
\n主に、
\ndata-* attributeを利用します。
\nTheme は presentation を担当しますが、Site の構造そのものは所有しません。
\nそのため Theme が、
\nを所有することはありません。
\napps/webapps/web は実際の Riebeckite Site Application です。
主に、
\nを所有します。
\nCore や Integration が「どう表示するか」まで決めるのではなく、最終的な Site の構造は Application が決定します。
\npackages/cliCLI は Node.js 上で実行される command と build tooling を担当します。
\nたとえば、
\nriebeckite build\nriebeckite check\nriebeckite doctor\nriebeckite inspect\nriebeckite profileなどの入口を提供します。
\nCLI は必要に応じて Core や Integration の機能を呼び出します。
\nコンテンツ処理では、大きく ContentSource と ContentManager の責務を分離しています。
flowchart LR\n Source[\"ContentSource\"]\n Manager[\"ContentManager\"]\n Location[\"Public Location\"]\n Pipeline[\"Parse / Pipeline<br/>Plugin Hooks\"]\n Result[\"Manifest / Graph\"]\n App[\"Application\"]\n \n Source -->|\"scan / read / metadata\"| Manager\n Manager --> Location\n Location --> Pipeline\n Pipeline --> Result\n Result --> App\n \n Plugins[\"Plugins\"] -->|\"hooks\"| PipelineContentSource は「コンテンツをどこから、どう読み込むか」を担当します。
主に、
\nmtimeなど、source に関する情報を提供します。
\nたとえば filesystem を使う Content Source ならファイルを読み込みますが、ContentManager 自身が filesystem を直接探索するわけではありません。
新しい Content Source を追加するときも、この contract を通します。
\nContentManager は読み込まれたコンテンツを処理します。
主に、
\nを担当します。
\nつまり、
\nContentSource\n ↓\nコンテンツを取得する\n \nContentManager\n ↓\nコンテンツを解決・処理するという分担です。
\nContentManager に独自の filesystem scan を追加するのではなく、ContentSource の contract を利用してください。
コンテンツの URL は filesystem path や slug から推測しません。
\nRiebeckite が明示的に Public Location を解決します。
\n基本的な流れは次のようになります。
\nflowchart LR\n Content[\"Content\"]\n Default[\"resolveDefaultContentLocation()\"]\n Hooks[\"resolveContentLocations<br/>Plugin Hooks\"]\n Manager[\"ContentManager<br/>getContentLocations()\"]\n Permalink[\"Resolved permalink\"]\n Consumer[\"Consumer\"]\n \n Content --> Default\n Default --> Hooks\n Hooks --> Manager\n Manager --> Permalink\n Permalink --> ConsumerConsumer は、この処理によって確定した permalink を使用します。
たとえば、
\ncontent/posts/hello.mdという filesystem path があっても、
\n/posts/helloになるとは限りません。
\nPlugin や config によって、
\n/blog/hello/へ解決されているなら、それが正式な公開 URL です。
\nそのため Consumer 側で、
\nfilesystem path → slug → URLのような再計算をしないでください。
\n解決済みの permalink が public URL の source of truth です。
Plugin は Page Type を使って、通常の Markdown content とは異なるページを提供できます。
\nただし Page Type は特定の Web framework に依存しません。
\nflowchart LR\n Plugin[\"Plugin\"]\n Page[\"Page Type<br/>path + body\"]\n Integration[\"Integration<br/>Route Resolution\"]\n Frame[\"Application<br/>Document Frame\"]\n \n Plugin --> Page\n Page --> Integration\n Integration --> FramePlugin が提供するのは、主に public path と page body です。
\nそれを実際の URL として処理するのは Integration、最終的な HTML document として組み立てるのは Application です。
\nPlugin が HonoX route や Site shell を所有する必要はありません。
\n詳しくは Page System を参照してください。
\nRiebeckite では、Build 時にだけ必要なものと、公開 Site の Runtime で必要なものを分離します。
\nflowchart LR\n subgraph Build[\"Build-time / Node.js\"]\n CLI[\"CLI\"]\n Doctor[\"Doctor\"]\n Inspector[\"Inspector\"]\n State[\"Incremental State\"]\n Cache[\"Plugin Cache\"]\n Profile[\"Profile / Trace\"]\n end\n \n Build --> Output[\"Generated Application<br/>Stable Content Data\"]\n \n Output --> Runtime[\"Runtime<br/>Cloudflare Workers\"]次のものは Build-time の情報です。
\n.riebeckite/build/content-state.jsonCloudflare Workers の request runtime は、これらを読み書きしません。
\nRuntime が利用するのは Build によって生成された application と、安定した content data です。
\nこれにより、Build の最適化用 state と公開 Site の動作を分離しています。
\nまた Build が失敗した場合、新しい不完全な state で以前の正常な state を置き換えません。
\n新しい機能を追加するときは、まず「どの package がその責務を持つべきか」を考えます。
\nflowchart TD\n Q{\"何を追加する？\"}\n \n Q -->|\"共通の型・contract・lifecycle\"| Core[\"Core\"]\n Q -->|\"再利用可能なContent機能\"| Plugin[\"Plugin\"]\n Q -->|\"HonoX / Vite / Platform接続\"| Integration[\"Integration\"]\n Q -->|\"Route / Page / Island\"| App[\"Site Application\"]\n Q -->|\"見た目・CSS・Token\"| Theme[\"Theme\"]判断の目安は次のとおりです。
\n| 追加するもの | \n配置先 | \n
|---|---|
| 持ち運べる型や lifecycle contract | \nCore | \n
| 再利用可能な content の振る舞い | \nPlugin | \n
| Vite / HonoX / Platform との接続 | \nIntegration | \n
| Route / Page composition / Island | \nSite Application | \n
| Visual token / CSS | \nTheme | \n
迷った場合は、その機能を成立させるために必要な最も内側の package に置きます。
\nただし、内側の package から外側へ依存させてはいけません。
\nたとえば、
\n「Plugin Page を HonoX で表示したい」からといって Core に HonoX のコードを追加するのではなく、
\nCore\n → framework-independent な Page contract\n \nPlugin\n → Page を提供\n \nHonoX Integration\n → Page を route と接続\n \nSite\n → 最終的な document を描画と責務を分割します。
\nこの境界を維持することで、Core や Plugin を特定の Site、Framework、Platform に固定せず再利用できます。
\n関連する設計については Content System、Plugin System、Theme System、HonoX Integration を参照してください。
\n","summary":"Architecture Riebeckite は、Core を中心に Plugin、Integration、Theme、Application を分離した pnpm workspace です。 重要な原則は、 内側の package が外側の実装を知らないこと です。 たとえば Core はコンテンツ処理の仕組みを提","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/build-dependency","url":"https://riebeckite.dev/en/docs/framework/build-dependency","title":"build-dependency.en","content_html":"\nCore owns incremental invalidation. A plugin does not compute which content is affected, and it does not keep its own dependency state. It declares a contract and lets Core decide what to reuse.
\nA plugin takes part in two independent contracts:
\nprocessedContentCache) decides which source content Core processes again.outputDependencies and context.output.emit) decides which emitted files Core writes again.flowchart LR\n Change[\"Content or file change\"] --> Content[\"Content dependency\"]\n Content --> Reprocess[\"Reprocess affected content\"]\n Reprocess --> Output[\"Output dependency\"]\n Output --> Rewrite[\"Rewrite affected outputs\"]processedContentCache states how Core may reuse a plugin's processed content between builds.
dependencyMode | \n Meaning | \n
|---|---|
none | \n Processing depends only on the source content, its frontmatter, the plugin options, and the declared version. | \n
tracked | \n Processing reads other content or files through Core. Core records those reads and reprocesses only the consumers. | \n
unsafe | \n Processing depends on inputs Core cannot observe, such as Git, network, time, or process state. Persistent reuse is disabled. | \n
A content-affecting plugin that declares no contract is treated as unsafe.
version names the contract. Core also includes the resolved plugin configuration in the cache key, so a change to the options, hooks, or version invalidates the cached entries.
Reads made through Core's content APIs become dependencies with stable identities.
\n| Kind | \nRecorded when | \nIdentity | \n
|---|---|---|
content | \n readContent, renderContent, renderNoteEmbed | \n content slug | \n
file | \n contentSource.read and helpers such as readContentSourceEntry | \n file path | \n
link | \n A link target is resolved to a permalink | \nlink id | \n
contentSource.scan() lists entries but creates no dependency. Direct filesystem, network, or clock access is invisible to Core, so those inputs belong to unsafe.
On a later build, Core looks up the cached processed content, then re-reads every recorded content, file, and link dependency and compares fingerprints. If any fingerprint changed, Core discards the entry and processes it again.
\nThe cache skips only Markdown and HTML processing. The post-processing hooks (onPostParsed, onPostProcessed) and the manifest hook (onManifestCreated) always run, so manifest-stage work belongs there.
Core persists each entry's dependency identities in build state and builds a reverse index from them. When a dependency changes, Core marks the dependent entry and propagates the invalidation to its dependents transitively. When content is added or removed, entries that link to a changed target are invalidated as well. On the first build, or whenever no previous state is available, every note is processed.
\nOutput dependencies are separate from content dependencies. Each type reacts to a different part of the change set.
\n| Type | \nAffected when | \n
|---|---|
content { slug } | \n That content changed. | \n
tag { tag } | \n Content carrying that tag changed. | \n
folder { folder } | \n Content in that folder changed. | \n
global | \n Any content changed. | \n
unknown | \n Always. Core also requests full output regeneration. | \n
Declare them in the following places.
\npageTypes[].outputDependencies for a plugin page.outputDependencies for a plugin that updates existing manifest entry HTML in onManifestCreated. Core adds them to every content output.context.output.emit(..., { dependencies }) for a generated output. Without declared dependencies, a generated output is unknown.Use content, tag, or folder when the scope is known, and global for a manifest-wide collection transform. Use unknown only when the input cannot be represented.
none, tracked, and unsafe describe processed-content reuse, not output reuse. A plugin can safely use none while declaring a global output dependency, or use tracked while a generated output has a narrow content dependency. An incorrect output declaration can preserve a stale file, so use unknown whenever the output scope cannot be stated completely. unknown deliberately trades incremental SSG for a full output render.
processedContentCache on every content-affecting plugin.unsafe when an input cannot be observed. A broad rebuild is acceptable; a stale result is not.See Plugin API for the exact fields and Build System for the build lifecycle.
\n","summary":"Build Dependency Contract Core owns incremental invalidation. A plugin does not compute which content is affected, and it does not keep its own dependency state","tags":[]},{"id":"https://riebeckite.dev/docs/framework/build-dependency","url":"https://riebeckite.dev/docs/framework/build-dependency","title":"build-dependency","content_html":"\nIncremental Buildの無効化はCoreの責務です。PluginはどのContentが影響を受けるかを計算せず、依存stateも自分では持ちません。契約を宣言すると、何を再利用するかはCoreが決めます。
\nPluginが関わる契約は、Content DependencyとOutput Dependencyの二つです。前者はprocessedContentCacheで、Coreがどのsource Contentを処理し直すかを決めます。後者はoutputDependenciesとcontext.output.emitで、Coreがどの出力ファイルを書き直すかを決めます。両者は独立した契約です。
flowchart LR\n Change[\"Contentまたはfileの変更\"] --> Content[\"Content Dependency\"]\n Content --> Reprocess[\"影響するContentの再処理\"]\n Reprocess --> Output[\"Output Dependency\"]\n Output --> Rewrite[\"影響するOutputの再書き込み\"]processedContentCacheは、Pluginの処理済みContentをBuild間でどう再利用してよいかを示す契約です。
dependencyMode | \n 意味 | \n
|---|---|
none | \n 処理結果がsource Content、frontmatter、Pluginのoptions、宣言したversionだけに依存する。 | \n
tracked | \n 他のContentやfileをCore経由で読む。Coreがその読み取りを記録し、利用側だけを再処理する。 | \n
unsafe | \n Git、network、時刻、process stateなど、Coreが観測できない入力に依存する。永続的な再利用は行わない。 | \n
Contentを変化させるPluginが契約を宣言していない場合、そのPluginはunsafeとして扱われます。
versionは契約の名前です。Coreは解決済みのPlugin設定もcache keyに含めます。そのため、options、hooks、versionのいずれかを変えると、cacheされたentryは無効です。
CoreのContent API経由の読み取りが、安定したidentityを持つdependencyになります。
\n| 種類 | \n記録される場面 | \nidentity | \n
|---|---|---|
content | \n readContent、renderContent、renderNoteEmbed | \n Contentのslug | \n
file | \n contentSource.readとreadContentSourceEntryなどのhelper | \n file path | \n
link | \n link先がpermalinkに解決されたとき | \nlink id | \n
contentSource.scan()はentryを列挙するだけでdependencyを作りません。filesystem、network、時計への直接アクセスはCoreから見えないため、それらの入力はunsafeです。
次のBuildでCoreは、cacheされた処理済みContentを取り出したあと、記録したcontent、file、linkのdependencyをすべて読み直し、fingerprintを比べます。一つでも変わっていれば、そのentryを捨てて処理し直します。
\ncacheが省略するのはMarkdownとHTMLの処理だけです。post処理のhooks（onPostParsed、onPostProcessed）とmanifestのhook（onManifestCreated）は、cacheの有無にかかわらず常に実行対象です。manifest段階の処理はそこに置いてください。
Coreは各entryのdependency identityをbuild stateに永続化し、そこから逆引きindexを作ります。dependencyが変わると、依存するentryに印を付け、さらにその依存先へと無効化を伝播させます。Contentが追加または削除された場合も、変わったlink先を参照していたentryは無効です。初回Buildや前回のstateが無いときは、すべてのnoteを処理します。
\nOutput DependencyはContent Dependencyとは別の契約です。種類ごとに、change setの異なる部分に反応します。
\n| 種類 | \n影響を受ける条件 | \n
|---|---|
content { slug } | \n そのContentが変わったとき | \n
tag { tag } | \n そのtagを持つContentが変わったとき | \n
folder { folder } | \n そのfolderのContentが変わったとき | \n
global | \n いずれかのContentが変わったとき | \n
unknown | \n 常に。Coreは全Outputの再生成も要求する。 | \n
宣言する場所は三つです。
\n| 対象 | \n宣言場所 | \n
|---|---|
| Plugin page | \npageTypes[].outputDependencies | \n
| manifest entry HTMLを更新するPlugin | \nrootのoutputDependencies。CoreがすべてのContent Outputに加算する。 | \n
| 生成output | \ncontext.output.emit(..., { dependencies })。未宣言ならunknown。 | \n
対象が特定できる場合はcontent、tag、folderを使ってください。manifest全体に依存する集合変換はglobalです。表現できない入力だけにunknownを使います。
none、tracked、unsafeは処理済みContentの再利用を示す契約であり、Outputの再利用を示すものではありません。たとえばPluginはnoneとglobal output dependencyを安全に組み合わせられます。また、trackedでも生成outputには狭いcontent dependencyを指定できます。誤ったoutput宣言では古いfileが残るため、outputの範囲を完全に表現できない場合はunknownを使ってください。unknownではincremental SSGよりfull output renderを優先します。
processedContentCacheを宣言します。unsafeを使います。広い再処理は許容できますが、古い結果の再利用は許容できません。正確なfieldはPlugin API、Build lifecycleはBuild Systemを参照してください。
\n","summary":"Build Dependency Contract Incremental Buildの無効化はCoreの責務です。PluginはどのContentが影響を受けるかを計算せず、依存stateも自分では持ちません。契約を宣言すると、何を再利用するかはCoreが決めます。 Pluginが関わる契約は、Content Dep","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/build-system","url":"https://riebeckite.dev/en/docs/framework/build-system","title":"build-system.en","content_html":"\nAn explicit build resolves configuration and plugins, reads content, runs content and plugin pipelines, creates the manifest and content graph, emits registered assets and client entries, and records successful incremental state. The HonoX integration then builds the application with the generated entries.
\nBuild state is application-scoped at .riebeckite/build/content-state.json. It is an optimization, not a source of truth. A missing, incompatible, or unsafe state causes an initial/full path; --full requests that path explicitly. State is saved only after a successful build, so a failure retains the prior valid state.
ContentSource metadata may contain mtime, size, ETag, or a hash. Treat mtime as a hint only: timestamp-only comparisons are not sufficient for correctness when metadata can be unreliable. Plugin cache is separate from build state, plugin-scoped, JSON-serializable, regenerable build-time data. Neither may be required at Workers request time.
State tracks each entry's fingerprint together with its dependencies: the notes it links to (whose resolved permalink it may embed) and the assets it references (whose metadata, such as attachment size, it may render). A changed dependency invalidates the dependent entry and, transitively, its dependents. Added or removed entries change which link targets resolve, so entries that reference an affected target are invalidated as well. On the first build, or when no previous state is available, every note is processed. The .riebeckite state directory is build-time state, not content, and is never scanned.
The processed Markdown result for each note is stored in .riebeckite/cache/content/v3. A build without an entry is a cold build. Restoring compatible entries before a later build makes it a warm build: unchanged notes can reuse their processed HTML and frontmatter while the normal build still generates dist/.
An entry key includes its Markdown source, parsed frontmatter, the cache schema, and the processing-pipeline fingerprint. The fingerprint includes content-filter configuration, plugin configuration and order, plugin cacheVersion and processed-content cache contracts, and the Core compatibility version. Cached content also records logical content, file, and link dependencies; changed or missing dependencies are misses. Unsafe plugins bypass this cache. Cache data contains logical slugs and normalized source paths rather than workspace paths, so it can be copied to a different runner or workspace on the same operating system.
This cache is an optimization, never a correctness dependency. Missing entries, incompatible versions, malformed metadata, fingerprint or dependency mismatches, and corrupted JSON are safe misses. Delete .riebeckite/cache to force cold processing; a filesystem access failure still fails the build because it requires attention. The build log reports one Persistent content cache line with hits, misses, and bypasses, plus a concise Content line (total, processed, and reused counts) and the total Build complete duration.
For GitHub Actions, cache .riebeckite/cache and .riebeckite/build/content-state.json, not dist/. The output cache (.riebeckite/ssg-output-cache.json) stays local because its build-time saving does not offset the transfer cost. The generated Cloudflare workflow does this automatically; see GitHub Actions.
Persistent per-content cache reuses Markdown and plugin processing. Output-level incremental SSG separately reuses final routes and generated files. After building the current manifest, Core compares its output descriptors with the previous successful state. HonoX renders only affected content and plugin-page routes, restores unchanged generated output from .riebeckite/ssg-output-cache.json, and removes outputs no longer owned by the site. The build log reports an SSG outputs line with the rendered, reused, and removed counts.
The state and output cache are optimizations. A missing, incompatible, malformed, or incomplete output state, an application/configuration fingerprint change, or an unknown output dependency makes HonoX render every output. Delete .riebeckite/build/content-state.json and .riebeckite/ssg-output-cache.json to force that safe path. dist/ is not a cache: Vite may recreate it, and unchanged site outputs are re-emitted from the output cache. This is a build optimization only; it does not change Wrangler's Cloudflare Workers deployment protocol.
pnpm build # configured project build\npnpm exec riebeckite build # content/application build\npnpm exec riebeckite build --full\npnpm exec riebeckite profile --fullUse check for validation and doctor for health diagnostics; neither substitutes for a build. Use inspect to view existing state, never to manufacture it. See CLI, Inspector, and Content system.
When adding generated output, make its owner and cleanup behavior explicit. Do not silently write during validation or inspection. Cache keys must include every relevant version/input; raise a full-build fallback rather than reusing uncertain output. Keep failures observable and avoid deleting a previous successful state before replacement is known to be valid.
\n","summary":"Build System What a build owns An explicit build resolves configuration and plugins, reads content, runs content and plugin pipelines, creates the manifest and ","tags":[]},{"id":"https://riebeckite.dev/docs/framework/build-system","url":"https://riebeckite.dev/docs/framework/build-system","title":"build-system","content_html":"\nRiebeckite の Build System は、Markdown などのコンテンツと設定を読み込み、最終的な Web サイトを生成する仕組みです。
\n通常の build では、大きく次の処理を行います。
\nRiebeckite は、前回の build 結果を利用して、変更された部分だけを処理する incremental build にも対応しています。
\nbuild を実行すると、最初に Riebeckite が設定と使用するプラグインを読み込みます。
\n次に、Content Source から Markdown などのコンテンツを読み込み、設定されたプラグインによる変換を行います。
\nこのとき、Markdown を HTML に変換するだけでなく、次のような情報も決定します。
\nこれらの情報をもとに、サイト全体のページ情報やリンク関係、必要なアセットなどを生成します。
\n最後に HonoX が、それまでに生成された情報を使って Web サイト全体を build します。
\n毎回すべてのコンテンツを最初から処理すると、サイトが大きくなるほど build に時間がかかります。
\nそこで Riebeckite は、前回の build から何が変更されたかを確認し、必要な部分だけを処理します。
\n前回の build 情報は、次のファイルに保存されます。
\n.riebeckite/build/content-state.jsonこの情報は build を高速化するためのものであり、サイトを正しく生成するために必須のものではありません。
\nたとえば、
\nといった場合は、無理に再利用せず、必要な処理を最初から行います。
\nつまり、高速化のための情報がなくても、同じサイトを正しく生成できることが前提です。
\n前回の build 情報を使わず、すべてを処理したい場合は --full を使用します。
pnpm exec riebeckite build --fullincremental build の結果に問題がありそうな場合の確認や、build 時間を比較したい場合などに利用できます。
\n前回の build 情報は、build が正常に完了した場合だけ更新されます。
\nflowchart TD\n A[\"前回成功した状態\"] --> B[\"Build 開始\"]\n B --> C{\"Build 成功？\"}\n \n C -->|Yes| D[\"新しい状態を保存\"]\n C -->|No| E[\"新しい状態は保存しない\"]\n \n E --> F[\"前回成功した状態を維持\"]新しい build が途中で失敗しても、前回正常に完了した build の情報は残ります。
\n失敗途中の情報で、正常だった状態を上書きすることはありません。
\nRiebeckite は、Content Source が提供するファイル情報を使って、コンテンツが変更されたかを判断します。
\nたとえば、次のような情報を利用できます。
\n利用できる情報は Content Source によって異なります。
\n更新日時だけに頼るのではなく、利用可能な情報を組み合わせて、前回の結果を安全に再利用できるか判断します。
\nファイル自体を編集していなくても、そのファイルが参照しているページなどが変更されると、再生成が必要になることがあります。
\nたとえば a.md が b.md にリンクしているとします。
flowchart LR\n A[\"a.md\"] -->|\"リンク\"| B[\"b.md\"]\n C[\"c.md\"] -->|\"リンク\"| A\n \n B -->|\"URL が変更\"| D[\"a.md を再生成\"]\n D -->|\"影響を確認\"| E[\"c.md も必要なら再生成\"]b.md の URL が変更されると、a.md 自体を編集していなくても、a.md に書かれているリンクを更新する必要があります。
そのため Riebeckite は、「ファイルが変更されたか」だけでなく、「そのファイルが何を参照しているか」も記録します。
\nたとえば、次のような関係を確認します。
\n参照先が変更された場合は、その影響を受けるページも再生成します。
\nさらに、そのページを参照している別のページにも影響がある場合は、必要な範囲まで再生成します。
\nコンテンツの追加や削除は、既存ファイルの編集より広い範囲に影響する場合があります。
\nたとえば、存在しないページへの Wikiリンクがある状態で、新しくそのページが追加されたとします。
\n追加前はリンク先を見つけられませんが、追加後は正しいページへリンクできるようになります。
\nコンテンツの追加や削除によってリンクの解決結果が変わった場合も、影響するページを再生成します。
\n初回 build や、前回の build 情報が存在しない場合は、すべてのコンテンツを処理します。
\nRiebeckite は、Markdown を HTML に変換した結果を次の場所に保存します。
\n.riebeckite/cache/content/v3これにより、変更されていない Markdown を毎回最初から処理する必要がなくなります。
\n初めて build する場合など、利用できるキャッシュがない build を cold build、前回の処理結果を再利用できる build を warm build と呼びます。
\nwarm build では、変更されていないページの HTML や frontmatter を再利用できます。
\nただし、前回の結果を無条件に再利用するわけではありません。
\nRiebeckite は、たとえば次のような変更がないか確認します。
\n変更があった場合や、安全に再利用できるか判断できない場合は、そのページを通常どおり処理し直します。
\nプラグインについても、処理結果を安全に再利用できることが確認できない場合はキャッシュを使用しません。
\nこのキャッシュも build を高速化するためのものであり、サイトの正しさを左右するものではありません。
\n次のような場合は、キャッシュを使わず通常の処理に戻ります。
\nキャッシュを完全に作り直したい場合は、次のディレクトリを削除できます。
\n.riebeckite/cachebuild log の Persistent content cache では、キャッシュがどの程度利用されたか確認できます。
hits: 再利用できた数misses: 再処理した数bypasses: 安全性のためキャッシュを使用しなかった数あわせて、build log には次の概要も表示されます。
\nContent: コンテンツの総数、実際に処理した数、再利用によって処理を省略した数Build complete: Build 全体の所要時間GitHub Actions では、生成されたサイトそのものではなく、次の build 用データをキャッシュします。
\n.riebeckite/cache\n.riebeckite/build/content-state.jsondist/ はキャッシュしません。
また、最終的なページ生成に使用する .riebeckite/ssg-output-cache.json は、ファイルを転送する時間に対して得られる効果が小さいため、ローカルでのみ利用します。
Cloudflare 用の workflow については GitHub Actions を参照してください。
\nMarkdown の処理結果とは別に、Riebeckite は最終的に生成されるページやファイルについても、変更されていないものを再利用できます。
\n前回の build と比較して変更の影響を受けていないページは、再度生成する代わりに、次のファイルに保存された結果を利用します。
\n.riebeckite/ssg-output-cache.jsonたとえば Markdown を 1 ファイルだけ変更した場合、サイト内のすべてのページを生成し直すのではなく、その変更によって影響を受けるページだけを生成できます。
\n一方、以前は存在していたものの、現在はサイトから削除されたページやファイルは出力から削除されます。
\nbuild log の SSG outputs では、この結果を確認できます。
rendered: 今回新しく生成した数reused: 前回の結果を再利用した数removed: サイトから削除された数この仕組みについても、安全に再利用できるか判断できない場合はキャッシュを使用せず、すべてのページを生成します。
\nたとえば次のような場合です。
\n完全に作り直したい場合は、次のファイルを削除できます。
\n.riebeckite/build/content-state.json\n.riebeckite/ssg-output-cache.jsonなお、dist/ はキャッシュではありません。
dist/ は最終的に生成された Web サイトの出力先です。
この最適化は build の方法を高速化するだけであり、Cloudflare Workers への deploy 方法を変更するものではありません。
\nPlugin Cache は、プラグイン自身が計算結果を一時的に保存するための仕組みです。
\nたとえば、build のたびに同じ計算を行う必要がない場合に、その結果を保存して次回の build で再利用できます。
\nPlugin Cache には次の特徴があります。
\nPlugin Cache がなくなっても、サイトを正しく build できる必要があります。
\nまた、Plugin Cache や incremental build の情報は build 時にだけ使用するものであり、公開後の Workers が読み書きするデータとしては使用しません。
\n.riebeckite ディレクトリ.riebeckite には、キャッシュや前回の build 情報など、Riebeckite が build のために使用するデータが保存されます。
これらはユーザーが作成したコンテンツではありません。
\nそのため、Riebeckite が Markdown などのコンテンツを探すとき、.riebeckite ディレクトリは対象外になります。
通常のプロジェクトを build するコマンドは次のとおりです。
\npnpm buildRiebeckite の build は次のコマンドです。
\npnpm exec riebeckite build前回の build 情報を使わずに build するには --full を付けます。
pnpm exec riebeckite build --fullfull build の処理時間を詳しく確認するには、次のコマンドを実行します。
\npnpm exec riebeckite profile --fullcheck、doctor、inspect は、それぞれ build とは異なる役割を持っています。
| コマンド | \n主な役割 | \n
|---|---|
build | \n Web サイトを生成する | \n
build --full | \n 前回の build 情報を使わずに Web サイトを生成する | \n
profile | \n build の処理時間を調べる | \n
check | \n 設定やプラグインの構成を確認する | \n
doctor | \n プロジェクトに問題がないか診断する | \n
inspect | \n 保存されている build 情報などを確認する | \n
check や doctor が成功しても、実際の build が必ず成功することを保証するものではありません。
また、inspect はすでに存在する情報を確認するためのコマンドです。build 情報を新しく作るためのコマンドではありません。
詳しいコマンドについては CLI、build 情報の確認については Inspector、コンテンツの読み込みについては Content system を参照してください。
\nBuild System やプラグインから新しいファイルを生成する場合は、「どの仕組みがそのファイルを管理するのか」を明確にします。
\n特に、次の点に注意してください。
\ncheck や inspect などの確認用コマンドから、意図せずファイルを書き換えない基本原則は、build の速さよりも、生成されるサイトの正しさを優先することです。
\nincremental build や各種キャッシュは build を高速化するための仕組みです。
\nそれらをすべて削除したとしても、同じ正しい Web サイトを生成できることが Riebeckite の Build System の前提です。
\n","summary":"Build System Riebeckite の Build System は、Markdown などのコンテンツと設定を読み込み、最終的な Web サイトを生成する仕組みです。 通常の build では、大きく次の処理を行います。 設定とプラグインを読み込む Markdown などのコンテンツを読み込む プラグイン","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/content-system","url":"https://riebeckite.dev/en/docs/framework/content-system","title":"content-system.en","content_html":"\nContentSource is the boundary for finding and reading source data. It owns scanning, reading, identity, and source metadata such as mtime, size, ETag, or hashes. FileSystemContentSource is the normal local implementation.
ContentManager owns the meaning of that data: parsing, Markdown/HTML pipeline execution, post processing, plugin orchestration, manifest creation, and content-graph construction. It should not grow direct filesystem behavior that bypasses ContentSource.
scan/read source\n -> resolve public locations (default resolver + plugin hooks)\n -> parse post -> process post -> create manifest -> graph\n |\n `--- plugin lifecycle/content hooks ---'Public locations are resolved before any content that needs a URL is processed, so a consumer never has to invent one. Plugin hooks observe or extend defined phases such as configuration resolution, content loaded, parsed/processed posts, manifest creation, and build start/end. Keep source I/O, semantic interpretation, and rendering distinct so a remote source can replace the filesystem source without changing Core policy.
\nA content entry separates three notions of identity:
\ncontentIndex, the manifest bySlug map, the content graph, and application-level selection keys such as /explore?note=<slug>.ContentManifestEntry.contentId and indexed by ContentManifest.byContentId. It is independent of both the slug and all public locations.They are distinct. A consumer that needs a public URL reads ContentManifestEntry.permalink (also available as entry.publicLocation); it must not build a URL from a slug or filesystem path. Turning a slug into a URL is the Core default resolver's job alone.
Resolution is a single, stateless pipeline:
\nresolveDefaultContentLocation(content), where content is a ContentLocationInput (slug, path, markdown). The default policy is index -> / and every other entry -> /{slug}. This is the Core default public-location policy, not a compatibility fallback.resolveContentLocations hook, which receives the ContentLocationInput list and returns ContentPublicLocation values. Plugin-specific URL strategies stay inside the plugin.ContentManager.getContentLocations() returns the resolved ReadonlyMap<string, ContentPublicLocation>. A ContentPublicLocation carries the canonical permalink, optional redirects, and optional opaque metadata that Core does not interpret.The manifest stores the resolved result: ContentManifestEntry.permalink and .publicLocation, plus the byPermalink index and the redirects map. The content graph and readOnlyContentGraph(source, locations) consume those resolved entries rather than deriving URLs. If a public location is not resolved for an entry, Core raises an explicit error instead of falling back to a slug-derived URL.
\n Set the standard id frontmatter field when content needs an identity that\n survives a rename, permalink change, alias, or redirect. IDs are optional, so\n existing content without id has no generated substitute and keeps its current\n behavior. Core never uses a slug, path, permalink, alias, or redirect as a\n stable ID.\n
---\nid: note-7f4e9b\n---\n Values must be non-empty, trimmed strings, and each explicit ID must be unique\n within a manifest; invalid or duplicate IDs fail the manifest build rather than\n silently selecting an identity.\n
\nThe manifest is the generated content representation used by the application. The content graph represents relationships and can be extended through the plugin graph contract. Reading a runtime manifest is not an explicit build. Incremental build state belongs only to the explicit build path and is never a mutable Worker runtime dependency.
\nCore exposes a portable query layer over resolved manifest entries:
\nqueryContentEntries(entries, spec) filters by tags, folder, frontmatter, and date range, applies one or more sort keys, and slices the result with limit/offset.queryContentPage(entries, spec) applies the same selection and returns the page slice together with page metadata (page, pageCount, hasPrevious, hasNext); resolveContentQueryPagination(total, spec) computes that metadata alone.groupContentEntries(entries, groupBy, options) runs the same selection and groups the result by tags, folder, date granularity (year/month/day), or a frontmatter field.Both functions operate on ContentManifestEntry values, so links use the resolved permalink; a query never builds a public content URL from a slug. Applications and plugins compose these functions to build listing pages and taxonomy views, while Core keeps ownership of manifest and graph construction rather than routing.
buildContentCollections(entries, definitions) turns the same query selection into listing collections. A definition declares a kind, a groupBy (tags, folder, date, or a frontmatter field), a site-local basePath, optional filter/sort/order values, and optional resolveTitle/resolvePath builders. Every generated ContentCollection carries the group value, the resolved path, a title, and its entries in query order.
This is the shared mechanism behind taxonomy, folder, and archive listings. A tag definition groups by tags under /tags; an archive definition groups by date under /archive; both are produced by the same call. Routing stays in the application, while the collection contract and the query engine stay in Core. Listing entries still link through ContentManifestEntry.permalink and never construct a URL from a slug.
A definition may set pageSize to split a collection across pages. Each page is emitted as its own ContentCollection whose path is the collection path plus /page/<n> for later pages, and its page metadata carries current, count, size, total, previousPath, and nextPath for building navigation.
ContentPublicLocation.See Configuration, Build system, and Plugin system.
\n","summary":"Content System Two explicit responsibilities ContentSource is the boundary for finding and reading source data. It owns scanning, reading, identity, and source ","tags":[]},{"id":"https://riebeckite.dev/docs/framework/content-system","url":"https://riebeckite.dev/docs/framework/content-system","title":"content-system","content_html":"\nContent System は、Markdown や画像などのファイルを、Riebeckite がサイトとして扱えるコンテンツへ変換する仕組みです。
\n単に Markdown を HTML に変換するだけではありません。
\nRiebeckite が、
\nを解決し、Site 全体から同じ情報を利用できる状態にします。
\nContent System の大まかな流れは次のとおりです。
\nflowchart TD\n Files[\"Markdown / Assets\"]\n Source[\"ContentSource<br/>コンテンツを読み込む\"]\n Manager[\"ContentManager<br/>コンテンツを解決・処理する\"]\n Plugin[\"Plugin Hooks\"]\n Manifest[\"Manifest\"]\n Graph[\"Content Graph\"]\n Location[\"Public Location\"]\n Site[\"Page Generation / Runtime\"]\n \n Files --> Source\n Source --> Manager\n \n Manager <--> Plugin\n \n Manager --> Manifest\n Manager --> Graph\n Manager --> Location\n \n Manifest --> Site\n Graph --> Site\n Location --> Site中心になるのが ContentSource と ContentManager です。
簡単に言えば、
\nContentSource\n = どこからコンテンツを読むか\n \nContentManager\n = 読み込んだコンテンツをどう扱うかという役割分担です。
\nContentSource は、Markdown やアセットをどこから、どう読み込むかを抽象化した API です。
通常は、
\ncontent/のような content.directory で指定されたディレクトリから読み込みます。
しかし Content System 自体は、コンテンツが必ず Site repository 内に存在するとは考えません。
\nたとえば、
\nSite Repository\n└─ content/\n \nExternal Repository\n└─ notes/\n \nObsidian Vault\n└─ notes/のどこから取得した場合でも、最終的には ContentSource という同じ interface を通して ContentManager に渡します。
flowchart LR\n Local[\"Site Repository\"]\n External[\"External Repository\"]\n Vault[\"Obsidian Vault\"]\n \n Local --> Source[\"ContentSource\"]\n External --> Source\n Vault --> Source\n \n Source --> Manager[\"ContentManager\"]これにより、コンテンツの保存場所が変わっても、それ以降の処理を同じ仕組みで扱えます。
\nContent System を理解するときに重要なのが、次の3つを区別することです。
\n| 種類 | \n意味 | \n
|---|---|
| ファイルシステム上のパス | \n実際にファイルが保存されている場所 | \n
| 論理パス | \ncontent root から見たコンテンツの識別子 | \n
| 公開先 | \nWeb Site 上の URL | \n
たとえば、
\nC:\\projects\\garden\\content\\posts\\hello.mdというファイルがあったとしても、Riebeckite 内部では、
\nposts/hello.mdという論理パスとして扱えます。
\nさらに、実際の公開先は、
\n/blog/hello/かもしれません。
\nflowchart LR\n FS[\"Filesystem Path<br/>C:/.../content/posts/hello.md\"]\n Logical[\"Logical Path<br/>posts/hello.md\"]\n Public[\"Public Location<br/>/blog/hello/\"]\n \n FS --> Logical\n Logical --> Publicこの3つを分離することで、content repository を別の repository に移しても、Site 側の URL やコンテンツ処理を同じ規則で扱えます。
\nContentManager は ContentSource から受け取ったコンテンツを管理し、Site で利用できる状態へ変換します。
主な役割は次のとおりです。
\nつまり ContentManager は、Content System の中心となる orchestrator です。
\nPlugin は ContentManager の lifecycle に hook できます。
\n代表的な hook には、
\nonContentLoaded\nonPostParsed\nonPostProcessed\nonManifestCreatedなどがあります。
\n概念的には次のような流れになります。
\nflowchart TD\n Load[\"Content Loaded\"]\n H1[\"onContentLoaded\"]\n Parse[\"Markdown Parse\"]\n H2[\"onPostParsed\"]\n Process[\"Content Processing\"]\n H3[\"onPostProcessed\"]\n Manifest[\"Manifest Created\"]\n H4[\"onManifestCreated\"]\n \n Load --> H1\n H1 --> Parse\n Parse --> H2\n H2 --> Process\n Process --> H3\n H3 --> Manifest\n Manifest --> H4Plugin はこの lifecycle を利用してコンテンツを拡張します。
\nこの3つは似ていますが、役割が異なります。
\n| 名前 | \n何を表す？ | \n例 | \n
|---|---|---|
slug | \n コンテンツの短い名前 | \nhello-world | \n
permalink | \n Site 上の公開 URL | \n/blog/hello-world/ | \n
| content ID | \nコンテンツそのものを安定して識別する ID | \narticle-01 | \n
特に、slug と公開 URL は同じものではありません。
\nたとえば、
\nslug\n hello-world\n \npermalink\n /blog/hello-world/\n \ncontent ID\n 019abc...のように、それぞれ別の目的を持ちます。
\n標準では resolveDefaultContentLocation が公開先を解決します。
基本的には、
\nindex\n ↓\n/\n \nその他\n ↓\n/{slug}として扱います。
\nただし、これはあくまで default resolver です。
\nPlugin は、
\nresolveContentLocationshook を使って公開先を追加・変更できます。
\nContentPublicLocation は、コンテンツが Site 上のどこで公開されるか を表します。
通常は1つの記事に1つの canonical な公開先があります。
\nArticle\n ↓\n/blog/article/しかし Plugin によって、別名 URL や redirect が追加される場合があります。
\nflowchart LR\n Article[\"Article\"]\n \n Article --> Canonical[\"Canonical<br/>/blog/article/\"]\n Article --> Alias[\"Alias<br/>/article/\"]\n Alias -->|\"redirect\"| Canonical公開先はページ生成だけで使う情報ではありません。
\nたとえば、
\nなども公開先を参照します。
\nそのため Riebeckite では URL を単なる文字列として各機能が独自に計算するのではなく、ContentPublicLocation として明示的に管理します。
Manifest は、Build 時に確定したコンテンツの一覧です。
\n各 entry には、たとえば次の情報が含まれます。
\nflowchart LR\n Manager[\"ContentManager\"]\n Manifest[\"Manifest\"]\n \n Manager --> Manifest\n \n Manifest --> Page[\"Page Generation\"]\n Manifest --> Runtime[\"Runtime Queries\"]\n Manifest --> Build[\"Incremental Build\"]\n Manifest --> Inspect[\"inspect content\"]Manifest は、Content System が解決した結果を他の仕組みへ渡す重要な境界です。
\n各 consumer が Markdown を読み直して同じ情報を再計算するのではなく、解決済みの Manifest を利用します。
\nContent Graph は、コンテンツ同士の関係を表します。
\nたとえば、
\n[[Article B]]という WikiLink があれば、
\ngraph LR\n A[\"Article A\"] --> B[\"Article B\"]という関係が成り立ちます。
\nこの情報から backlink も扱えます。
\ngraph LR\n A[\"Article A\"] --> B[\"Article B\"]\n C[\"Article C\"] --> B\n \n B -. \"backlinks\" .-> A\n B -. \"backlinks\" .-> CContent Graph は単なるグラフ表示用のデータではありません。
\nたとえば、
\nなどの基盤として利用できます。
\nPlugin は、
\nextendContentGraphを使ってグラフへ情報を追加できます。
\nBuild 後のコンテンツを検索・整理するために、Query API が用意されています。
\n代表的な API は次のとおりです。
\nqueryContentEntries\nqueryContentPage\ngroupContentEntriesこれらはファイルを検索する API ではありません。
\nflowchart LR\n Files[\"Markdown Files\"]\n Build[\"Build / ContentManager\"]\n Index[\"Resolved Content Index\"]\n Query[\"Content Query\"]\n Result[\"Result\"]\n \n Files --> Build\n Build --> Index\n Query --> Index\n Index --> ResultQuery は、Build 時にすでに解決された index に対して実行します。
\nRuntime や Plugin が Markdown を直接読み直して独自に状態を再構築することは避けます。
\nbuildContentCollections は、複数のコンテンツを一覧として扱うための仕組みです。
たとえば、
\nすべての記事\n ↓\n日付順に並べる\n ↓\nタグごとに分類する\n ↓\nページ単位に分割するといった処理に利用できます。
\npageSize を指定すると pagination も扱えます。
flowchart LR\n Entries[\"Published Entries\"]\n Sort[\"Sort\"]\n Group[\"Group\"]\n Paginate[\"Paginate\"]\n Pages[\"Collection Pages\"]\n \n Entries --> Sort\n Sort --> Group\n Group --> Paginate\n Paginate --> PagesPlugin や Site Application は、この仕組みを使って記事一覧、タグ一覧などを作成できます。
\n画像や添付ファイルは Markdown 本文とは別の entry として扱います。
\nたとえば、
\ncontent/\n├─ article.md\n└─ images/\n └─ example.pngがあった場合、Riebeckite はアセットの論理パスを保ちながら、Site 上で利用できる URL へ対応付けます。
\nflowchart LR\n Asset[\"Content Asset<br/>images/example.png\"]\n Resolver[\"Asset Resolution\"]\n Public[\"Public Asset URL\"]\n \n Asset --> Resolver\n Resolver --> Public実際の URL 形式は Plugin や設定によって変わる場合があります。
\ncontent root の外にある任意のファイルを公開 URL に変換しないことが重要です。
\nContent System の公開境界を通して、安全に公開対象を決定します。
\nSite と Content を別 repository にしても、Content System の基本的な流れは変わりません。
\nflowchart LR\n ContentRepo[\"Content Repository\"]\n Checkout[\"Checkout / Content Source\"]\n SiteRepo[\"Site Repository\"]\n Build[\"Riebeckite Build\"]\n Site[\"Generated Site\"]\n \n ContentRepo --> Checkout\n Checkout --> Build\n SiteRepo --> Build\n Build --> SiteContent Repository はコンテンツを提供します。
\n最終的に、
\nを決定するのは Site Repository 側の Build です。
\nこのため、Content Repository が分離されていても ContentManager や Plugin が filesystem の配置を特別扱いする必要はありません。
\nContent System を変更するときは、次の原則を維持してください。
\n| 原則 | \n理由 | \n
|---|---|
content.directory は appRoot 基準で解決する | \n Site ごとに安定した基準を持つため | \n
| Plugin は filesystem path に依存しない | \nContent Source を交換可能にするため | \n
公開判定は publishStrategy と frontmatter に従う | \n 公開境界を一元化するため | \n
公開先は ContentPublicLocation として登録する | \n URL を各機能が独自計算しないため | \n
| Runtime は Build 済み index を利用する | \nRuntime から source filesystem を分離するため | \n
| Site Build が最終的な公開状態を決める | \nContent Repository と Site の責務を分離するため | \n
全体として、
\nflowchart LR\n Source[\"Source<br/>どこから読む？\"]\n Content[\"ContentManager<br/>何として扱う？\"]\n Public[\"Public Location<br/>どこで公開する？\"]\n Index[\"Manifest / Graph<br/>何が解決された？\"]\n Consumer[\"Site / Plugin<br/>どう利用する？\"]\n \n Source --> Content\n Content --> Public\n Public --> Index\n Index --> Consumerという境界を崩さないことが重要です。
\nSource は読み込み方、ContentManager はコンテンツの解決、Public Location は公開先、Manifest / Graph は解決結果を表します。
\n各機能が filesystem や Markdown を独自に読み直すのではなく、この Content System を通して同じ解決結果を共有することが、Riebeckite の Content Architecture の基本です。
\nThis page is for people developing Riebeckite itself: core, CLI, HonoX integration, official plugins, official themes, templates, or the reference app. It is intentionally separate from Getting Started. Users who only want to publish a site should use create-riebeckite instead of cloning this monorepo.
git clone https://github.com/rerurate/riebeckite.git\ncd riebeckite\npnpm install\npnpm buildpnpm dev\npnpm build\npnpm check\npnpm check:docs\npnpm check:scaffold\npnpm testUse targeted commands when possible:
\npnpm check:docs validates Markdown links and docs structure.pnpm check:scaffold validates generated scaffold output.pnpm typecheck checks packages.pnpm --filter <package> test runs a package test when available.| Path | \nPurpose | \n
|---|---|
packages/core | \n public config, content, pipeline, plugin, theme, diagnostics, observability APIs | \n
packages/cli | \n riebeckite command | \n
packages/integrations/honox | \n HonoX integration and scaffold generator | \n
packages/create-riebeckite | \n public site scaffolding entrypoint | \n
packages/plugins/* | \n official plugins | \n
packages/themes/* | \n official themes | \n
apps/web | \n official documentation app and framework-development reference application | \n
docs/ | \n documentation source read by the official docs app | \n
templates/analytics-cloudflare | \n Analytics Worker deployment templates | \n
src/** imports.See Architecture, Testing, CLI, and HonoX Integration.
\n","summary":"Framework Development This page is for people developing Riebeckite itself: core, CLI, HonoX integration, official plugins, official themes, templates, or the r","tags":[]},{"id":"https://riebeckite.dev/docs/framework/development","url":"https://riebeckite.dev/docs/framework/development","title":"development","content_html":"\nこのページは、Riebeckite 本体を開発する人向けのガイドです。
\n次のような変更を行う場合に、この monorepo を使用します。
\n単に Riebeckite を使って自分の Site を作りたい場合は、この repository を clone する必要はありません。
\nGetting Started から Site を作成してください。
\nflowchart TD\n Q{\"何をしたい？\"}\n \n Q -->|\"RiebeckiteでSiteを作りたい\"| User[\"Getting Started\"]\n Q -->|\"Riebeckite本体を変更したい\"| Dev[\"Framework Development\"]\n \n User --> Site[\"自分のSite Repository\"]\n Dev --> Repo[\"Riebeckite Monorepo\"]Riebeckite 本体を開発する場合は、repository を clone して依存関係をインストールします。
\ngit clone https://github.com/rerurate/riebeckite.git\ncd riebeckite\npnpm install\npnpm buildこれで workspace 内の package を開発できる状態になります。
\npnpm devapps/web の参照アプリを使って、Riebeckite の変更を実際の Site として確認できます。
apps/web は単なるデモではなく、Framework 開発時に Core、Plugin、Theme、Integration が正しく組み合わさることを確認するための参照アプリでもあります。
Riebeckite は pnpm workspace を使った monorepo です。
\n大きく次のように分かれています。
\nflowchart TD\n Repo[\"riebeckite/\"]\n \n Repo --> Packages[\"packages/\"]\n Repo --> Apps[\"apps/\"]\n Repo --> Docs[\"docs/\"]\n Repo --> Templates[\"templates/\"]\n \n Packages --> Core[\"core<br/>共通基盤\"]\n Packages --> CLI[\"cli<br/>CLI\"]\n Packages --> Integration[\"integrations/honox<br/>HonoX接続\"]\n Packages --> Create[\"create-riebeckite<br/>Site生成\"]\n Packages --> Plugins[\"plugins/*<br/>公式Plugin\"]\n Packages --> Themes[\"themes/*<br/>公式Theme\"]\n \n Apps --> Web[\"web<br/>Docs / Reference App\"]\n Docs --> DocSource[\"Documentation Source\"]\n Templates --> Analytics[\"analytics-cloudflare<br/>Analytics Deployment Template\"]| Path | \n役割 | \n
|---|---|
packages/core | \n config、content、pipeline、Plugin、Theme、Diagnostics、Observability などの共通基盤 | \n
packages/cli | \n riebeckite CLI | \n
packages/integrations/honox | \n HonoX / Vite Integration と scaffold generator | \n
packages/create-riebeckite | \n Site 作成用の公開 entrypoint | \n
packages/plugins/* | \n 公式 Plugin | \n
packages/themes/* | \n 公式 Theme | \n
apps/web | \n 公式ドキュメント Site兼、Framework 開発用の参照アプリ | \n
docs/ | \n 公式ドキュメントの source | \n
templates/analytics-cloudflare | \n Analytics Worker の Deployment template | \n
各 package の詳しい責務については Architecture を参照してください。
\nFramework 開発でよく使用するコマンドは次のとおりです。
\n| コマンド | \n用途 | \n
|---|---|
pnpm dev | \n 開発用 Site を起動する | \n
pnpm build | \n workspace を build する | \n
pnpm check | \n repository 全体を検査する | \n
pnpm test | \n test を実行する | \n
pnpm typecheck | \n TypeScript の型を検査する | \n
pnpm check:docs | \n Documentation を検査する | \n
pnpm check:scaffold | \n 生成される Site を検査する | \n
pnpm check:docsMarkdown link や Documentation の構造を検査します。
\nドキュメントを追加・移動・削除した場合は実行してください。
\npnpm check:scaffold生成される Riebeckite Site が正しい構成になっているかを検査します。
\nたとえば、
\npackage.jsonなどを変更した場合に重要です。
\npnpm typecheckTypeScript の型エラーを確認します。
\n変更した package だけを確認したい場合は --filter を使用できます。
pnpm --filter <package> testたとえば特定の Plugin だけを変更した場合、最初から repository 全体の test を実行するのではなく、対象 package の test から確認できます。
\n変更内容によって必要な検証は異なりますが、基本的には 小さい範囲から確認して、最後に広い範囲を確認する 形を推奨します。
\nflowchart TD\n Change[\"コードを変更\"]\n Focus[\"対象PackageのTest / Typecheck\"]\n Related[\"関連するIntegration / Appを確認\"]\n Check[\"pnpm check\"]\n Build[\"pnpm build\"]\n \n Change --> Focus\n Focus --> Related\n Related --> Check\n Check --> Buildたとえば Plugin を変更した場合は、まずその Plugin の test を実行します。
\npnpm --filter <plugin-package> test問題がなければ、必要に応じて型検査や参照アプリを確認し、最後に repository 全体の検証を行います。
\n変更のたびに最初から最も重い command を実行する必要はありません。
\n機能を追加するときは、まず責務に合った package を選びます。
\nflowchart TD\n Q{\"何を変更する？\"}\n \n Q -->|\"共通のContent / Contract\"| Core[\"packages/core\"]\n Q -->|\"CLI Command\"| CLI[\"packages/cli\"]\n Q -->|\"再利用可能な機能\"| Plugin[\"packages/plugins/*\"]\n Q -->|\"HonoX / Viteとの接続\"| Integration[\"packages/integrations/honox\"]\n Q -->|\"見た目 / CSS\"| Theme[\"packages/themes/*\"]\n Q -->|\"Route / Island / Site UI\"| App[\"apps/web\"]\n Q -->|\"Site生成\"| Scaffold[\"create-riebeckite / scaffold\"]判断に迷う場合は、Architecture の責務分離を基準にしてください。
\nFramework を変更するときは package 間の依存方向を維持してください。
\n大まかな依存関係は次のようになります。
\nflowchart BT\n App[\"Application\"]\n Integration[\"Integration\"]\n Plugin[\"Plugin\"]\n Theme[\"Theme\"]\n CLI[\"CLI\"]\n Core[\"Core\"]\n \n App --> Integration\n Integration --> Core\n Plugin --> Core\n Theme --> Core\n CLI --> Core\n CLI --> Integration特に Core から外側への逆依存を作らないことが重要です。
\nたとえば Core から、
\napps/web\npackages/plugins/*\nHonoX\nViteなどの具体的な実装へ依存させてはいけません。
\nFramework に依存しない contract は Core に置き、その contract を Integration や Plugin が利用します。
\n外部 Plugin / Theme と同じ条件で利用できる API は、公開 export から参照してください。
\nたとえば、
\nimport { ... } from \"@riebeckite/core\";のような公開 entrypoint を使用します。
\n次のように package 内部へ直接依存することは避けてください。
\nimport { ... } from \"@riebeckite/core/src/...\";src/** は内部実装であり、安定した Public API ではありません。
公式 Plugin や Theme も可能な限り Public API の consumer として実装することで、外部 package から実際に利用できる contract になっていることを確認できます。
\nScaffold は Riebeckite monorepo 内でしか動かない構成にしてはいけません。
\n生成された Site は、
\ncreate-riebeckite\n ↓\nGenerated Site\n ↓\nnpm packages\n ↓\nbuildという形で、monorepo の内部 source に依存せず動作する必要があります。
\nそのため scaffold を変更した場合は、workspace 内で動くだけではなく、外部 Site として成立することも確認してください。
\ncheck:scaffold や external-site E2E は、この境界を検証するためにあります。
一般ユーザー向け Documentation では、Riebeckite monorepo の clone や workspace setup を前提にしません。
\nflowchart LR\n User[\"Site User\"]\n Getting[\"Getting Started\"]\n Site[\"Generated Site\"]\n \n Dev[\"Framework Developer\"]\n Framework[\"Framework Development\"]\n Repo[\"Riebeckite Monorepo\"]\n \n User --> Getting --> Site\n Dev --> Framework --> RepoSite を作るユーザーと Framework を開発するユーザーでは、必要な環境が異なるためです。
\nmonorepo 固有の command、内部 package 構成、Framework の build 方法などは、この Framework Development セクションで扱います。
\nFramework の変更では、特に次の点を維持してください。
\nsrc/** を import しなくても実装できる Public API を維持するFramework 全体の責務については Architecture、テスト方針については Testing、CLI については CLI、HonoX との接続については HonoX Integration を参照してください。
\n","summary":"Framework Development このページは、 Riebeckite 本体を開発する人向け のガイドです。 次のような変更を行う場合に、この monorepo を使用します。 Core の機能を追加・変更する CLI を変更する HonoX Integration を変更する 公式 Plugin / The","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/diagnostics","url":"https://riebeckite.dev/en/docs/framework/diagnostics","title":"diagnostics.en","content_html":"\nDiagnostics are structured findings emitted by Core, plugins, and tooling. They make invalid configuration, content issues, capability problems, and environmental health visible without turning every issue into an unstructured console string.
\nPlugins can provide diagnostics through addDiagnostics; Core and integrations combine them for commands such as check and doctor. A plugin should name the actionable condition, identify the relevant content/configuration when available, and make severity proportionate to whether output can remain correct.
Use check for configuration/plugin validity and doctor for broader health. Doctor checks independent areas where possible, so one broken optional area should not conceal another finding. A failing doctor result exits unsuccessfully.
The doctor build-state check verifies that the incremental state is readable and that its stored fingerprints still match the current content source. When entries were added, changed, or removed since the last build, it reports a warning with counts and samples; the next build refreshes the state.
\nStable content IDs come from the optional source-authored id frontmatter field and are the identity key for per-content consumers such as the analytics plugin's page-view tracking. The diagnostics plugin reports two content-level invariants around them:
| Code | \nDefault severity | \nCondition | \n
|---|---|---|
duplicate-content-id | \n error | \n multiple published notes share a stable content ID, which would silently merge per-content metrics | \n
invalid-content-id | \n error | \n id frontmatter violates the stable content ID contract, which breaks the build | \n
These checks are generic content diagnostics; the diagnostics plugin does not hardcode an analytics-specific requirement into its check abstraction.
\nThe diagnostics plugin also reports manifest-level reference integrity for the published site. It checks resolved public entries and plugin-provided public routes rather than creating a parallel filesystem scanner. This covers missing internal links, unresolved WikiLinks, missing local assets, duplicate final public locations, and redirect problems (content-integrity:*). Page-local HTML quality remains the responsibility of @riebeckite/plugin-quality.
Generated pages and generated assets should be registered through Page Types, generated outputs, or plugin assets. Registered paths are treated as valid public targets and should not be reported as broken links.
\nUse Inspector to inspect facts and Observability for logs and traces.
\n","summary":"Diagnostics Diagnostics are structured findings emitted by Core, plugins, and tooling. They make invalid configuration, content issues, capability problems, and","tags":[]},{"id":"https://riebeckite.dev/docs/framework/diagnostics","url":"https://riebeckite.dev/docs/framework/diagnostics","title":"diagnostics","content_html":"\nDiagnostics は、Riebeckite の設定やコンテンツ、プラグイン、実行環境に問題がないかを検査し、開発者に報告するための仕組みです。
\n単にエラーメッセージを console.log へ出すのではなく、
といった情報を、Riebeckite が扱える共通形式の診断情報（diagnostic）として表現します。
\nこれにより、Core や各プラグインが見つけた問題を check や doctor からまとめて確認できます。
プラグインは addDiagnostics を使って独自の診断を追加できます。
追加された診断は Core や integration によって集約され、主に check や doctor から利用されます。
診断を追加するときは、可能な限り次の情報を明確にしてください。
\nたとえば「設定が不正です」とだけ報告するのではなく、「どの設定が不正で、どのように変更すればよいか」まで分かる診断を推奨します。
\ncheck と doctorcheck と doctor は役割が少し異なります。
check は主に設定やプラグインの構成が正しいかを検査します。
doctor はそれに加えて、Riebeckite が正常に動作できる状態かをより広く検査します。
Doctor では、1つの検査に失敗しても、可能な限り他の独立した検査を続行します。そのため、複数の問題がある場合でも一度の実行でまとめて確認できます。
\n問題が見つかった場合、コマンドは non-zero exit code で終了します。
\nDoctor は incremental build で使用する build state も検査します。
\n主に次の状態を確認します。
\n前回の build 以降にコンテンツが追加・変更・削除されている場合は、変更件数と一部のサンプルを warning として報告します。
\nこれは state の破損を意味するものではありません。次回の build が完了すると、現在のコンテンツに合わせて state が更新されます。
\nRiebeckite では、コンテンツを継続的に識別するための「安定コンテンツ ID」を設定できます。
\n通常はフロントマターの id を使用します。
---\nid: my-article\n---この ID は、たとえば analytics プラグインがページごとの閲覧数を記録するときなど、URLとは別にコンテンツそのものを識別したい場合に利用されます。
\nDiagnostics プラグインは、コンテンツ ID について次の問題を検査します。
\n| コード | \n重要度 | \n意味 | \n
|---|---|---|
duplicate-content-id | \n error | \n複数の公開コンテンツが同じ ID を使用している | \n
invalid-content-id | \n error | \nid がコンテンツ ID のルールを満たしていない | \n
たとえば、2つの記事が同じ ID を持っていると、analytics などで別の記事のデータが同じコンテンツとして扱われる可能性があります。
\nこれらは analytics 専用の検査ではありません。コンテンツ ID を利用するすべての機能に共通する整合性チェックとして Diagnostics が担当します。
\nDiagnostics プラグインは、公開サイト内のリンクや参照が正しく解決できるかも検査します。
\nたとえば、次のような問題を検出します。
\nこれらは content-integrity:* の診断として報告されます。
整合性検査では、Riebeckite がすでに解決した公開コンテンツや公開パスの情報を使用します。
\nそのため、Diagnostics のためだけに Markdown をもう一度解析したり、コンテンツを最初から読み直したりすることはありません。
\nまた、permalink、alias、rename、多言語化、公開・除外設定などによって最終的な公開先が変わっている場合も、Riebeckite が解決した結果を基準に検査します。
\nDiagnostics が担当するのは、主にサイト全体の参照や構成の整合性です。
\n一方で、
\nalt があるかといった個々のページの HTML 品質は @riebeckite/plugin-quality が担当します。
プラグインが独自のページ、生成ファイル、アセットなどを公開する場合は、Riebeckite が提供する対応する仕組みを使って登録してください。
\n正しく登録された公開先は Diagnostics からも認識されます。
\nそのため、たとえばプラグインが /explore というページを正式に公開していれば、
/exploreへのリンクが「存在しないページ」として誤って報告されることはありません。
\nDiagnostics を追加するときは、次の原則に従ってください。
\nDiagnostics は問題を発見して説明する仕組みです。問題を自動的に修正したり、ビルド状態を変更したりする仕組みではありません。
\n現在の状態そのものを確認したい場合は Inspector、ログやトレースを確認したい場合は Observability を参照してください。
\n","summary":"Diagnostics Diagnostics は、Riebeckite の設定やコンテンツ、プラグイン、実行環境に問題がないかを検査し、開発者に報告するための仕組みです。 単にエラーメッセージを console.log へ出すのではなく、 何が問題なのか どこで問題が起きているのか どの程度重要なのか どう直せばよい","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/honox-integration","url":"https://riebeckite.dev/en/docs/framework/honox-integration","title":"honox-integration.en","content_html":"\n@riebeckite/honox connects portable Core behavior to HonoX and Vite. It owns application-root/config resolution, Vite development and build integration, SSG extension mapping, generated plugin/theme style entries, and the HonoX application build workflow.
\n Register the integration with riebeckiteVite() from vite.config.ts. It is\n the higher-level helper for a normal site: it appends the Riebeckite plugins,\n applies the SSG entry and extension-map defaults, and contributes the SSR\n externals the runtime needs, so the site does not restate Vite/HonoX internals.\n Combine it with the site's own plugins (the HonoX plugin, a deployment build\n plugin, Tailwind, and so on):\n
import { riebeckiteVite } from \"@riebeckite/honox\";\nimport { defineConfig } from \"vite\";\n \nexport default defineConfig({\n plugins: [honox({ ... }), ...riebeckiteVite(), build()],\n});\n riebeckiteVite accepts the same optional configRoot, appRoot, configFile,\n and monorepo-only workspaceRoot as the lower-level plugin. appRoot defaults\n to the Vite root, and configRoot defaults to appRoot. A config path is\n imported relative to configRoot; content.directory is resolved relative to\n appRoot. resolveHonoxApplication returns these roots together with the\n resolved config, so CLI and Vite use the same model. workspaceRoot is only for\n source-package aliases during monorepo development; installed npm consumers use\n their own node_modules without it. The integration creates generated import\n entries below app/.riebeckite/, and exposes the required client module as a\n virtual module rather than writing it into that directory. Generated files are\n integration output: do not edit them as application source.\n
\n A generated site imports framework-owned bootstrap modules instead of keeping\n resolved config and content-manager code in the application: the resolved\n config is virtual:riebeckite/config, and the configured content runtime is\n virtual:riebeckite/content. This is why app/config.ts, app/content.ts, and\n app/constants/paths.ts are not generated. The SSG entry app/server.ts\n re-exports both, and riebeckiteSsg finds the manifest through them.\n
\n A script that runs outside Vite (for example a Node script started with tsx)\n can resolve the same config with resolveHonoxConfig from\n @riebeckite/honox/runtime.\n
\n The lower-level pieces remain exported for callers that need full control:\n riebeckite (the Vite plugin), riebeckiteSsg (static generation),\n riebeckiteSsgExtensionMap, and createRiebeckiteSsg (the SSG wrapper that\n fills in Riebeckite's defaults). riebeckiteSsg starts its internal Vite server\n with the resolved application root and define values, so invoking\n riebeckite build from a subdirectory yields the same output as invoking it\n from the application root. defaultSsgEntry is the root-relative\n ./app/server.ts entry, and defaultSsrExternals is the SSR externals list\n both helpers use. The SSG entry must re-export the resolved config and\n content (export { config, content }): that is how riebeckiteSsg finds the\n manifest to emit plugin-generated outputs and to run the per-page HTML\n inspections. Other exports are loadRiebeckiteConfig,\n resolveHonoxApplication, resolveHonoxApplicationRoot, buildHonoxApplication,\n and startHonoxDevServer.\n
\n Catch-all routes need two small helpers so runtime routing and static\n generation agree. contentRouteSsgParams(routePath, params) is a drop-in\n replacement for ssgParams from hono/ssg: it emits params only for the\n route's own enumeration request, so a shallow catch-all such as /:slug{.+}\n does not capture the enumeration of a deeper sibling like /tags/:slug{.+}.\n ssgEnumerableHandler(handler) keeps a route handler visible to SSG\n enumeration while it still calls next() to defer to those siblings; Hono\n otherwise skips middleware-shaped handlers.\n
\n When plugins provide Page Types, use resolveRiebeckiteRoute(content, path)\n instead of resolveContentRoute(manifest, path) and merge\n pluginPageSsgParams(content) with the content parameters. The resolver first\n returns a plugin page, then falls through to content and redirects. Its page\n body is intentionally a string: render it inside the site's existing document\n frame and pass page.headTags to that frame. The scaffolded catch-all route\n wraps this in resolveRiebeckiteContentRequest(c, content), which resolves\n content, plugin pages, redirects, and not-found and sets the htmlLanguage and\n headTags context, so the site only composes the returned result. The root /\n is resolved by resolveRiebeckiteHomeRequest(c, content), which shares the same\n mechanics. Plugin packages never need to add HonoX route files.\n
\n @riebeckite/honox/ui is deliberately a small structural contract, not a\n component framework. Its complete public component surface is:\n
Article, ArticleLayout, ArticleHeader, ArticleContent,\n ArticleBody, PageBody, ArticleMeta, ArticleFooter, and ContentSlot\n for an article page;\n Sidebar for complementary content.\n The corresponding *Props types are public. ContentSlot is paired with the\n pure hasSlot(slots, name) helper, and the ARTICLE_SLOT constant provides\n the standard slot names. These stable styling hooks are the only classes\n supplied by the contract: rb-article, rb-article-layout, rb-article-header,\n rb-article-body, rb-article-content, rb-article-meta, rb-article-footer,\n and rb-sidebar, in the component order above. Primitives provide semantic\n HTML, those hooks, class/className composition, and the structural CSS that\n makes the hooks work. That structural CSS ships in @riebeckite/honox/style.css\n and reaches the site through the generated .riebeckite/framework-styles.css.\n Primitives do not own article copy, metadata formatting, navigation placement,\n cards, page-layout composition, islands, or site visual design and overrides.\n Those belong to the site application. ArticleHeader and ArticleContent\n accept either children or their HTML input prop, never both. ArticleBody\n renders rendered Markdown as .rb-article-content, and Markdown typography is\n scoped to that wrapper, so plugin components keep their own headings wherever\n they are placed. ContentSlot looks a slot up by name in the slots map and\n renders it with a data-slot attribute; a missing, empty, or whitespace-only\n slot renders nothing, and class/className add site classes. It never infers\n a semantic element from the slot name.\n
import {\n Article,\n ArticleBody,\n ArticleContent,\n ArticleLayout,\n ContentSlot,\n} from \"@riebeckite/honox/ui\";\n \n<Article class=\"site-article\">\n <ArticleLayout>\n <ContentSlot\n slots={bodySlots}\n name=\"article.aside\"\n class=\"site-article__aside\"\n />\n <ArticleContent>\n <ContentSlot slots={bodySlots} name=\"article.header\" />\n <ContentSlot slots={bodySlots} name=\"article.metadata\" />\n <ArticleBody html={post.html ?? \"\"} />\n </ArticleContent>\n </ArticleLayout>\n</Article>;\n Use the primitives as composition points, then style them from the site. Pass\n rendered Markdown to ArticleBody; ArticleContent html={...} remains for\n backward compatibility but is deprecated. Do not import files below\n @riebeckite/honox/src/ or rely on any unlisted component.\n
\n A Riebeckite site is a normal HonoX application. The integration supplies\n content and build wiring; the application owns every user-facing decision.\n Keep the following source directories in the site, rather than in an\n integration, theme, or plugin. For a walkthrough of editing them with ordinary\n HonoX, see Customizing Your Site.\n
\n| Directory | \nSite-owned responsibility | \n
|---|---|
app/routes/ | \n URL handling, page composition, redirects, and response metadata | \n
app/components/ | \n Reusable site presentation and composition of the public UI primitives | \n
app/islands/ | \n Optional interactive UI and its client-side state | \n
app/style.css and local CSS | \n Visual tokens, layout, typography, and imports of generated extension styles | \n
\n app/routes/_renderer.tsx is the site shell. It owns the document head,\n navigation, page chrome, and the application client entry. A route resolves a\n request with resolveRiebeckiteContentRequest(c, content) — which also sets the\n htmlLanguage and headTags context — then chooses its own component tree.\n The reference application in apps/web is one implementation, not a required\n layout.\n
\n When a plugin provides document head tags, the shell still belongs to the\n site. A plugin only describes meta / link / script on\n ContentManifestEntry.headTags; it never renders them.\n resolveRiebeckiteContentRequest / resolveRiebeckiteHomeRequest set the\n resolved entry's tags into the route context, and app/routes/_renderer.tsx\n decides whether to render them. A plugin does not own the <head> or the tag\n order.\n
// app/routes/_renderer.tsx\nimport { PluginHeadTags } from \"@riebeckite/honox/ui\";\n \nconst headTags = c.get(\"headTags\") ?? [];\n \n<head>\n <PluginHeadTags tags={headTags} />\n</head>;\n For example, @riebeckite/plugin-discord-embed, which aligns the Discord embed\n color, supplies theme-color through this contract.\n
\n @riebeckite/honox/ui provides two primitives that clarify the separation of\n responsibilities between the framework and the site for head composition.\n
RiebeckiteHeadimport { RiebeckiteHead } from \"@riebeckite/honox/ui\";\n \n<RiebeckiteHead title=\"My Site\" headTags={[]} />The framework renders the standard head contents:
\n<meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"><title> (the value provided by the title prop)<link rel=\"icon\" href=\"/favicon.ico\"> (overridable via the faviconHref prop; pass null to omit)<ColorModeScript /> (controlled by the colorModeScript prop, default true)stylesheets prop, default [\"/app/style.css\"])clientSrc prop, default \"/app/client.ts\"; null omits it)PluginHeadTag values (via the headTags prop)children prop) appended after the standard ones\n RiebeckiteHead does not render the <head> element itself. The site retains\n ownership of <head> and can add custom meta/link/script alongside it.\n
PluginHeadTagsimport { PluginHeadTags } from \"@riebeckite/honox/ui\";\n \n<PluginHeadTags tags={headTagsFromManifest} />\n Converts PluginHeadTag values (meta / link / script) into JSX elements. Use this\n when the site composes its own head and does not use RiebeckiteHead.\n
For example, a site that keeps <head> ownership and uses RiebeckiteHead:
import { RiebeckiteHead, ThemeRoot } from \"@riebeckite/honox/ui\";\n \nexport default jsxRenderer(({ children }, c) => (\n <ThemeRoot\n theme={config.theme}\n lang={c.get(\"htmlLanguage\") ?? config.site.locale}\n >\n <head>\n <RiebeckiteHead\n title={config.site.title}\n headTags={c.get(\"headTags\") ?? []}\n />\n <meta name=\"custom-site-value\" content=\"...\" />\n </head>\n <body class=\"riebeckite-page rb-site\">{children}</body>\n </ThemeRoot>\n));The framework owns the standard head rendering mechanics (charset, viewport, default title, favicon wiring, color-mode bootstrap, stylesheet/client entry wiring, PluginHeadTag conversion) and theme-root attribute derivation. The site still owns <head>/<body> composition and can add custom meta/link/script. The favicon FILE (/public/favicon.ico) remains site-owned; only the default link wiring is framework-owned.
Plugin-provided head tags continue to work through the existing headTags mechanism. RiebeckiteHead and headTags can be used together.
\n When a plugin contributes HTML that belongs inside the note body, the site still\n owns where it is rendered. A plugin only writes an HTML fragment into\n ContentManifestEntry.bodySlots under a slot name; it never changes a route,\n the shell, or the render order. A site route passes the slot object to its\n article component, which decides whether and where to render each slot.\n
// app/routes/[slug{.+}].tsx\n<Article\n content={post}\n bodySlots={route.entry.bodySlots}\n/>;\n The Article here is the site's own article component, not the\n @riebeckite/honox/ui primitive of the same name. The scaffolded starter\n renders the standard slots at fixed positions: article.aside,\n article.header, article.metadata, article.before-content,\n article.after-content, and article.footer. A plugin author picks one of\n those, or asks the site to render a custom name; a custom slot renders nothing\n until the site chooses to render it.\n
\n The site chooses which slot goes where and delegates the rendering mechanics to\n the public ContentSlot primitive.\n
<ArticleContent>\n <ContentSlot slots={bodySlots} name=\"article.header\" />\n <ContentSlot\n slots={bodySlots}\n name=\"article.metadata\"\n class=\"site-article__metadata\"\n />\n <ArticleBody html={post.html ?? \"\"} />\n</ArticleContent>\n ContentSlot owns the slot lookup, missing and empty handling, HTML fragment\n rendering, and the data-slot attribute, so the site never writes\n dangerouslySetInnerHTML for a standard slot. Order, visibility, site classes,\n and custom slot names still belong to the site. The escape hatches remain:\n read slots directly, wrap a slot in any element, and render the same slot more\n than once.\n
\n For example, @riebeckite/plugin-properties publishes its property panel on\n the properties slot when configured with render: \"slot\". The default\n render: \"html\" keeps inserting the panel at the start or end of the note HTML.\n A plugin never owns routes or the shell.\n
\n Article-end plugin sections share article.footer. Render that slot once in\n the article component; the resolved plugin order determines the fragment\n sequence, and an empty contribution does not create a DOM node.\n
\n For example, an external site can compose an article with the stable primitive\n contract while retaining all presentation ownership:\n
\n// app/components/article.tsx\nimport type { ContentBodySlots, PostContent } from \"@riebeckite/core\";\nimport {\n Article,\n ArticleBody,\n ArticleContent,\n ArticleLayout,\n ContentSlot,\n} from \"@riebeckite/honox/ui\";\n \nexport function SiteArticle({\n post,\n bodySlots,\n}: {\n post: PostContent;\n bodySlots?: ContentBodySlots;\n}) {\n return (\n <Article class=\"site-article\">\n <ArticleLayout>\n <ArticleContent>\n <ContentSlot slots={bodySlots} name=\"article.header\" />\n <ArticleBody html={post.html ?? \"\"} />\n <ContentSlot slots={bodySlots} name=\"article.footer\" />\n </ArticleContent>\n </ArticleLayout>\n </Article>\n );\n}\n Import generated extension styles from the site's stylesheet, but never edit\n the generated files themselves:\n
\n/* app/style.css */\n@import \"./.riebeckite/framework-styles.css\";\n@import \"./.riebeckite/plugin-styles.css\";\n@import \"./.riebeckite/theme-styles.css\";\n \n.site-article { max-width: 48rem; margin: 0 auto; }\n Islands are also ordinary application modules. Place a HonoX island under\n app/islands/, import it from the route or component that owns it, and keep\n its hydration and client state local to the site. app/client.ts must continue\n to initialize both createClient() and initRiebeckiteClient(); the latter\n starts browser entries contributed by installed plugins and themes. A plugin\n may contribute its own client entry, but it must not take ownership of a\n site's routes, shell, components, islands, or CSS decisions.\n
\n The external-site E2E fixture contains this minimal arrangement: a site shell,\n a local article component built from @riebeckite/honox/ui, a local island,\n and site CSS. It is built from packed npm artifacts, so it is the supported\n example for copying and overriding these boundaries.\n
\n Not-found handling is HonoX's standard app/routes/_404.tsx. Riebeckite decides\n that a request is not found; HonoX re-renders that response through the site's\n _renderer.tsx, so the status stays 404 while the not-found screen belongs to\n the site.\n
// app/routes/_404.tsx\nimport type { NotFoundHandler } from \"hono\";\n \nconst handler: NotFoundHandler = (c) => {\n c.status(404);\n return c.render(<main class=\"not-found\">Page not found</main>);\n};\n \nexport default handler;\n The route resolver (resolveRiebeckiteContentRequest,\n resolveRiebeckiteHomeRequest, and plugin page resolution) and the extension\n guard that keeps asset-like paths out of the content route stay in\n @riebeckite/honox; the site never reimplements them. Only public, routable\n content resolves, so a not-found response never carries draft, future-dated, or\n private metadata.\n
\n Runtime errors use Hono's own error handling. Without an app/routes/_error.tsx\n the default handler logs the error and returns a plain 500 Internal Server Error; a site may add _error.tsx (an ErrorHandler) when it wants a\n visitor-facing screen. Configuration, plugin, and build failures are\n developer-facing and must not be turned into a successful page.\n
Article routing resolves a request against the manifest's already-resolved public locations (byPermalink, then redirects), never by inferring a URL from a filesystem path, directory layout, or slug. A slug remains an internal content lookup key; the public URL is the resolved permalink.
Keep HonoX, Vite, Cloudflare, and route APIs in this package or apps/web; Core remains portable. A plugin can expose assets, client entries, endpoints, and renderers, but Core does not become a HonoX router. The application decides concrete route composition and islands.
Use Build system for state behavior and Architecture for package ownership.
\n","summary":"HonoX Integration @riebeckite/honox connects portable Core behavior to HonoX and Vite. It owns application-root/config resolution, Vite development and build in","tags":[]},{"id":"https://riebeckite.dev/docs/framework/honox-integration","url":"https://riebeckite.dev/docs/framework/honox-integration","title":"honox-integration","content_html":"\n@riebeckite/honox は、Riebeckite Core と HonoX / Vite を接続する integration です。
Core はコンテンツやプラグインの処理を担当しますが、HonoX の route や Vite の build 方法については知りません。
\nその間を接続するのが @riebeckite/honox です。
flowchart LR\n A[\"Riebeckite Core<br/>Content / Plugin / Manifest\"]\n B[\"@riebeckite/honox<br/>Integration\"]\n C[\"HonoX / Vite<br/>Application\"]\n \n A --> B\n B --> C主に次の処理を担当します。
\nこれにより、通常の Site は Riebeckite 内部の Vite / HonoX 設定を毎回組み立てる必要がありません。
\n通常は vite.config.ts で riebeckiteVite() を登録します。
import { riebeckiteVite } from \"@riebeckite/honox\";\nimport { defineConfig } from \"vite\";\n \nexport default defineConfig({\n plugins: [honox({ ... }), ...riebeckiteVite(), build()],\n});riebeckiteVite() は通常の Site 向けの higher-level helper です。
Riebeckite の Vite plugin を追加するだけでなく、次の設定もまとめて行います。
\nHonoX plugin、deployment 用 build plugin、Tailwind など、Site 自身が必要とする Vite plugin と組み合わせて利用できます。
\nriebeckiteVite() では、必要に応じて次の場所を指定できます。
| Option | \n意味 | \n
|---|---|
appRoot | \n Site application の基準ディレクトリ | \n
configRoot | \n Riebeckite config を探す基準 | \n
configFile | \n 使用する config file | \n
workspaceRoot | \n monorepo 開発時の workspace root | \n
通常は指定する必要はありません。
\nappRoot の既定値は Vite root、configRoot の既定値は appRoot です。
Riebeckite config は configRoot を基準に読み込みます。
一方、
\ncontent: {\n directory: \"./content\",\n}のような content directory は appRoot を基準に解決します。
resolveHonoxApplication() は、これらの root と解決済み config をまとめて返します。
CLI と Vite がこの共通モデルを利用することで、それぞれが異なる方法で application を解決しないようにしています。
\nworkspaceRootworkspaceRoot は、Riebeckite 自体を monorepo で開発するときに source package alias を利用するための設定です。
npm から Riebeckite をインストールした通常の Site では必要ありません。
\nその場合は Site 自身の node_modules から package が解決されます。
.riebeckite に生成されるファイルIntegration は application 内の
\napp/.riebeckite/へ、plugin や theme を接続するためのファイルを生成します。
\nたとえば plugin style や theme style です。client module は .riebeckite には生成されず、virtual module として提供されます。
flowchart LR\n A[\"Installed Plugins / Themes\"]\n B[\"@riebeckite/honox\"]\n C[\"app/.riebeckite/\"]\n D[\"Site Application\"]\n \n A --> B\n B -->|\"generated entries\"| C\n C --> D.riebeckite は integration が管理する生成物です。
Site の source code として直接編集しないでください。
\ngenerated Site は Framework 所有の bootstrap module を import します。解決済み config は virtual:riebeckite/config、構成済みの content runtime は virtual:riebeckite/content です。そのため app/config.ts、app/content.ts、app/constants/paths.ts は生成されません。SSG entry の app/server.ts はこの2つを re-export し、riebeckiteSsg はそこから manifest を見つけます。
Vite の外で動く script（tsx で起動する Node script など）は @riebeckite/honox/runtime の resolveHonoxConfig で同じ config を解決できます。
より細かく integration を制御したい場合は、lower-level API も利用できます。
\nriebeckiteriebeckiteSsgriebeckiteSsgExtensionMapcreateRiebeckiteSsg通常の Site では riebeckiteVite() を利用し、独自の build integration が必要な場合のみ lower-level API を利用してください。
HonoX の runtime routing と静的生成では、同じ URL が同じページとして扱われる必要があります。
\n特に catch-all route がある場合、SSG の route 列挙に注意が必要です。
\nRiebeckite はこのために2つの helper を提供します。
\ncontentRouteSsgParamscontentRouteSsgParams(routePath, params)hono/ssg の ssgParams の代わりとして使用します。
この helper は、その route 自身に属する params だけを返します。
\nたとえば、
\n/:slug{.+}という catch-all route があっても、
\n/tags/:slug{.+}に属するページまで横取りしません。
\nssgEnumerableHandlerssgEnumerableHandler(handler)next() を使って sibling route に処理を渡す handler を、SSG の列挙対象として残すための helper です。
Hono は middleware 形式の handler を通常 SSG の列挙対象から外すため、この差を補います。
\nPlugin は通常の content とは別に、独自のページを提供できます。
\nその場合は、
\nresolveContentRoute(manifest, path)ではなく、
\nresolveRiebeckiteRoute(content, path)を使用します。
\nSSG params には、
\npluginPageSsgParams(content)を追加します。
\n生成された Site の catch-all route は、これらをまとめた resolveRiebeckiteContentRequest(c, content) を使用します。この helper が content / Plugin Page / redirect / not-found を解決し、htmlLanguage と headTags を context へ設定するため、Site は返された結果を自身の composition に渡すだけで済みます。root / も同じ mechanics を共有する resolveRiebeckiteHomeRequest(c, content) で解決します。
Route resolver は次の順序で URL を解決します。
\nflowchart TD\n A[\"Request Path\"]\n B{\"Plugin Page?\"}\n C[\"Plugin Page\"]\n D{\"Content?\"}\n E[\"Content\"]\n F{\"Redirect?\"}\n G[\"Redirect\"]\n H[\"Not Found\"]\n \n A --> B\n B -->|Yes| C\n B -->|No| D\n D -->|Yes| E\n D -->|No| F\n F -->|Yes| G\n F -->|No| HPlugin Page の body は意図的に文字列として扱います。
\nSite が持つ既存の document frame 内へ描画し、page.headTags も Site の frame へ渡します。
この仕組みにより、Plugin が独自ページを提供するためだけに HonoX の route file を追加する必要はありません。
\n@riebeckite/honox/ui は UI framework ではありません。
Site が独自のデザインを作りながら、Riebeckite と共通の HTML 構造を利用するための小さな primitive set です。
\n公開されている主な component は次のとおりです。
\nArticleArticleLayoutArticleHeaderArticleContentArticleBodyPageBodyArticleMetaArticleFooterContentSlotSidebar対応する *Props 型も公開されています。ContentSlot には hasSlot(slots, name) という純粋 helper が対応し、ARTICLE_SLOT 定数が標準 slot 名を提供します。
各 primitive は次の class を stable styling hook として提供します。
\n| Component | \nClass | \n
|---|---|
Article | \n rb-article | \n
ArticleLayout | \n rb-article-layout | \n
ArticleHeader | \n rb-article-header | \n
ArticleContent | \n rb-article-body | \n
ArticleBody | \n rb-article-content | \n
ArticleMeta | \n rb-article-meta | \n
ArticleFooter | \n rb-article-footer | \n
Sidebar | \n rb-sidebar | \n
ArticleBody はレンダリング済み Markdown 本文を .rb-article-content として描画し、Markdown typography はこの wrapper にのみ適用されます。plugin component の見出しは plugin 自身が所有します。
ContentSlot は slots map から slot 名で HTML fragment を取り出し、data-slot を付けて描画します。存在しない slot、空文字、whitespace のみの slot は何も描画しません。class / className で Site 固有 class を追加できます。slot 名から semantic 要素を推測するような暗黙の mapping は行いません。
Primitive が担当するのは主に、
\nclass / className の合成です。rb-* hook を成立させる構造 CSS は @riebeckite/honox/style.css にあり、生成された .riebeckite/framework-styles.css 経由で Site に読み込まれます。
一方、
\nは Site Application が管理します。
\nimport {\n Article,\n ArticleBody,\n ArticleContent,\n ArticleLayout,\n ContentSlot,\n} from \"@riebeckite/honox/ui\";\n \n<Article class=\"site-article\">\n <ArticleLayout>\n <ContentSlot\n slots={bodySlots}\n name=\"article.aside\"\n class=\"site-article__aside\"\n />\n <ArticleContent>\n <ContentSlot slots={bodySlots} name=\"article.header\" />\n <ContentSlot slots={bodySlots} name=\"article.metadata\" />\n <ArticleBody html={post.html ?? \"\"} />\n </ArticleContent>\n </ArticleLayout>\n</Article>;ArticleHeader と ArticleContent は、children と HTML input prop のどちらか一方だけを受け取ります。レンダリング済み Markdown 本文は ArticleBody に渡してください。ArticleContent html={...} は後方互換のために残っていますが非推奨です。
Primitive は composition point として使用し、構造は Framework の hook CSS が、見た目は Site 側が定義してください。
\nまた、
\n@riebeckite/honox/src/以下を直接 import しないでください。
\n公開 API として記載されていない内部 component に依存することも避けてください。
\nRiebeckite Site は、最終的には通常の HonoX application です。
\n@riebeckite/honox は content と build を接続しますが、実際にユーザーが見る UI の設計は Site が管理します。通常の HonoX で編集する手順は サイトのカスタマイズ を参照してください。
flowchart TD\n A[\"Riebeckite Core<br/>content / manifest / plugin\"]\n B[\"@riebeckite/honox<br/>build / routing integration\"]\n C[\"Site Application\"]\n \n C --> D[\"app/routes/<br/>URL / page composition\"]\n C --> E[\"app/components/<br/>Site UI\"]\n C --> F[\"app/islands/<br/>Interactive UI\"]\n C --> G[\"app/style.css<br/>Visual Design\"]\n \n A --> B\n B --> C主なディレクトリの責務は次のとおりです。
\n| ディレクトリ | \nSite が持つ責務 | \n
|---|---|
app/routes/ | \n URL処理、ページ構成、redirect、response metadata | \n
app/components/ | \n Site 固有の UI | \n
app/islands/ | \n 対話 UI と client-side state | \n
app/style.css | \n 色、layout、typography、extension style | \n
app/routes/_renderer.tsxは Site 全体の shell です。
\nここでは主に、
\nなどを管理します。
\nRoute は ContentManager からコンテンツを取得し、
resolveRiebeckiteRoute(content, c.req.path)で request URL を解決します。
\nその結果をどの component tree で表示するかは Site が決定します。
\nRiebeckite repository にある apps/web は実装例の1つであり、外部 Site が同じ layout を使う必要はありません。
not-found の処理は HonoX 標準の app/routes/_404.tsx です。Riebeckite が「見つからない」と判断し、HonoX がその response を Site の _renderer.tsx を通して描画し直すため、status は 404 のまま、not-found 画面の見た目は Site が所有します。
// app/routes/_404.tsx\nimport type { NotFoundHandler } from \"hono\";\n \nconst handler: NotFoundHandler = (c) => {\n c.status(404);\n return c.render(<main class=\"not-found\">Page not found</main>);\n};\n \nexport default handler;route resolver（resolveRiebeckiteContentRequest、resolveRiebeckiteHomeRequest、Plugin Page の解決）と、asset-like な path を content route に入れない extension guard は @riebeckite/honox に残ります。Site がこれらを再実装することはありません。解決されるのは公開済みで routable な content だけなので、not-found response に draft・未来公開・非公開 content の metadata が載ることもありません。
runtime error は Hono の error 処理を使います。app/routes/_error.tsx が無ければ、標準の handler が error をログに記録し、500 Internal Server Error を返します。visitor 向けの画面が必要な場合に限り、Site は _error.tsx（ErrorHandler）を追加できます。config、plugin、build の失敗は開発者向けであり、成功したページに変換してはいけません。
Plugin は Site に情報や UI fragment を提供できます。
\nただし、最終的にどこへ描画するかは Site が決定します。
\nflowchart LR\n A[\"Plugin\"]\n B[\"Manifest\"]\n C[\"Site Route\"]\n D[\"Site Shell / Component\"]\n \n A -->|\"headTags / bodySlots / page\"| B\n B --> C\n C -->|\"placement\"| DPlugin が document head に情報を追加したい場合は、
\nContentManifestEntry.headTagsへ meta / link / script を記述します。
Plugin 自身が <head> を描画するわけではありません。
resolveRiebeckiteContentRequest / resolveRiebeckiteHomeRequest が、解決した entry の headTags を route context へ設定します。_renderer.tsx がそれを読み取って描画します。
import { PluginHeadTags } from \"@riebeckite/honox/ui\";\n \nconst headTags = c.get(\"headTags\") ?? [];\n \n<head>\n <PluginHeadTags tags={headTags} />\n</head>;つまり、
\nPlugin\n ↓ headTags を提供\nFramework resolver\n ↓ context へ設定\n_renderer.tsx\n ↓\n<head> に描画という関係です。
\nたとえば @riebeckite/plugin-discord-embed は、この仕組みを使って theme-color を提供します。
Plugin は <head> 自体や tag の並び順を所有しません。
@riebeckite/honox/ui より公開される 2 つの primitive は、head composition の責務分離を明確にします。
RiebeckiteHeadimport { RiebeckiteHead } from \"@riebeckite/honox/ui\";\n \n<RiebeckiteHead title=\"My Site\" headTags={[]} />Framework が次の標準的な head contents を描画します。
\n<meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"><title>（title prop が提供する値）<link rel=\"icon\" href=\"/favicon.ico\">（faviconHref プロップで上書き可能、null で省略可）<ColorModeScript />（colorModeScript プロップで制御、default true）[\"/app/style.css\"]）\"/app/client.ts\"、null で省略可）PluginHeadTag values の変換（headTags プロップ）RiebeckiteHead は <head> 要素自身を描画しません。Site は <head> の ownership を保持し、その中に RiebeckiteHead を配置できます。
PluginHeadTagsimport { PluginHeadTags } from \"@riebeckite/honox/ui\";\n \n<PluginHeadTags tags={headTagsFromManifest} />PluginHeadTag values (meta / link / script) を JSX 要素に変換します。RiebeckiteHead を使わず、Site が自分で head を組み立てる際に使用します。
Site が <head> 所有権を維持しつつ標準 head をFrameworkに任せる場合：
import { RiebeckiteHead, ThemeRoot } from \"@riebeckite/honox/ui\";\n \nexport default jsxRenderer(({ children }, c) => (\n <ThemeRoot\n theme={config.theme}\n lang={c.get(\"htmlLanguage\") ?? config.site.locale}\n >\n <head>\n <RiebeckiteHead\n title={config.site.title}\n headTags={c.get(\"headTags\") ?? []}\n />\n <meta name=\"custom-site-value\" content=\"...\" />\n </head>\n <body class=\"riebeckite-page rb-site\">{children}</body>\n </ThemeRoot>\n);Frameworkは標準 head rendering メカニクス（charset、viewport、default title、favicon wiring、color-mode bootstrap、stylesheet/client entry wiring、PluginHeadTag 変換）と theme-root attribute 導出を担当し、Site は <head>/<body> 構成とカスタム meta/link/script の所有権を保持します。favicon FILE (/public/favicon.ico) は Site-owned のまま、default link wiring にのみ Framework が所有権を持ちます。
Plugin が head tags を提供する場合は、既存の headTags メカニズムはそのまま機能します。RiebeckiteHead と headTags は併用可能です。
本文の途中へ Plugin の HTML を表示したい場合は、
\nContentManifestEntry.bodySlotsを使用します。
\nPlugin は slot 名と HTML fragment を提供します。
\nたとえば、
\npropertiesという slot があれば、Route は slot object を article component へ渡し、Site は、
\n<Article\n content={post}\n bodySlots={route.entry.bodySlots}\n/>のように article component 内の任意の位置へ配置できます。
\nここでの Article は Site 自身の article component であり、同名の @riebeckite/honox/ui primitive ではありません。scaffold の starter は標準 slot を決まった位置へ描画します(article.aside、article.header、article.metadata、article.before-content、article.after-content、article.footer)。plugin 作者はこれらから選ぶか、Site に独自名の描画を依頼します。独自 slot は Site が描画を選ぶまで何も表示しません。
Site はどの slot をどこへ置くかを選び、描画の仕組みは公開 ContentSlot primitive に任せます。
<ArticleContent>\n <ContentSlot slots={bodySlots} name=\"article.header\" />\n <ContentSlot\n slots={bodySlots}\n name=\"article.metadata\"\n class=\"site-article__metadata\"\n />\n <ArticleBody html={post.html ?? \"\"} />\n</ArticleContent>ContentSlot は slot lookup、存在しない slot や空 slot の扱い、HTML fragment の描画、data-slot の付与を担当します。Site が dangerouslySetInnerHTML を直接書く必要はありません。順序、可視性、Site 固有 class、独自 slot 名は引き続き Site が所有します。slots を直接読んだり、任意の wrapper で包んだり、同じ slot を複数回描画する escape hatch も残っています。
Plugin が route や shell の構造を書き換える必要はありません。
\n@riebeckite/plugin-properties では、
render: \"slot\"を指定すると properties slot を提供します。
render: \"html\" は従来どおり、生成 HTML の先頭または末尾へ直接挿入します。
記事末尾の Plugin section は article.footer に集約します。article component ではこの slot を一度だけ描画し、fragment の順序は解決済み Plugin の order で決めます。空の contribution は DOM node を生成しません。
外部 Site でも、公開 primitive を使いながら自由に component を構成できます。
\nimport type { ContentBodySlots, PostContent } from \"@riebeckite/core\";\nimport {\n Article,\n ArticleBody,\n ArticleContent,\n ArticleLayout,\n ContentSlot,\n} from \"@riebeckite/honox/ui\";\n \nexport function SiteArticle({\n post,\n bodySlots,\n}: {\n post: PostContent;\n bodySlots?: ContentBodySlots;\n}) {\n return (\n <Article class=\"site-article\">\n <ArticleLayout>\n <ArticleContent>\n <ContentSlot slots={bodySlots} name=\"article.header\" />\n <ArticleBody html={post.html ?? \"\"} />\n <ContentSlot slots={bodySlots} name=\"article.footer\" />\n </ArticleContent>\n </ArticleLayout>\n </Article>\n );\n}見た目は Site の CSS で定義します。
\n@import \"./.riebeckite/framework-styles.css\";\n@import \"./.riebeckite/plugin-styles.css\";\n@import \"./.riebeckite/theme-styles.css\";\n \n.site-article {\n max-width: 48rem;\n margin: 0 auto;\n}.riebeckite 内の生成 CSS 自体を直接編集しないでください。
Island も通常の Site module として管理します。
\napp/islands/へ HonoX island を配置し、それを利用する route または component から import します。
\nhydration や client-side state は Site 内で管理します。
\napp/client.ts では、
createClient();\ninitRiebeckiteClient();の両方を初期化します。
\ninitRiebeckiteClient() は、インストールされている Plugin や Theme が提供する browser entry を起動するために使用されます。
Plugin は client entry を提供できますが、
\nそのものを所有してはいけません。
\nRiebeckite の routing では、すでに解決された公開 URL を使用します。
\n基本的には、
\nbyPermalink\n ↓\nredirectsの順で request を解決します。
\nfilesystem path やディレクトリ構造から公開 URL を逆算しません。
\nまた、slug はコンテンツを内部で検索するためのキーです。
実際に公開される URL は、解決済みの permalink です。
Riebeckite 全体では、次のように責務を分離します。
\nflowchart LR\n Core[\"Core<br/>Content / Manifest / Plugin API\"]\n Integration[\"HonoX Integration<br/>Vite / SSG / Route Resolution\"]\n Plugin[\"Plugin<br/>Content Extension / Page / Asset / Client Entry\"]\n Site[\"Site Application<br/>Route / Shell / UI / Island / CSS\"]\n \n Core --> Integration\n Plugin --> Core\n Integration --> Site\n Plugin -. \"提供した情報を<br/>Site が配置\" .-> SiteHonoX / Vite / Cloudflare 固有の処理は integration または Site Application に閉じます。
\nCore は HonoX routing を所有しません。
\nPlugin はページ、アセット、client entry などを提供できますが、Site 全体の route composition や UI 構造は所有しません。
\nCore はコンテンツを扱い、Integration は HonoX と接続し、Plugin は機能を提供し、Site が最終的な表示を決める、という境界を維持してください。
\nbuild state の扱いについては Build system、package ごとの責務については Architecture を参照してください。
\n","summary":"HonoX Integration @riebeckite/honox は、Riebeckite Core と HonoX / Vite を接続する integration です。 Core はコンテンツやプラグインの処理を担当しますが、HonoX の route や Vite の build 方法については知りません","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/inspector","url":"https://riebeckite.dev/en/docs/framework/inspector","title":"inspector.en","content_html":"\nInspector answers questions about already-resolved state. Use it through the CLI:
\nriebeckite inspect config\nriebeckite inspect plugins\nriebeckite inspect content --list\nriebeckite inspect graph\nriebeckite inspect buildInspection is factual and non-mutating. It must not run a build, write incremental state or plugin cache, emit assets, render special artifacts merely for display, invoke Vite/HonoX build work, or auto-fix configuration. If the requested information does not exist because no build has completed, report that condition plainly.
\ninspect content --list reports each entry's resolved canonical permalink. When a public-location plugin records identity metadata, it also shows the ID and the ID source.
inspect build reports the incremental state status. When the state is invalid, it also reports the reason: malformed JSON, an unsupported state version, or an unrecognized structure.
Separating these commands makes automated tooling safe: a CI diagnostic command cannot accidentally modify cache or deployment output. See CLI and Diagnostics.
\n","summary":"Inspector Inspector answers questions about already-resolved state. Use it through the CLI: sh Wrap Copy riebeckite inspect config riebeckite inspect plugins ri","tags":[]},{"id":"https://riebeckite.dev/docs/framework/inspector","url":"https://riebeckite.dev/docs/framework/inspector","title":"inspector","content_html":"\nInspector は、Riebeckite がすでに解決した設定やコンテンツ、Plugin、Build State を確認するための機能です。
\n簡単に言えば、「Riebeckite から今どう見えているか」を調べるための読み取り専用ツールです。
\nたとえば、
\nといった情報を確認できます。
\nflowchart LR\n A[\"Config\"]\n B[\"Plugins\"]\n C[\"Content\"]\n D[\"Content Graph\"]\n E[\"Build State\"]\n \n A --> I[\"Inspector\"]\n B --> I\n C --> I\n D --> I\n E --> I\n \n I --> F[\"情報を表示するだけ\"]Inspector はこれらの情報を確認するだけで、build や設定の変更は行いません。
\nInspector には、確認したい対象ごとにコマンドがあります。
\n| コマンド | \n確認できるもの | \n
|---|---|
riebeckite inspect config | \n 解決済みの設定 | \n
riebeckite inspect plugins | \n 有効になっている Plugin | \n
riebeckite inspect content --list | \n 公開コンテンツと URL | \n
riebeckite inspect graph | \n コンテンツ同士の関係 | \n
riebeckite inspect build | \n incremental build の state | \n
riebeckite inspect configRiebeckite が実際に使用する 解決済みの config を確認します。
\n設定ファイルに書いた値そのものではなく、既定値なども適用された後の「Riebeckite が最終的に認識している設定」を確認したいときに使用します。
\nたとえば、
\n\n\n設定したはずなのに期待した動作にならない
\n
という場合に、まず実際の設定値を確認できます。
\nriebeckite inspect plugins現在有効になっている Plugin を確認します。
\n「Plugin を追加したつもりだけれど、本当に読み込まれているのか」を調べるときなどに利用できます。
\nriebeckite inspect content --listRiebeckite が認識しているコンテンツを一覧表示します。
\n各 entry について、解決済みの canonical permalink を確認できます。
\nたとえば、
\ncontent/posts/hello.mdというファイルがあっても、実際の公開 URL が
\n/blog/hello/であれば、Inspector では最終的に解決された /blog/hello/ を確認できます。
つまり、filesystem 上の場所ではなく、実際にサイトで使われる URL を確認するための情報です。
\nPublic Location Plugin が identity metadata を提供している場合は、コンテンツ ID とその ID がどこから取得されたかも表示します。
\nriebeckite inspect graphコンテンツ同士の関係を確認します。
\nたとえば、
\ngraph LR\n A[\"article-a\"] --> B[\"article-b\"]\n A --> C[\"article-c\"]\n C --> Bのようなリンク関係を、Riebeckite がどのように認識しているか調べるために利用します。
\nリンク、backlink、graph を利用する Plugin を開発するときの確認にも使えます。
\nriebeckite inspect buildincremental build で利用する state の状態を確認します。
\n正常な state が存在する場合は、その情報を表示します。
\nstate が利用できない場合は、その理由も確認できます。
\nたとえば、
\nといった状態です。
\nInspector はこれらを修復しません。
\nflowchart TD\n A[\"inspect build\"]\n B{\"Build State は存在する？\"}\n \n A --> B\n B -->|Yes| C{\"State は有効？\"}\n B -->|No| D[\"State がないことを表示\"]\n \n C -->|Yes| E[\"State の情報を表示\"]\n C -->|No| F[\"無効な理由を表示\"]\n \n D --> G[\"終了\"]\n E --> G\n F --> Gstate が壊れていても、Inspector が新しい state を作ったり、既存 state を書き換えたりすることはありません。
\nInspector は read-only です。
\nInspector の実行によってプロジェクトの状態が変わってはいけません。
\n具体的には、次の処理を行いません。
\nまだ一度も build しておらず、確認対象の情報が存在しない場合も、Inspector が勝手に生成することはありません。
\n代わりに、
\n\n\n現在はその情報が存在しない
\n
ことを明確に表示します。
\nこの性質により、Inspector は開発中だけでなく CI でも安全に利用できます。
\ninspect / check / doctor / build の違いRiebeckite には似た目的に見えるコマンドがありますが、それぞれ役割が異なります。
\nflowchart LR\n Q{\"何をしたい？\"}\n \n Q -->|\"現在の状態を見たい\"| I[\"inspect\"]\n Q -->|\"設定が正しいか確認したい\"| C[\"check\"]\n Q -->|\"環境を含めて問題を調べたい\"| D[\"doctor\"]\n Q -->|\"サイトを生成・更新したい\"| B[\"build\"]\n \n I --> IR[\"状態を変更しない\"]\n C --> CR[\"Config / Plugin を検証\"]\n D --> DR[\"Health を診断\"]\n B --> BR[\"Output / State を更新\"]| やりたいこと | \nコマンド | \n
|---|---|
| 現在の解決結果を確認する | \ninspect | \n
| Config / Plugin が正しいか検証する | \ncheck | \n
| Environment を含めて問題を診断する | \ndoctor | \n
| Site や Build State を生成・更新する | \nbuild | \n
迷った場合は、
\n「見るだけなら inspect、検証なら check、問題調査なら doctor、生成するなら build」
と考えると分かりやすいです。
\nこの役割分担によって、状態を確認するだけのコマンドが cache や deployment output を意図せず変更することを防いでいます。
\n各コマンドの詳細は CLI、診断の仕組みについては Diagnostics、incremental state については Build System を参照してください。
\n","summary":"Inspector Inspector は、Riebeckite がすでに解決した設定やコンテンツ、Plugin、Build State を確認するための機能です。 簡単に言えば、 「Riebeckite から今どう見えているか」を調べるための読み取り専用ツール です。 たとえば、 実際にどの設定が使われているか どの","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/observability","url":"https://riebeckite.dev/en/docs/framework/observability","title":"observability.en","content_html":"\nRiebeckite separates logs, traces, and profiling so each answers a different question.
\n| Signal | \nAnswers | \nContract | \n
|---|---|---|
| Logger | \nWhat happened or failed? | \nstructured, safe operational messages | \n
Tracer / TraceSink | \n Where did work occur and how long did it take? | \nnested timed spans | \n
| Profiler | \nWhere should build performance be investigated? | \nconsumes trace data and reports it | \n
Create spans around meaningful build phases, plugin work, and I/O boundaries; close them on both success and failure. Trace names should be stable enough for comparison. Do not use traces to hide errors: record/propagate the actual failure according to the caller contract.
\nFor parallel work, the sum of child span durations is cumulative work, not elapsed wall-clock time. A profiler must label or otherwise preserve that distinction so concurrent activity is not misreported as a slow serial path.
\nThe profile report separates plugin-cache activity from persistent-content-cache activity. It reports content-cache hits, misses, and bypasses together with the reason for each miss (for example no-entry or dependency-changed) and each bypass (for example an l10n safe bypass), so a warm build that is not reusing entries can be explained without reading cache internals.
Do not log secrets, raw credentials, or unnecessarily sensitive source content. Keep tracing optional and proportional: instrumentation must not alter build results. Runtime Workers must not depend on mutable build traces or local profiling files.
\nRun riebeckite profile [--full] for CLI-driven reporting. Pair it with Build system and Diagnostics when investigating a problem.
The profile report includes the diagnostics phase: the duration of the diagnostics.run span and the total, error, warning, and info counts emitted when diagnostics are collected. This keeps diagnostic cost and volume visible next to the build phases that produced them.
Observability は、Riebeckite の実行中に 何が起きたのか、どこに時間がかかったのか を調べるための仕組みです。
\nRiebeckite では目的の異なる3つの仕組みを分けています。
\nflowchart LR\n R[\"Riebeckite Build\"]\n \n R --> L[\"Logger\"]\n R --> T[\"Tracer / TraceSink\"]\n \n L --> LO[\"何が起きた？\"]\n T --> SP[\"Timed Spans\"]\n SP --> P[\"Profiler\"]\n P --> PO[\"どこに時間がかかった？\"]| 機能 | \n答える問い | \n主な用途 | \n
|---|---|---|
| Logger | \n何が起きた・失敗したか | \n実行状況やエラーの記録 | \n
Tracer / TraceSink | \n どこで、どれだけ処理したか | \n処理時間を span として記録 | \n
| Profiler | \nBuild のどこを調査すべきか | \nTrace の集計と分析 | \n
たとえば Build が遅い場合、Logger に大量のメッセージを追加して原因を探すのではなく、Tracer で処理時間を記録し、Profiler でその結果を確認します。
\n逆に「Plugin の読み込みに失敗した」のような出来事を伝えるのは Logger の役割です。
\nTrace は、Build の処理を span という単位に分けて処理時間を記録します。
\nたとえば Build が次のように実行されたとします。
\nflowchart TD\n B[\"build\"]\n B --> C[\"content.load\"]\n B --> P[\"plugins.run\"]\n B --> D[\"diagnostics.run\"]\n B --> A[\"application.build\"]\n \n P --> P1[\"plugin A\"]\n P --> P2[\"plugin B\"]build が親 span、その中で実行される処理が child span になります。
これにより、
\n\n\nBuild 全体が遅い
\n
だけではなく、
\n\n\n\n
plugins.runの中の特定 Plugin に時間がかかっている
といったところまで調べられます。
\nすべての関数に span を追加する必要はありません。
\n主に次のような、処理時間を知る意味がある境界へ追加します。
\nspan の名前には、Build 間で比較できる安定した名前を使用します。
\nたとえば、
\ncontent.load\nplugins.run\ndiagnostics.run\napplication.buildのような名前です。
\n入力ファイル名などによって span 名そのものが毎回変化する設計は避けます。
\n処理が成功した場合だけでなく、失敗した場合も span を閉じます。
\nflowchart TD\n A[\"Span 開始\"]\n B[\"処理\"]\n C{\"成功？\"}\n D[\"Span 終了\"]\n E[\"Span 終了\"]\n F[\"結果を返す\"]\n G[\"Error を伝播\"]\n \n A --> B --> C\n C -->|Yes| D --> F\n C -->|No| E --> GTrace はエラー処理の代わりではありません。
\n処理が失敗した場合は Trace を記録したうえで、通常の caller contract に従って error を伝播します。
\nTrace のためにエラーを握りつぶしてはいけません。
\nTrace を読むときは、処理時間の合計と実際の経過時間は同じとは限らないことに注意してください。
\nたとえば Plugin A と Plugin B が並列に実行されたとします。
\ngantt\n title Parallel Plugin Work\n dateFormat X\n axisFormat %L ms\n \n section Plugins\n Plugin A :a, 0, 100\n Plugin B :b, 0, 100それぞれが 100ms かかった場合、
\nPlugin A = 100ms\nPlugin B = 100msなので、処理量としては合計 200ms です。
\nしかし2つは同時に実行されているため、実際の経過時間はおよそ 100ms です。
\nCumulative work = 200ms\nWall-clock time = 約100msProfiler はこの違いを維持します。
\nchild span の時間を単純に足して、
\n\n\nplugins.run = 200ms
\n
のように表示すると、並列処理を直列処理のように見せてしまうためです。
\nProfiler は Trace を集計して、Build のどこに時間がかかっているかを確認するための機能です。
\nCLI から実行できます。
\nriebeckite profileincremental state を再利用せず計測する場合は、
\nriebeckite profile --fullを使用します。
\n--full は、incremental build の影響を避けて Build 全体の performance を調べたい場合に便利です。
Profiler の目的は、
\n「遅い」という事実から、次にどこを調査すればよいかを絞り込むこと
\nです。
\nProfiler は Cache の状況も分けて表示します。
\nこれにより、
\n\n\nなぜ warm build なのにキャッシュが使われていないのか
\n
を、安全性のための bypass なのか、依存関係の変更による miss なのかまで区別して確認できます。
\nDiagnostics も通常の Build phase と同じように計測されます。
\nProfiler には、
\ndiagnostics.runspan の duration が表示されます。
\nさらに Diagnostics が生成した finding の件数も確認できます。
\nこれにより、
\ndiagnostics.run\n├─ duration\n├─ total\n├─ error\n├─ warning\n└─ infoのように、Diagnostics にどれだけ時間がかかり、どれだけの問題が報告されたのかを同時に確認できます。
\nたとえば Diagnostics が Build 時間の大部分を占めている場合、その phase をさらに調査する判断材料になります。
\nObservability は Riebeckite の動作を観測するための仕組みであり、Build の結果を変えてはいけません。
\nInstrumentation を有効にしても無効にしても、生成される Site は同じである必要があります。
\nまた、Logger や Trace には次のような情報を記録しないでください。
\n観測のために必要な情報だけを記録します。
\nTrace や Profile の保存データも Build-time の情報です。
\nCloudflare Workers などの runtime が、書き換え可能な Trace / Profile file に依存する設計にはしません。
\n問題の種類によって使う機能を分けます。
\nflowchart TD\n Q{\"何を調べたい？\"}\n \n Q -->|\"何が起きた？\"| L[\"Logger\"]\n Q -->|\"どこに時間がかかった？\"| P[\"Profiler\"]\n Q -->|\"設定や構成に問題がある？\"| D[\"Diagnostics\"]\n Q -->|\"Build の状態を確認したい\"| B[\"Build System / Inspector\"]Build が失敗している場合は Logger や Diagnostics、Build が遅い場合は Trace / Profiler、incremental build の状態を確認したい場合は Inspector と組み合わせて調査します。
\nBuild の仕組みについては Build System、問題の報告については Diagnostics、現在の state を確認する場合は Inspector を参照してください。
\n","summary":"Observability Observability は、Riebeckite の実行中に 何が起きたのか、どこに時間がかかったのか を調べるための仕組みです。 Riebeckite では目的の異なる3つの仕組みを分けています。 Logger — 何が起きたかを知る Tracer — どの処理にどれだけ時間がかかった","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/page-system","url":"https://riebeckite.dev/en/docs/framework/page-system","title":"page-system.en","content_html":"\n\n The Page System lets a plugin provide a standalone page without taking over an\n application route. It is a capability on the normal RiebeckitePlugin\n contract, not a second kind of plugin.\n
| Layer | \nResponsibility | \n
|---|---|
| Core | \nPage Type contract, validation, path enumeration, resolution, and conflicts | \n
| Plugin | \nPage Type ID, public paths, and a framework-independent HTML body | \n
| HonoX integration | \nGeneric route resolver and SSG parameter helper | \n
| Site application | \nCatch-all route, document frame, metadata, and safe HTML rendering | \n
| Theme | \nTokens and stable hooks; no knowledge of a Page Type ID is required | \n
\n PluginPageContext.manifest is the resolved manifest. Its entries still\n contains draft and scheduled, so a Page Type must read publicEntries\n (routable) or discoverableEntries (public only) for page output instead.\n
Before Page Types, a standalone plugin feature needed a dedicated route:
\nrequest -> plugin-specific application route -> plugin component -> document frameWith the Page System, plugins participate through one generic route:
\nbuild: plugin Page Types -> public paths -> SSG parameters\nrequest: catch-all route -> resolveRiebeckiteRoute\n -> plugin page | content | redirect\nplugin page -> site document frame -> theme CSS and plugin client entries\n The route and frame remain site-owned. Plugins return a body fragment and\n optional title, description, headTags, and language; the site decides how\n those values are represented in the document.\n
\n Use pageTypes when the feature is an independent screen. Use renderers for\n content embeds such as Canvas, Bases, and Excalidraw: they belong inside an\n article and do not need a page of their own.\n
import { definePlugin } from \"@riebeckite/core\";\n \nexport function reportPlugin() {\n return definePlugin({\n name: \"report\",\n pageTypes: [{\n id: \"example.report\",\n paths: [\"/report\"],\n resolve: ({ pathname, manifest }) => pathname === \"/report\"\n ? {\n type: \"example.report\",\n pathname,\n title: \"Report\",\n body: `<p>${manifest.publicEntries.length} published entries</p>`,\n }\n : null,\n }],\n });\n}\n IDs are globally unique. A request with multiple matching Page Types selects\n the greatest priority; equal priorities are an explicit error. Declare\n paths for every static page and derive dynamic paths from\n manifest.publicEntries when SSG must emit them.\n
\n Every HonoX site that uses plugin pages needs the generic catch-all route. The\n scaffolded site already includes it. The root / is resolved by\n resolveRiebeckiteHomeRequest(c, content), which shares the same mechanics:\n
import {\n contentRouteSsgParams,\n resolveRiebeckiteContentRequest,\n riebeckiteSsgParams,\n} from \"@riebeckite/honox/server\";\nimport { PageBody } from \"@riebeckite/honox/ui\";\nimport { createRoute } from \"honox/factory\";\n \nexport default createRoute(\n contentRouteSsgParams(\"/:slug{.+}\", () => riebeckiteSsgParams(content)),\n async (c) => {\n const resolved = await resolveRiebeckiteContentRequest(c, content);\n \n if (resolved.kind === \"response\") return resolved.response;\n \n if (resolved.kind === \"page\") {\n return c.render(<PageBody html={resolved.page.body} />);\n }\n \n return c.render(/* site-specific article composition */);\n },\n);\n Keep the frame's HTML policy at the application boundary. A plugin must only\n return HTML it is responsible for generating; an application must not treat\n untrusted request input as a page body.\n
\n\n For the complete fields and runtime validation rules, see the\n Plugin API.\n
\n","summary":"Page System The Page System lets a plugin provide a standalone page without taking over an application route. It is a capability on the normal RiebeckitePlugin ","tags":[]},{"id":"https://riebeckite.dev/docs/framework/page-system","url":"https://riebeckite.dev/docs/framework/page-system","title":"page-system","content_html":"\nPage System は、Plugin が Site の route を直接追加せずに独立したページを提供するための仕組みです。
\nたとえば Plugin が、
\n/explore\n/report\n/tags/exampleのような独自ページを提供したい場合に使用します。
\nPage System がない場合、Plugin ごとに HonoX の route を Site Application へ追加する必要があります。
\nPage System では Plugin は「この URL に、このページを提供する」という情報だけを公開し、実際の routing や document の描画は Site が担当します。
\nflowchart LR\n Plugin[\"Plugin\"]\n Page[\"Page Type<br/>path + body\"]\n Resolver[\"共通 Route Resolver\"]\n Site[\"Site Application\"]\n Browser[\"Browser\"]\n \n Plugin --> Page\n Page --> Resolver\n Resolver --> Site\n Site --> BrowserpageTypes は通常の RiebeckitePlugin が持つ capability の1つです。
Page 専用の別種類の Plugin を作るわけではありません。
\nPage Type は、Plugin が独立した URL を持つページを提供するときに使用します。
\nたとえば、
\nなどです。
\n一方、記事本文の中へ何かを表示するだけなら Page Type は必要ありません。
\nflowchart TD\n Q{\"Plugin が何を表示する？\"}\n \n Q -->|\"独立したURLを持つページ\"| Page[\"pageTypes\"]\n Q -->|\"記事本文へ埋め込む\"| Renderer[\"renderers\"]\n \n Page --> P1[\"例: /explore\"]\n Page --> P2[\"例: /report\"]\n \n Renderer --> R1[\"Canvas\"]\n Renderer --> R2[\"Bases\"]\n Renderer --> R3[\"Excalidraw\"]Canvas、Bases、Excalidraw のように記事内へ埋め込む機能は renderers を使用します。
Page System では、Plugin がページ全体を所有するわけではありません。
\n責務を次のように分離します。
\n| 層 | \n責務 | \n
|---|---|
| Core | \nPage Type の contract、検証、path 列挙、解決、競合検出 | \n
| Plugin | \nPage Type ID、公開 path、framework 非依存の HTML body | \n
| HonoX Integration | \n共通 route resolver、SSG parameter helper | \n
| Site Application | \nroute、document frame、metadata、HTML の描画 | \n
| Theme | \ntoken と stable hook による見た目 | \n
全体では次のような関係になります。
\nflowchart LR\n Plugin[\"Plugin<br/>Pageを提供\"]\n Core[\"Core<br/>Page contract / resolution\"]\n Integration[\"HonoX Integration<br/>Routing / SSG\"]\n Site[\"Site<br/>Document / Rendering\"]\n Theme[\"Theme<br/>CSS\"]\n \n Plugin --> Core\n Core --> Integration\n Integration --> Site\n Theme --> Siteroute と document frame は Site Application が所有します。
\nPlugin はページの内容を提供しますが、
\n<html>\n<head>\n...\n<body>のような document 全体を生成するわけではありません。
\nPage System 導入前は、独立ページを持つ Plugin ごとに Site 側へ専用 route が必要でした。
\nflowchart LR\n Request[\"Request\"]\n Route[\"Plugin専用Route\"]\n Component[\"Plugin専用Component\"]\n Frame[\"Site Document Frame\"]\n \n Request --> Route\n Route --> Component\n Component --> Frameこの方式では Plugin を追加するだけでは動かず、Site Application の route も変更する必要があります。
\nつまり Plugin と Site の結合が強くなります。
\nPage System では、すべての Plugin Page が共通 route resolver に参加します。
\nflowchart LR\n Request[\"Request\"]\n Catch[\"Catch-all Route\"]\n Resolver[\"resolveRiebeckiteRoute\"]\n Page[\"Plugin Page\"]\n Content[\"Content\"]\n Redirect[\"Redirect\"]\n \n Request --> Catch\n Catch --> Resolver\n \n Resolver --> Page\n Resolver --> Content\n Resolver --> Redirectこれにより、新しい Plugin Page を追加するたびに HonoX route を追加する必要がありません。
\nPage System には、大きく2つの処理があります。
\nBuild 時には、Plugin が提供する Page Type から静的生成する URL を集めます。
\nflowchart LR\n Plugin[\"Plugin Page Type\"]\n Paths[\"Public Paths\"]\n Params[\"SSG Parameters\"]\n Build[\"Static Generation\"]\n \n Plugin --> Paths\n Paths --> Params\n Params --> Buildたとえば Plugin が、
\n/reportを提供していれば、その path を SSG の生成対象にできます。
\nRequest が来ると、共通 resolver がどの種類のページかを判断します。
\nflowchart TD\n Request[\"Request\"]\n Resolver[\"resolveRiebeckiteRoute\"]\n \n Request --> Resolver\n \n Resolver --> Q{\"何が一致した？\"}\n \n Q -->|\"Plugin Page\"| Page[\"Plugin Page\"]\n Q -->|\"Content\"| Content[\"Content\"]\n Q -->|\"Redirect\"| Redirect[\"Redirect\"]\n Q -->|\"なし\"| NotFound[\"Not Found\"]Plugin Page が解決された場合、その body を Site の document frame 内へ描画します。
\nflowchart LR\n Page[\"Plugin Page<br/>body / metadata\"]\n Frame[\"Site Document Frame\"]\n Theme[\"Theme CSS\"]\n Client[\"Plugin Client Entry\"]\n Browser[\"Final Page\"]\n \n Page --> Frame\n Theme --> Frame\n Client --> Frame\n Frame --> BrowserPage Type は Plugin の pageTypes に定義します。
import { definePlugin } from \"@riebeckite/core\";\n \nexport function reportPlugin() {\n return definePlugin({\n name: \"report\",\n \n pageTypes: [\n {\n id: \"example.report\",\n paths: [\"/report\"],\n \n resolve: ({ pathname, manifest }) =>\n pathname === \"/report\"\n ? {\n type: \"example.report\",\n pathname,\n title: \"Report\",\n body: `<p>${manifest.publicEntries.length} published entries</p>`,\n }\n : null,\n },\n ],\n });\n}この例では、
\n/reportというページを Plugin が提供します。
\nページ本文には、到達可能な記事数を表示しています。
\nPlugin が HonoX component や route file を作る必要はありません。
\nPage Type の resolve には PluginPageContext が渡されます。
その中の、
\nPluginPageContext.manifestは解決済みの Manifest です。entries には draft と scheduled も含まれるため、Page の出力には使いません。
到達可能な URL を網羅する場合は publicEntries（public と unlisted）、読者へ一覧として見せる場合は discoverableEntries（public のみ）を使います。entry ごとに分岐が必要な場合だけ、解決済みの entry.publishing を読みます。
flowchart LR\n All[\"All Content\"]\n Publish[\"Publish Boundary\"]\n Public[\"publicEntries / discoverableEntries\"]\n Page[\"Plugin Page\"]\n \n All --> Publish\n Publish --> Public\n Public --> Page非公開コンテンツを Plugin Page 側で独自に探索して表示する設計にはしません。
\nこれによって Page System も通常の Site と同じ公開境界を維持できます。
\n各 Page Type には ID が必要です。
\nid: \"example.report\"Page Type ID は、すべての Plugin を通して一意である必要があります。
\nたとえば、
\nriebeckite.garden-explorer\nexample.report\nexample.searchのように Plugin や用途が分かる namespace を持たせると衝突を避けやすくなります。
\n静的なページは paths に公開 path を指定します。
paths: [\"/report\"]複数のページを提供することもできます。
\npaths: [\n \"/report\",\n \"/report/archive\",\n]動的ページを静的生成する場合は、SSG path を manifest.publicEntries から導出します。
filesystem を独自に scan して path を作るのではなく、Content System が解決した公開状態を利用してください。
\n複数の Page Type が同じ URL に一致する可能性があります。
\nその場合は priority を使って解決します。
flowchart TD\n Path[\"/report\"]\n A[\"Page Type A<br/>priority: 10\"]\n B[\"Page Type B<br/>priority: 20\"]\n \n Path --> A\n Path --> B\n \n A --> Compare{\"priority\"}\n B --> Compare\n \n Compare -->|\"B が高い\"| Result[\"Page Type B\"]最も高い priority を持つ Page Type が選ばれます。
ただし、同じ最大 priority の Page Type が複数一致した場合は、どちらかを暗黙的に選びません。
\nflowchart TD\n Match[\"複数Page Typeが一致\"]\n Priority{\"最大priorityは一意？\"}\n \n Match --> Priority\n \n Priority -->|Yes| Resolve[\"そのPage Typeを使用\"]\n Priority -->|No| Error[\"Conflict Error\"]競合を明示的なエラーにすることで、Plugin の登録順などによって結果が変わることを防ぎます。
\nPlugin Page を利用する HonoX Site には、共通の catch-all route が必要です。
\ncreate-riebeckite などで生成された Site には、必要な構成があらかじめ含まれています。
概念的には次のように接続します。
\nimport {\n contentRouteSsgParams,\n resolveRiebeckiteContentRequest,\n riebeckiteSsgParams,\n} from \"@riebeckite/honox/server\";\nimport { PageBody } from \"@riebeckite/honox/ui\";\nimport { createRoute } from \"honox/factory\";\n \nexport default createRoute(\n contentRouteSsgParams(\"/:slug{.+}\", () => riebeckiteSsgParams(content)),\n async (c) => {\n const resolved = await resolveRiebeckiteContentRequest(c, content);\n \n if (resolved.kind === \"response\") return resolved.response;\n \n if (resolved.kind === \"page\") {\n return c.render(<PageBody html={resolved.page.body} />);\n }\n \n return c.render(/* Site 固有の article composition */);\n },\n);通常の Site 利用者が Plugin ごとにこの route を追加する必要はありません。
\n共通 route が Plugin Page をまとめて解決します。root / も同じ仕組みを共有する resolveRiebeckiteHomeRequest(c, content) が解決します。
Plugin Page は HTML body に加えて、必要に応じてページの metadata を提供できます。
\nたとえば、
\nbody\ntitle\ndescription\nheadTags\nlanguageなどです。
\nただし、Plugin がそれらをどの位置へ描画するかまで決定するわけではありません。
\nflowchart LR\n Plugin[\"Plugin\"]\n \n Plugin --> Body[\"body\"]\n Plugin --> Title[\"title\"]\n Plugin --> Description[\"description\"]\n Plugin --> Head[\"headTags\"]\n Plugin --> Language[\"language\"]\n \n Body --> Site[\"Site Application\"]\n Title --> Site\n Description --> Site\n Head --> Site\n Language --> Site\n \n Site --> Document[\"Final Document\"]Site Application がこれらを受け取り、既存の document frame に反映します。
\nこのため、Plugin Page でも Site 全体の navigation、header、footer、Theme などをそのまま利用できます。
\nPage Type の body は HTML として描画されます。
そのため Plugin は、自分自身が安全に生成できる HTML だけを返す必要があります。
\nたとえば request parameter をそのまま HTML に埋め込むような処理は避けます。
\n// Avoid\nbody: `<p>${untrustedRequestValue}</p>`信頼できない入力を扱う場合は、適切に escape / sanitize してから使用します。
\n最終的に HTML をどのように描画するかは Site Application の boundary で決定します。
\nPage Type が Site の HTML safety policy を回避する仕組みにはしません。
\nTheme は Page Type ID を知る必要がありません。
\nたとえば、
\nexample.report専用の Theme logic を作るのではなく、
\ndata-* attributeを利用して見た目を変更します。
\nflowchart LR\n Page[\"Plugin Page\"]\n Site[\"Site Document\"]\n Hooks[\"Stable Hooks / Tokens\"]\n Theme[\"Theme CSS\"]\n \n Page --> Site\n Site --> Hooks\n Theme --> Hooksこれにより、新しい Page Type が追加されても Theme と Plugin を直接結合せずに済みます。
\nPage System では、Plugin はページを提供するが、Application を所有しないことが最も重要です。
\nflowchart LR\n Plugin[\"Plugin<br/>何を表示する？\"]\n Core[\"Core<br/>どう表現・解決する？\"]\n Integration[\"Integration<br/>どうRouteへ接続する？\"]\n Site[\"Site<br/>どうDocumentとして描画する？\"]\n Theme[\"Theme<br/>どう見せる？\"]\n \n Plugin --> Core\n Core --> Integration\n Integration --> Site\n Theme --> Site責務は次のとおりです。
\nPlugin\n → Page の内容と公開 path を提供する\n \nCore\n → Page Type の共通 contract と解決規則を提供する\n \nHonoX Integration\n → Page Type を routing / SSG へ接続する\n \nSite Application\n → route、document frame、metadata、HTML safety を所有する\n \nTheme\n → Site の見た目を変更するという関係になります。
\nこの境界によって Plugin は HonoX や特定 Site の構造に依存せず、インストールするだけで独立ページを提供できます。
\nPage Type の全フィールドと実行時検証については Plugin API、Site との接続については HonoX Integration を参照してください。
\n","summary":"Page System Page System は、Plugin が Site の route を直接追加せずに独立したページを提供する ための仕組みです。 たとえば Plugin が、 text Wrap Copy /explore /report /tags/example のような独自ページを提供したい場合に使用","tags":[]},{"id":"https://riebeckite.dev/en/docs/framework/plugin-system","url":"https://riebeckite.dev/en/docs/framework/plugin-system","title":"plugin-system.en","content_html":"\nYour First Plugin is a short walkthrough that gets a plugin running. This page is its \"in depth\" companion: it collects everything you refer to while building a plugin — extension points, capabilities, lifecycle, pipelines, and packaging.
\nIf you are new, read your first plugin first, and use this page when you want more detail. For the complete API surface, see Plugin API.
\nA plugin adds features: Markdown/HTML interpretation, reusable content transformation, plugin-specific renderers, reusable browser behavior, plugin-specific diagnostics, and endpoint/SEO extensions.
\nWhat does not go in a plugin:
\nimport { definePlugin } from \"@riebeckite/core\";\n \nexport function examplePlugin() {\n return definePlugin({\n name: \"example\",\n });\n}Give the factory typed options and keep the resolved options in options.
type ExampleOptions = {\n enabled?: boolean;\n};\n \nexport function examplePlugin(options: ExampleOptions = {}) {\n return definePlugin({\n name: \"example\",\n options,\n });\n}Register it in riebeckite.config.ts:
export default defineConfig({\n plugins: [examplePlugin({ enabled: true })],\n});false | null | undefined entries are dropped from the plugin input, and enabled: false is never executed.
plugins: [\n condition && myPlugin(),\n]The current Core contract covers the following areas. You do not implement all of them — use the smallest extension point your plugin needs.
\nUI and output have several extension points, and they are alternatives rather than a progression: Markdown/HTML transformation, renderers, Page Types, body slots, exported Hono JSX components, and client entries. To choose between them, see Providing UI or output.
\n| Area | \nAPI | \n
|---|---|
| Identity | \nname, enabled, order, options | \n
| Dependency | \nprovides, requires, optional | \n
| Validation | \nvalidateOptions | \n
| Cache | \ncacheVersion, context.cache | \n
| Lifecycle | \nsetup, buildStart, buildEnd, dispose | \n
| Content hooks | \nonConfigResolved, onContentLoaded, onPostParsed, onPostProcessed, onManifestCreated | \n
| Public Location | \nresolveContentLocations | \n
| Pipeline | \nremarkPlugins, rehypePlugins, extendMarkdownPipeline, extendHtmlPipeline | \n
| Graph | \nextendContentGraph | \n
| Diagnostics | \naddDiagnostics | \n
| Rendering inside content | \nrenderers | \n
| Standalone pages | \npageTypes | \n
| Browser integration | \nassets, clientEntries | \n
| HTTP integration | \nendpoints | \n
| SEO | \nseo | \n
definePlugin({\n name: \"consumer\",\n provides: [\"example.output\"],\n requires: [\"content.graph\"],\n optional: [\"example.optional\"],\n});provides: capabilities this plugin offersrequires: mandatory capabilitiesoptional: capabilities used when presentThe resolver places providers before consumers. Missing requirements, duplicate providers, and cycles are configuration errors. Unrelated plugins keep their input order as much as possible. order only sets a base ordering before dependency resolution; prefer the capability contract over raw order when dependencies exist.
TypeScript types do not fully guarantee runtime values after the config file executes. Plugins that need it provide validateOptions. A validator must have no side effects — no filesystem scanning, no builds, no cache writes. Return problems as structured issues so config validation can display them together.
type PluginContext = {\n config?: ResolvedRiebeckiteConfig;\n contentIndex: Map<string, string>;\n diagnostics: Diagnostic[];\n cache: PluginCache;\n output: GeneratedOutputSink;\n logger: Logger;\n tracer: Tracer;\n contentSource?: ContentSource;\n};Depending on the hook, slug, markdown, content, manifest, entries, and location input are added. Prefer receiving framework services from the context over creating global singletons.
setup, buildStart, onConfigResolved, content processing, and buildEnd run once per ContentManager. buildEnd receives the completed manifest after diagnostics have been collected and is the only terminal build hook. dispose frees acquired resources and runs in reverse resolved order. Named lifecycle and content hook failures identify the plugin, hook, and original cause. Other hook families follow resolved plugin order.
setup → buildStart → config resolved → public locations resolved\n→ content loaded → Markdown/HTML pipeline → post parsed → post processed\n→ content graph → manifest created → diagnostics → build endUse only the hooks you actually need. Do not reconstruct later-stage information in earlier stages.
\nSimple remark/rehype plugins are declared as arrays.
\ndefinePlugin({\n name: \"example\",\n remarkPlugins: [remarkExample],\n rehypePlugins: [rehypeExample],\n});To compose the pipeline itself:
\ndefinePlugin({\n name: \"example\",\n extendMarkdownPipeline(pipeline, context) {\n pipeline.use(remarkExample);\n },\n extendHtmlPipeline(pipeline) {\n pipeline.use(rehypeExample);\n },\n});Semantic Markdown/HTML transformation belongs in the plugin; do not bring AST processing into application components.
\nextendContentGraph extends the graph before or after construction within the framework contract. For backlinks or graph features, do not rescan the filesystem yourself — use the existing Content Graph / Manifest contract.
resolveContentLocations replaces the public location of content entries. Core first applies the default resolver (resolveDefaultContentLocation: index → /, otherwise /{slug}), then runs each plugin hook in resolved plugin order, and keeps the result as ContentPublicLocation in the manifest / graph / pipeline. URL strategy is the plugin's responsibility. An unresolved location is an explicit error, not a slug fallback.
renderers transform a content target into plugin-specific HTML. The context includes kind, path, raw, label, url, embed, plus the usual PluginContext. Return null when the target is not yours so other renderers are tried.
pageTypes provides an independent screen through the site's generic catch-all route. A type has a globally unique id, static or manifest-derived paths, an optional priority, and resolve. It returns a framework-independent HTML body or null. It may also describe title, description, and headTags; the site document frame renders those values.
Use a Page Type for a page such as a taxonomy listing or explorer. Use a renderer for an article embed such as Canvas, Bases, or Excalidraw. Plugins do not add HonoX route files or own the document frame.
\nPage Type IDs are validated at runtime and must be unique. If more than one type resolves a request, the greatest priority wins; a tie is an error. Use the resolved manifest passed to the resolver, reading manifest.publicEntries or manifest.discoverableEntries rather than manifest.entries. The application wires resolveRiebeckiteRoute and pluginPageSsgParams into its catch-all route; the scaffold does this already. See Page System for the full rendering flow and Plugin API for the contract.
Put plugin stylesheets inside the plugin package and declare the module specifier in assets.
assets: [{\n pluginName: \"example\",\n kind: \"style\",\n moduleSpecifier: \"@riebeckite/plugin-example/style.css\",\n}]Do not copy plugin CSS into apps/web, and never reference /node_modules directly from the browser.
In-site plugins: a plugin does not have to be published. Define it inside the site with definePlugin and pass it to plugins. Resolution order, dependency resolution, pipeline hooks, and diagnostics use the same contract as a package.
// site/extensions/local-plugin.ts\nreturn definePlugin({\n name: \"site-local\",\n assets: [{\n pluginName: \"site-local\",\n kind: \"style\",\n moduleSpecifier: \"/extensions/plugin.css\",\n }],\n});createStyleAsset() and createClientEntry() build @riebeckite/plugin-<name>/... specifiers, so they fit only a package literally named that way. An unpublished plugin, or a published package under any other name, must provide an explicit moduleSpecifier the host bundler can resolve.
Plugin CSS lives in the plugin package and reaches the browser through assets. When a plugin renders an independent, reusable feature, put a stable root hook on the outermost element.
rr-<feature> (rr-search, rr-callout, rr-query, rr-code, …). Below the root, use the BEM shape rr-<feature>, rr-<feature>__element, rr-<feature>--modifier.rr- hooks are additions, so existing selectors and site overrides keep working.rb- namespace. rb-* classes and --rb-* tokens belong to the framework's structural hooks and semantic design tokens. Plugin-specific tokens are --rr-*, with --rb-* as fallback.rr-<feature>__* and rr-<feature>--* are internal implementation details. Document only the descendants you want themes to style.Use clientEntries only when browser initialization is required.
clientEntries: [{\n pluginName: \"example\",\n moduleSpecifier: \"@riebeckite/plugin-example/client\",\n exportName: \"initExample\",\n publicConfig: { selector: \".example\" },\n}]Do not add client JavaScript to plugins that work purely at SSR/build time. publicConfig is passed to the client initializer and recorded in the manifest so static hosts can use it. Plugin options are not passed to the client automatically. Never register tokens, credentials, or private service URLs as public config.
HTTP endpoints use the endpoints contract. Do not embed route-framework implementations in the plugin itself; the integration connects the endpoint contract to the host router. seo lets a plugin participate in SEO processing (metadata/feeds). Do not reimplement plugin-specific SEO logic in application routes.
addDiagnostics(context) {\n return [{\n // follows the Diagnostic contract\n }];\n}Return diagnostics as structured data whenever possible. Use Diagnostics / Logger instead of console.log from the plugin.
context.cache is a build-time cache isolated per plugin.
cacheVersionIt is not Cloudflare Workers persistent storage.
\ncontext.logger.info(\"...\");\nawait context.tracer.span(\"plugin.example.work\", { plugin: \"example\" }, async () => {\n // work\n});The profiler uses structured traces; plugins do not need their own stopwatch/reporting system.
\nUse packages/plugins/backlinks as a template. Recommended layout:
packages/plugins/example/\n├─ index.ts ← factory calling definePlugin, re-exports public parts\n├─ components/ ← components (if any)\n├─ client.ts ← only when needed\n├─ src/\n│ ├─ remark.ts\n│ ├─ rehype.ts\n│ ├─ renderer.ts\n│ └─ types.ts\n├─ style.css ← only when needed\n├─ package.json\n├─ README_ja.md\n└─ README.mdA distributed plugin depends only on @riebeckite/core and declares its own subpaths (./client, ./components, ./style.css) in exports. Never import @riebeckite/core/src/** or reference monorepo paths. For the package surface and current constraints, see \"Public packages and import paths\" in Framework Reference.
Publish built ESM plus type declarations and point exports at the built files; build them in a prepack script so packing and publishing ship fresh output. The repository's build script is not published, so supply a small build: bundle the entry points with esbuild (format: \"esm\", packages: \"external\", external: [\"@riebeckite/*\"]) and emit declarations with tsc --emitDeclarationOnly. See Distributing a Plugin outside this repository for a minimal manifest.
In NodeNext/ESM packages, keep imports resolvable by Node after the build. Do not rely on the development TypeScript loader accidentally resolving extensionless imports.
\nnpm exec riebeckite check # validate config and plugin resolution\nnpm exec riebeckite doctor # health check\nnpm exec riebeckite inspect plugins# list resolved plugins\nnpm exec riebeckite build # confirm it appears in the outputIf a plugin does not resolve, start with check for capability or import errors. Also ask whether you really need a plugin — perhaps configuration or an app implementation suffices.
definePlugin