ドキュメントサイトの設計方針カスタマイズ性が高く、かつ迅速に構築可能な公式ウェブサイトの設計を目指します。技術ドキュメントのホスティングを主目的としつつ、ブログ機能なども柔軟に組み込めるアーキテクチャを採用します。静的サイトジェネレーターの選定当初はブログプラットフォームとしてVanBlogを検討しましたが、公式サイトの用途には静的サイトジェネレーター（SSG）の方が適していると判断し、以下の候補から評価を行いました。- Jekyll: GitHub Pagesとの統合が容易なブログ向けジェネレーター
- Hugo: Go製の高速なジェネレーターで豊富なテーマが存在
- Hexo: Node.jsベースの強力なフレームワーク
- Docusaurus: Facebook製のドキュメント特化型ツール
- Gatsby: Reactベースのモダンなウェブフレームワーク
- Pelican / MkDocs: Pythonベースのジェネレーター評価の結果、Vueエコシステムの資産を活用でき、技術ドキュメントとの親和性が高いVuePressのV2を採用しました。VuePressの環境構築パッケージのダウンロード速度を向上させるため、npmのレジストリを国内ミラーに設定します。
npm config set proxy_registry https://mirrors.nodejs.jp/プロジェクトの初期化と依存関係のインストールを実行します。npm create vuepress-site doc-project cd doc-project npm install開発サーバーの起動と、本番用ビルドのコマンドは以下の通りです。ビルド成果物はデフォルトで.vuepress/outputに出力されます。npm run dev npm run buildMarkdown拡張機能の導入フローチャートなどの図表を埋め込むため、Mermaidのサポートを追加します。vuepress-markdown-extendプラグインを利用します。npm i vuepress-markdown-extend mermaid設定ファイルにプラグインを登録し、Mermaidを有効化します。``` import { markdownExtendPlugin } from "vuepress-markdown-extend";
export default defineAppConfig({
plugins: [
markdownExtendPlugin({
mermaidChart: true,
}),
],
});
Markdownファイル内で以下のように図表を記述できるようになります。
graph TD
Client -->|Request| RustServer -->|Response| StaticAssets
<h3>ローカル検索エンジンの実装</h3><p>ドキュメント内の検索機能として、`vuepress-local-search-engine`を導入します。</p>8207781131<p>設定ファイルに検索プラグインを追加し、カスタムフィールドのインデックスも定義します。</p>7415679782<h3>共通コンポーネントのインクルード</h3><p>各ドキュメントページで共通するヘッダーやフッターの記述を省略するため、ファイルのインクルード機能を有効にします。</p>7839931540<p>この設定により、Markdown内で次のように外部ファイルを読み込むことが可能になります。</p>1965489525<h3>Rust製サーバーを用いたデプロイ</h3><p>ビルドが完了した静的アセットをホスティングするために、Rustで実装された軽量なプロキシおよび静的ファイルサーバーである`rustwebd`を使用します。まず、Docker環境を構築します。</p>2879692966<p>`rustwebd`のコンテナイメージを取得し、HTTP/HTTPS両方でのリクエスト受付と、カスタム404ページの設定を行うための起動オプションを定義します。
Usage: rustwebd serve-static [--root-dir=ARG] [--host=ARG] [--tls-bind=ARG] [--tls-cert=ARG] [--tls-key=ARG] [--not-found=ARG] ...
Available options:
--root-dir=ARG 静的ファイルのルートディレクトリ
--host=ARG HTTPリスニングアドレス [default: 127.0.0.1:8080]
--tls-bind=ARG HTTPSリスニングアドレス
--tls-cert=ARG TLS証明書パス
--tls-key=ARG TLS秘密鍵パス
--not-found=ARG 404エラー時のフォールバックファイル
Docker Composeを用いて、ビルド成果物とSSL証明書をマウントし、サービスを起動する構成は以下の通りです。
version: '3.8'
services:
web_host:
container_name: rust_web_host
image: rusthub/rustwebd:latest
command:
- sh
- -c
- |
rustwebd serve-static --root-dir /app/public --host 0.0.0.0:80 --tls-bind 0.0.0.0:443 --not-found /app/public/404.html --tls-cert /app/ssl/domain.crt --tls-key /app/ssl/domain.key
ports:
- "80:80"
- "443:443"
volumes:
- ./certs/:/app/ssl:ro
- ./output/:/app/public:ro
networks: default: name: web-net