Theme は、Riebeckite Site の見た目を変更する仕組みです。

Theme を変更すると、

• 色
• フォント
• 文字サイズ
• 余白
• 記事幅
• Sidebar の幅
• Light / Dark Mode
• 記事全体の視覚的な雰囲気

などを変更できます。

flowchart LR
    Content["Markdown"]
    Riebeckite["Riebeckite"]
    Theme["Theme"]
    Site["表示されるSite"]
 
    Content --> Riebeckite
    Riebeckite --> Site
    Theme --> Site

Theme は Content の意味や Site の機能を変更するものではありません。

検索、図表、WikiLink、Analytics などの機能を追加したい場合は Plugins を利用します。

Theme と Plugin の違い

迷った場合は、「見た目を変えたいのか」「機能を追加したいのか」で考えます。

flowchart TD
    Want{"何を変えたい？"}
 
    Want -->|"見た目"| Theme["Theme"]
    Want -->|"機能"| Plugin["Plugin"]

最初から Theme は設定されている

create-riebeckite で生成した Site には、通常すでに Theme が設定されています。

Preset によって既定の Theme が異なります。

そのため、最初から Theme を追加しなくても Site を利用できます。

見た目を変更したくなったときに、別の Theme へ切り替えれば十分です。

Theme を変更する

別の Theme を使う場合は、大きく2つの手順があります。

1. Theme Packageをインストール
 
2. riebeckite.config.tsでThemeを指定

1. Theme をインストールする

たとえば Minimal Theme を利用する場合は、

npm install @riebeckite/theme-minimal

を実行します。

2. Theme を設定する

Theme の Factory を Import し、riebeckite.config.ts の theme に指定します。

import { defineConfig } from "@riebeckite/core";
import { minimalTheme } from "@riebeckite/theme-minimal";
 
export default defineConfig({
  theme: minimalTheme(),
});

これで Site 全体に Minimal Theme が適用されます。

@riebeckite/theme-minimal
        ↓
minimalTheme()
        ↓
riebeckite.config.ts
        ↓
Site

Theme の Option

Theme によっては Option を指定できます。

たとえば Default Theme では、次のように設定できます。

import { defineConfig } from "@riebeckite/core";
import { defaultTheme } from "@riebeckite/theme-default";
 
export default defineConfig({
  theme: defaultTheme({
    colorMode: "system",
    typography: "system",
    articleLayout: "article",
    userCss: ["/extensions/custom.css"],
  }),
});

Theme ごとに利用できる Option は異なる場合があります。

正確な Factory 名と Option は、それぞれの Package README を確認してください。

Color Mode

Theme は共通設定として Color Mode を扱えます。

たとえば、

defaultTheme({
  colorMode: "system",
});

のように指定します。

Riebeckite の Theme Contract では、

light
dark
system

の Color Mode を扱います。

system は Browser / OS 側の設定に合わせるための Mode です。

Color Mode の詳しい Contract は Theme API を参照してください。

Typography

文字の雰囲気も Theme の一部です。

たとえば、

defaultTheme({
  typography: "system",
});

のように設定します。

Theme Contract では Typography Preset として、

system
serif
sans

を扱えます。

実際の Font や細かな Typography は Theme が決定します。

Article Layout

記事部分の Layout も Theme から設定できます。

defaultTheme({
  articleLayout: "article",
});

Theme Contract では、

article
sidebar
full-width

の Layout Preset を扱えます。

Site の用途や記事の種類に合わせて選択できます。

少しだけ見た目を変更する

Theme を丸ごと作るほどではない小さな変更には userCss を利用できます。

defaultTheme({
  userCss: [
    "/extensions/custom.css",
  ],
});

たとえば、

.rb-article {
  font-size: 1.05rem;
}

のような Site 固有の調整を追加できます。

userCss は Theme の Style より後に適用されるため、Site 固有の調整に向いています。

userCss と Theme の使い分け

目安は次のとおりです。

flowchart TD
    Change{"どんな変更？"}
 
    Change -->|"このSiteだけの小さな調整"| CSS["userCss"]
    Change -->|"再利用したいデザイン"| Theme["Theme"]
    Change -->|"新しい機能"| Plugin["Plugin"]

最初は userCss で調整し、変更が大きくなったら Theme として整理する方法もあります。

公式 Theme

Riebeckite には複数の公式 Theme があります。

各 Theme の正確な Export 名と Option は、Package README を参照してください。

Default

Default は、Riebeckite の標準的な Theme です。

import { defaultTheme } from "@riebeckite/theme-default";
 
export default defineConfig({
  theme: defaultTheme(),
});

特定のデザインへ大きく寄せず、Riebeckite Site の出発点として利用できます。

starter と showcase Preset では Default Theme が利用されます。

Minimal

Minimal は、装飾を抑えた Theme です。

import { minimalTheme } from "@riebeckite/theme-minimal";
 
export default defineConfig({
  theme: minimalTheme(),
});

minimal Preset ではこの Theme が利用されます。

Gruvbox

Gruvbox は、Gruvbox をもとにした暖色系の Theme です。

import { gruvboxTheme } from "@riebeckite/theme-gruvbox";
 
export default defineConfig({
  theme: gruvboxTheme(),
});

暖かい色と高いコントラストを持つ配色を利用します。

Rerurate

Rerurate は、Rerurate の視覚文法をもとにした Theme です。

import { rerurateTheme } from "@riebeckite/theme-rerurate";
 
export default defineConfig({
  theme: rerurateTheme(),
});

Sakura

Sakura は、桜をモチーフにした Theme です。

import { sakuraTheme } from "@riebeckite/theme-sakura";
 
export default defineConfig({
  theme: sakuraTheme(),
});

Tokyo Night

Tokyo Night は、Tokyo Night をもとにした暗色系 Theme です。

import { tokyonightTheme } from "@riebeckite/theme-tokyonight";
 
export default defineConfig({
  theme: tokyonightTheme(),
});

Editor のような暗色系の見た目を利用できます。

Theme を切り替える

Theme は riebeckite.config.ts の theme を変更することで切り替えられます。

たとえば Default Theme から Minimal Theme へ変更するなら、

// Before
theme: defaultTheme(),

を、

// After
theme: minimalTheme(),

へ変更します。

もちろん、新しい Theme Package がまだ入っていない場合は先にインストールしてください。

変更後は、

npm exec riebeckite dev

で実際の表示を確認します。

Theme が変更するもの

Theme の責任範囲は Presentation です。

Theme
 
├─ Color
├─ Typography
├─ Spacing
├─ Layout
├─ Design Token
└─ CSS

一方で、

検索機能
Markdown変換
WikiLink
Analytics
新しいPage
Browser上のInteractiveな処理

などは Theme の責任ではありません。

これらには Plugin や Application を利用します。

flowchart TD
    Site["Riebeckite Site"]
 
    Site --> Theme["Theme<br/>見た目"]
    Site --> Plugin["Plugin<br/>機能"]
    Site --> App["Application<br/>Site構成"]
 
    Theme --> CSS["Color / Font / Layout"]
    Plugin --> Feature["Search / Mermaid / Analytics"]
    App --> Page["Route / Navigation / Composition"]

Theme を自作する

既存 Theme の userCss だけでは足りず、再利用できる Design としてまとめたい場合は、自分で Theme を作成できます。

まず Writing a Theme を参照してください。

Themeを使いたい
  → このページ
 
Themeを作りたい
  → Writing a Theme
 
正確なAPIを確認したい
  → Theme API
 
内部の仕組みを知りたい
  → Framework / Theme System

Theme の公開 Contract を確認したい場合は Theme API、Riebeckite 内部で Theme がどのように扱われるか知りたい場合は Framework / Theme System を参照してください。

まとめ

Theme は Riebeckite Site の見た目を担当する仕組みです。

見た目を変える
  → Theme
 
小さなSite固有調整
  → userCss
 
機能を追加する
  → Plugin
 
SiteのPageや構成を作る
  → Application

既存 Theme を使う場合は、

Packageをinstall
      ↓
Factoryをimport
      ↓
config.themeに指定
      ↓
devで確認

という流れになります。

Theme ごとの正確な Factory 名と Option は Package README を確認してください。

次に読むページ

• Writing a Theme — Theme を自作する
• Theme API — Theme の公開 Contract
• Framework / Theme System — Theme の内部設計
• Plugins — Site に機能を追加する