Druxt docs

druxtjs.org

Druxt で構築された Nuxt フロントエンドと Drupal バックエンドです。

このリポジトリは、Druxt のドキュメントサイトである druxtjs.org のソースです。また、Druxt サイトの実際の動作例でもあります。ページは Drupal のコンテンツで、Nuxt によってレンダリングされます。

このサイトは、1 つのリポジトリに 2 つのアプリケーションを収めています。nuxt/ はフロントエンドです。DruxtEntity とそのラッパーコンポーネントを通じて、Druxt でドキュメントをレンダリングします。drupal/ は、編集者がコンテンツを編集する Drupal 11 バックエンドです。

参加する

フロントエンドとバックエンドをまとめて、サイト全体をお使いのマシンで実行します。次の 3 つの方法から選んでください。

方法	必要なもの
Dev container	Dev Containers を備えた VS Code、GitHub Codespaces、または DevPod
mise	mise と 3 つの PHP 拡張機能
手動	PHP 8.3 以降、Composer、Node 16.20.1

Dev container

ツール	方法
VS Code	リポジトリをクローンして開き、コンテナーで再度開くを選択します
GitHub Codespaces	リポジトリのページで Code を開き、Codespaces を選択します
DevPod	バッジをクリックするか、devpod up https://github.com/druxt/druxtjs.org を実行します

コンテナーには Node 16.20.1、PHP 8.4、Composer、mise が含まれています。コンテナーの作成時に npm install と npm run setup が実行されるため、コンテナーを開くと Drupal が起動しています。その後、npm run dev を実行します。

mise

.mise.toml では Node 16.20.1 と PHP 8.4 が固定されています。PHP には gd、pdo_sqlite および sodium 拡張機能が必要です。

mise install
npm install
npm run setup
npm run dev

手動

gd、pdo_sqlite、sodium 拡張機能を含む PHP 8.3 以降、Composer、Node 16.20.1 をインストールします。その後、次を実行します。

npm install
npm run setup
npm run dev

利用できる機能

コマンド	説明
npm install	ルートのツールをインストールし、Git フックを有効にします
npm run setup	一時的な SQLite データベースに Drupal をインストールし、API ページ用に固定バージョンの druxt.js を取得してから、Drupal を起動します
npm run dev	Drupal に接続して Nuxt 開発サーバーを起動します。初回実行時にはフロントエンドのパッケージをインストールします
npm run login	Drupal 用の一度限りのログインリンクを表示します

サービス	アドレス
Drupal	http://127.0.0.1:8888、または次に利用可能なポート。どのポートかは npm run info で確認できます
Nuxt	http://localhost:3000

npm run setup は Drupal のアドレスを .env に書き込み、npm run dev はそこから読み取ります。 セットアップには、Composer パッケージと GitHub 上の固定バージョンのドキュメントを取得するため、ネットワークアクセスが必要です。

ドキュメントを書く

1. npm run login を実行し、表示されたリンクを開きます。
2. Drupal で Content に移動してページを編集するか、新しいページを追加します。レイアウト段落エディターでは、テキスト、コード、画像のセクションを組み合わせてページを作成できます。
3. 保存してから、http://localhost:3000 でページを再読み込みします。

編集フォームの Preview には、未保存の変更が表示されます。 docs/backend.md では、タブについて説明しています。

ここでの編集は、このマシンのデータベースにのみ反映されます。サイトのプレビューやテストには使えますが、ページのテキストを公開する方法ではありません。変更をどこに加えるべきかについては、変更の反映先をご覧ください。

編集者は http://localhost:3000 にサインインして、ページごとの URL で最新の下書きを確認することもできます。 docs/backend.md では、ワークフローとサインインについて説明しています。

Modules、API reference、Components の各ページは druxt.js パッケージから生成されます。npm run docs:generate を実行すると、固定されたバージョンの druxt.js のチェックアウト内でローカルにビルドされます。最初に druxt.js をインストールしてビルドするため、初回の実行には時間がかかります。

変更の反映先

変更内容	反映先
コンテンツモデル、エディター、サイトの設定	drupal/ で vendor/bin/drush config:export を実行してエクスポートし、プルリクエストで drupal/config/sync/ をコミットします
フロントエンド	nuxt/ に変更を加えたプルリクエスト
ページのテキスト	編集者が変更する Drupal。データベースが信頼できる唯一の情報源であり、ページのテキストはまだプルリクエストでは受け付けていません

サイトのコンテンツは本番環境のデータベースに保存されています。ローカルの Drupal にはページがない状態で起動し、そこでの編集はローカル環境にとどまります。

フロントエンドの Druxt

nuxt/ は Druxt で構築された Nuxt 2 アプリで、Druxt サイトの例として読めるように作られています。

内容	方法
ページ	各セクションページは Druxt ルーターでパスを解決し、<DruxtEntity mode="full"> で Drupal のページをレンダリングします。
ラッパー	nuxt/components/druxt/ には、Druxt が名前で検索するラッパーコンポーネントが格納されています。ページは entity/node/DocPageFull.vue で、各段落タイプに対応するコンポーネントが entity/paragraph/ にあります。その他はフィールド（field/）、レイアウトセクション（layout-paragraph/）、ブロック（block/）、ブロック領域（block-region/）、メニュー（menu/）です。
表示設定	druxt-schema はアプリのビルド時に Drupal のビュー表示とフォーム表示を読み込むため、フロントエンドには Drupal で編集者が変更した表示設定が反映されます。
レイアウト	druxt-layout-paragraphs がページのレイアウトセクションをレンダリングします。
ヘッダー、サイドバー、フッター	druxt-blocks が、Drupal の druxtjs テーマの領域に配置されたブロックをレンダリングします。テーマ、サイト名、ロゴは druxtjs_org コンシューマーの分離設定に基づいており、ビルド時に nuxt/modules/decoupled-settings が読み込みます。
UI	nuxt/components/dui/ には、Drupal に依存しない表示用コンポーネント（コードブロック、図、リッチテキスト、カラム）が格納されています。これらは共有 Druxt UI ライブラリに移行する予定です。
プレイグラウンド	nuxt/components/global/DruxtExample.vue は、選択したバックエンド用の独自のランタイム（nuxt/utils/druxt-runtime.js）で任意の Druxt コンポーネントをレンダリングし、各コンポーネントについて把握している情報を nuxt/utils/live-examples.js から取得します。同じカードがモジュールとコンポーネントのリファレンスページに表示されます。

見た目を変更するには、Druxt が検索したラッパー名（Vue devtools で確認できます）を見つけ、一致するパスにコンポーネントを追加します（nuxt/components/druxt/ の下）。命名方法については、コンポーネントの解決を参照してください。

デプロイ

このサイトは Lagoon 上で、Drupal と Nuxt が並ぶ1つの環境として稼働します。Nuxt はまず事前レンダリング済みのページを提供し、保存されていないページや有効期限が過ぎたページはその場でレンダリングします。デプロイ時の処理については docs/hosting.md を参照してください。

コマンド

コマンド	内容
npm run setup	バックエンドをインストールしてから起動します
npm run dev	バックエンドに接続する Nuxt 開発サーバー
npm run storybook	バックエンドに接続するポート 3030 の Storybook
npm run start / stop	Drupal を起動または停止します
npm run info	Drupal の場所と実行中のバージョンを表示します
npm run login	Drupal の一度限りのログインリンクを生成します
npm run docs:generate	Modules、API リファレンス、Components のページをビルドします
npm run lint	prose を除くすべてのリンターを実行します
npm run lint:prose	npm run lint:prose:install を一度実行した後、Vale を実行します
npm test	スクリプトとフロントエンドのモジュールを対象とした Node テスト

貢献

コミットメッセージ、チェック項目、ファイルに決して含めてはいけない内容については、CONTRIBUTING.md をご覧ください。 druxt/druxtjs.org でイシューやプルリクエストを作成してください。 docs/backend.md では、ページの履歴とプレビューについて説明しています。

ライセンス

MIT