[lexxy] ドキュメントをJekyllサイトに移行

背景

これまでREADMEに全てのドキュメントを集約していたLexxyプロジェクトですが、情報量の増加に伴い、より構造化されたドキュメントサイトへの移行が必要となりました。#558では、Jekyll製の静的サイトジェネレータとJust the Docsテーマを採用し、検索機能を備えた本格的なドキュメントサイトを構築しています。

技術的な変更内容

GitHub Actions による自動デプロイ

新たに.github/workflows/docs.ymlが追加され、GitHub Pagesへの自動デプロイが実現されました。ワークフローは以下の特徴を持ちます：

トリガー条件:

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

docs/ディレクトリまたはワークフローファイル自体の変更時にのみ実行
手動実行（workflow_dispatch）にも対応

ビルドプロセス:

- name: Build with Jekyll
  run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
  env:
    JEKYLL_ENV: production

GitHub Pagesのベースパスを動的に設定することで、サブディレクトリでのホスティングに対応しています。

Jekyll サイトの構成

Gemfile:

source "https://rubygems.org"

gem "jekyll", "~> 4.3"
gem "just-the-docs", "~> 0.10"
gem "webrick" # Required for Ruby 3+

Ruby 3以降では標準ライブラリから外れたwebrickが明示的に追加されています。

設定ファイルの構成:

title: Lexxy
description: A modern rich text editor for Rails
url: "https://basecamp.github.io"
baseurl: "/lexxy"

theme: just-the-docs

# Search
search_enabled: true
search.heading_level: 2
search.previews: 3

検索機能が有効化され、見出しレベル2まで検索対象に含まれます。プレビューは3件まで表示される設定です。

ドキュメント構造の再編成

READMEから447行が削除され、代わりに以下のページ構成に分割されました：

docs/
├── index.md              # ホーム（nav_order: 1）
├── installation.md       # インストール（nav_order: 2）
│   └── css-setup.md     # CSS設定（子ページ）
├── configuration.md      # 設定（nav_order: 3）
│   ├── prompts.md       # プロンプト機能
│   │   ├── inline-attachments.md
│   │   ├── remote-attachments.md
│   │   ├── free-html.md
│   │   ├── remote-filtering.md
│   │   └── options-reference.md
├── events.md            # イベント（nav_order: 4）
└── development.md       # 開発者向け（nav_order: 5）

各ページのフロントマターで階層構造を定義：

---
title: Prompts
layout: default
parent: Configuration
has_children: true
---

新規追加されたドキュメント内容

プロンプト機能の詳細化

docs/prompts/配下に、4種類の実装パターンが詳細に記載されました：

Inline attachments: Action Text添付として保存
Remote attachments: リモートエンドポイントからロード
Free HTML: 編集可能なHTMLとして挿入
Remote filtering: サーバーサイドフィルタリング

各パターンには、モデル定義からビュー、コントローラーまでの完全な実装例が含まれています。

イベントシステムのドキュメント化

docs/events.mdで7種類のカスタムイベントを解説：

// lexxy:insert-link イベントの活用例
editor.addEventListener('lexxy:insert-link', (event) => {
  const { url, replaceLinkWith, insertBelowLink } = event.detail

  // カスタムプレビューでリンクを置換
  replaceLinkWith('<div class="preview">...</div>', { attachment: true })
})

リンク展開機能の実装方法を、Stimulusコントローラーを使った実例で示しています。

開発環境への影響

.gitignoreに以下が追加され、Jekyllのビルド成果物を除外：

# Jekyll docs
/docs/_site/
/docs/.jekyll-cache/
/docs/.jekyll-metadata
/docs/Gemfile.lock

ローカルでのドキュメント開発は以下のコマンドで実行可能：

cd docs
bundle install
bundle exec jekyll serve

サイトは http://localhost:4000/lexxy/ で確認できます。

まとめ

この変更により、Lexxyのドキュメントは単一の巨大なREADMEから、検索可能で構造化されたサイトへと進化しました。Just the Docsテーマの採用により、ナビゲーション、検索、モバイル対応が標準で提供され、ドキュメントの発見性と利用体験が大幅に向上します。GitHub Actionsによる自動デプロイにより、mainブランチへのマージ後、即座にドキュメントが公開される仕組みも整いました。

Primary Source: PR #558
Generated by: Claude Sonnet 4.5 for DiffDaily