Reference

Reference は、Riebeckite の設定値・CLI・公開 API・Theme・内部構造を調べるための章です。

「どう使えばいいか」という手順を知りたい場合は Guides を参照してください。

flowchart TD
    Q{"何を知りたい？"}
 
    Q -->|"使い方・手順"| Guides["Guides"]
    Q -->|"設定・Command・API・Theme"| Reference["Reference"]
    Q -->|"内部構造・仕組み"| Framework["Framework"]

Reference は最初から順番に読む必要はありません。設定項目や API を確認したくなったときに、必要なページを参照してください。

ページ

Configuration

Configuration では、

• site
• content
• markdown
• theme
• plugins
• appRoot
• configRoot
• contentRoot

など、Riebeckite の設定とその解決方法を確認できます。

CLI

CLI では、

init
dev
check
doctor
build
profile
inspect

の各 Command と、その役割を確認できます。

Plugin API

Plugin API では、

• definePlugin
• Lifecycle Hook
• Content Hook
• Renderer
• Page Type
• Assets
• Client Entry
• Endpoint
• Diagnostics

など、Plugin が利用できる Public Contract を確認できます。

Plugin の仕組みそのものを理解したい場合は Plugin System を参照してください。

Theme API

Theme API では、

• defineTheme
• Design Token
• Color Mode
• Typography
• Article Layout
• CSS Contract
• Theme Package

など、Theme が利用できる Public Contract を確認できます。

Theme の設計思想や仕組みを理解したい場合は Theme System を参照してください。

公開 Package

Riebeckite の外部 Plugin / Theme / Site は、公開 Package と公開 Export だけに依存してください。

主な Package は次のとおりです。

依存関係は概ね次のようになります。

flowchart BT
    Site["Site"]
    ExternalPlugin["External Plugin"]
    ExternalTheme["External Theme"]
 
    Honox["@riebeckite/honox"]
    Core["@riebeckite/core"]
 
    Site --> Honox
    Site --> Core
    ExternalPlugin --> Core
    ExternalTheme --> Core
    Honox --> Core

外部 Package から Riebeckite monorepo の内部実装へ直接依存しないことが重要です。

Public API と Internal API

外部 Package では Package の Public Export を利用します。

たとえば、

import {
  definePlugin,
  escapeHtml,
} from "@riebeckite/core";

のように Import します。

一方、次のような Import は使用しないでください。

import {
  something,
} from "@riebeckite/core/src/...";

また、

../../../../packages/core/...

のような Riebeckite monorepo 内部の Path にも依存しません。

flowchart LR
    Consumer["External Package"]
 
    Consumer -->|"✓"| Public["@riebeckite/core<br/>Public Export"]
    Consumer -.->|"✗"| Internal["@riebeckite/core/src/**"]
    Consumer -.->|"✗"| Monorepo["Monorepo Internal Path"]

Public API は外部利用を前提とした Contract です。

src/** や monorepo 内部 Path は実装詳細であり、Package の更新によって変更される可能性があります。

@riebeckite/core

@riebeckite/core は、Riebeckite の Framework 非依存な Public API を提供します。

主な Export は次のとおりです。

Config

defineConfig
resolveConfig
resolveConfigModule
isPublished
isExcluded

Config の宣言、解決、Publication Policy などに使用します。

詳しくは Configuration を参照してください。

Content

ContentManager
ContentCollection
ContentGraph
ContentQuery
buildContentCollections
fingerprintContentEntries
resolveDefaultContentLocation

Content の読み込み、解決、Collection、Graph、Query、Public Location などに使用します。

仕組みについては Content System を参照してください。

Plugins

definePlugin
resolvePlugins
defineEndpoint
createStyleAsset
createClientEntry
appendContentBodySlot
createPluginMemo
stableStringify

Plugin の定義や解決、Endpoint などに使用します。

Plugin を作成する場合は Plugin API と プラグイン作成の詳細 を参照してください。

Themes

defineTheme
RiebeckiteTheme
ThemeDesignTokens
ThemeColorMode
ThemeTypographyPreset
ThemeArticleLayoutPreset

Theme の定義と Presentation Contract に使用します。

Theme を作成する場合は Theme API と テーマ作成の詳細 を参照してください。

Pipeline

Pipeline
MarkdownPipeline
HtmlPipeline

Markdown / HTML の処理 Pipeline を拡張するときに使用します。

通常の Site 利用で直接扱う必要はありません。

Utilities

escapeHtml
escapeHtmlAttribute
normalizeTag
calculateReadingTime
stripHtml

Plugin や Integration から利用できる共通 Utility です。

Observability

Logger
Tracer
TraceSpan
TraceSink

Log や Trace を Framework と統合するための型です。

詳しくは Observability を参照してください。

どのドキュメントを見るべきか

迷った場合は、次の基準で選べます。

flowchart TD
    Start["知りたいこと"]
 
    Start --> Use{"具体的な手順？"}
    Use -->|Yes| Guides["Guides"]
    Use -->|No| API{"設定値やAPIを調べたい？"}
 
    API -->|Yes| Reference["Reference"]
    API -->|No| Internal{"内部の仕組みを知りたい？"}
 
    Internal -->|Yes| Framework["Framework"]
    Internal -->|No| GettingStarted["Getting Started"]

簡単に分けると、

サイトを作り始めたい
  → Getting Started
 
具体的な作業手順を知りたい
  → Guides
 
設定・CLI・APIを調べたい
  → Reference
 
Riebeckiteの内部構造を理解したい
  → Framework

です。

Reference は API の使い方を探すための索引として使い、設計思想や内部実装の説明は Framework、実際の作業手順は Guides と役割を分けています。