README - k2works/intercept-booster-2-sample GitHub Wiki

Wiki.js と MkDocs 概要

Wiki.jsとは

Wiki.jsは、モダンで強力なオープンソースのWikiソフトウェアです。Node.jsで構築されており、Markdownをはじめとする様々なマークアップ言語をサポートしています。

Wiki.jsの主な特徴

  • モダンなインターフェース: 直感的で使いやすいUIを提供
  • マルチマークアップ言語サポート: Markdown, HTML, AsciiDoc, Wikitext, TXTなど
  • 強力な検索機能: 全文検索とタグベースの検索
  • 多言語対応: 複数言語でのコンテンツ管理
  • 認証と権限管理: 詳細なアクセス制御
  • カスタマイズ可能: テーマやプラグインによる拡張
  • データベース対応: MySQL, PostgreSQL, SQLite, MS SQL Serverなど
  • ストレージ対応: ローカルファイルシステム、Amazon S3、Azure Blob Storage、Google Cloud Storageなど
  • Git同期: GitHubやGitLabとの同期機能

MkDocsとは

MkDocsは、Markdownファイルからプロジェクトドキュメントを生成するための静的サイトジェネレーターです。Pythonで書かれており、シンプルで高速なドキュメント生成を実現します。

MkDocsの主な特徴

  • シンプルな構成: YAMLファイルによる簡単な設定
  • 美しいテーマ: Material for MkDocsなどの高品質なテーマ
  • 検索機能: 組み込みの全文検索
  • プレビュー機能: ライブリロードによる即時プレビュー
  • 拡張性: Pythonによる拡張機能の追加
  • マークダウン拡張: コードハイライト、数式、図表などの拡張機能
  • 多言語対応: 複数言語でのドキュメント作成
  • デプロイ容易性: GitHub Pages、AWS S3などへの簡単なデプロイ

本プロジェクトでのWiki.jsとMkDocsの利用

本プロジェクト「intercept-booster-2-sample」では、Wiki.jsを使用してプロジェクトのドキュメントを管理し、MkDocsを使用してそれらのドキュメントを静的サイトとして公開しています。この組み合わせにより、以下のような利点があります：

  • ダイアグラム埋め込み: PlantUMLやMermaidを使用した図表の埋め込み（Home.mdの例を参照）
  • バージョン管理: Gitを使用したドキュメントのバージョン管理
  • CI/CD連携: GitHub Actionsを使用したドキュメントの自動デプロイ
  • 美しいドキュメントサイト: MkDocsによる見やすく検索しやすいドキュメントサイトの生成
  • 開発環境との統合: Dockerを使用した開発環境でのドキュメント編集と即時プレビュー

GitHub Actionsによる自動デプロイ

本プロジェクトでは、GitHub Actionsを使用してドキュメントを自動的にGitHub Pagesにデプロイしています。このワークフローは以下のステップで構成されています：

  1. リポジトリのチェックアウト: メインリポジトリをチェックアウト
  2. Wikiリポジトリのクローン: Wikiリポジトリをdocs/wikiディレクトリにクローン
  3. Dockerの設定: 必要なDockerサービスの準備
  4. サービスの起動: PlantUMLとMkDocsのサービスを起動
  5. MkDocsサイトのビルド: ドキュメントサイトの生成
  6. ファイルの転送: 生成されたサイトファイルを一時ディレクトリにコピー
  7. GitHub Pagesの設定: デプロイ用の設定
  8. アーティファクトのアップロード: サイトファイルをアーティファクトとしてアップロード
  9. GitHub Pagesへのデプロイ: 生成されたサイトをGitHub Pagesにデプロイ

このワークフローは、メインブランチへのプッシュ時または手動トリガー時に実行され、最新のドキュメントが常にGitHub Pagesで公開されるようになっています。

使用方法

  1. 閲覧:

    • GitHub Pagesでホストされているドキュメントサイトにアクセス
    • ローカル環境で docker-compose up mkdocs を実行し、http://localhost:8000 でアクセス

  2. 編集:

    • GitHub Wiki UIを使用して直接編集
    • ローカルでWiki.jsを実行して編集し、変更をGitHubにプッシュ
    • docs/wiki ディレクトリ内のMarkdownファイルを直接編集

参考リンク