Privacy Workshop (PWS) の公式Webサイトを管理するリポジトリです。 GitHub上でMarkdownファイルを編集するだけでページの作成・更新ができます（ローカルでの作業も可）。 不明点は PWS Slack で質問してください。
| # | セクション | 内容 |
|---|---|---|
| 01 | ページの追加・更新方法 | GitHub上でのページ編集手順 |
| 02 | 新規フォルダの追加方法 | 新年度・新規プロジェクト立ち上げ時の手順 |
| 03 | フォルダ・ファイル構成 | リポジトリの主要ディレクトリ一覧 |
| 04 | ブランチ | ブランチの種類と運用ルール |
| 05 | 技術スタック・アーキテクチャ | ビルド・デプロイを支える技術要素 |
| 06 | Markdown作成Tips | Markdown記述時に知っておくと便利なポイント |
| 07 | 備考 | その他の注意事項 |
| 08 | 困ったときは | 問い合わせ先・参考リンク |
GitHub上でMarkdownファイルを編集・commitするだけでページを更新できます。 まずは全体構成スライドを読んで、サイトの思想と構成を把握してください。
| 手順 | 概要 | 内容 |
|---|---|---|
| 1 | 全体像の把握 | 全体構成スライドを読む（思いと全体構成） |
| 2 | Markdownの編集 | gh-pagesブランチの /202*/markdown/ 等にある .md ファイルをマークダウン形式で編集（新規ページは .md を新規作成） |
| 3 | ビルド完了を待つ | commitすると GitHub Actions が自動でHTML変換を実行する。Actionsタブで全ジョブが完了（緑チェック）になるまで待つ |
| 4 | テスト環境で確認 | テスト環境で見た目を確認。問題があれば再度編集してcommit |
| 5 | 本番へデプロイ | 問題なければ gh-pages → master にマージ。少し待つと本番環境にデプロイされる |
注意事項
| 項目 | 内容 |
|---|---|
| テスト環境の確認 | 必ずテスト環境で表示を確認してからmasterにマージしてください |
| ビルド完了前のマージ禁止 | Actionsタブで全ジョブが完了する前にmasterにマージすると、HTMLが生成されないまま本番に反映されます |
| ビルド状況の確認方法 | リポジトリ上部の Actions タブから実行状況を確認できます |
新年度や新規プロジェクト立ち上げ時を想定した手順です。 GitHub上の操作のみで完結できます（ローカルでの作業も可）。
詳しくは 新規フォルダの作成方法 を参照してください。
リポジトリの主要なディレクトリとその役割です。
コンテンツの編集対象は 2020 以降の年度フォルダと ppsd/ です。
| フォルダ | 管理 | 説明 |
|---|---|---|
2018以前 |
対象外 | PWS2018以前のサイト。gitで管理していませんでした |
2019/ |
対象外 | PWS2019のサイト。htmlファイルを直接編集 |
2020/ 以降 |
管理対象 | PWS各年度のサイト。mdファイルをGitHub上で編集して作成 |
ppsd/ |
管理対象 | データ合成技術評価委員会のサイト。2020以降と同じ運用 |
scripts/ |
管理対象 | 共通ビルドスクリプト（build.py, make.py, create_folder.py） |
tests/ |
管理対象 | テストコード（pytest） |
doc/ |
管理対象 | ドキュメント・タスク管理 |
.github/workflows/ |
管理対象 | GitHub Actionsの設定（管理者向け） |
3種類のブランチを使い分けています。
通常の開発は gh-pages ブランチ、または gh-pages から切り出した feature-* ブランチで行います。
| ブランチ | 用途 | 運用ルール |
|---|---|---|
master |
本番環境へのデプロイ用 | 直接commitしない。gh-pagesの内容をマージして本番に反映する |
gh-pages |
テスト環境での確認・開発用 | メインの開発ブランチ。PRのベースはこちら |
feature-* 等 |
機能開発・修正用 | gh-pagesから切り出して作成し、gh-pagesへPRを出す |
サイトのビルド・デプロイを支える技術要素です。 全体像は全体構成スライドを参照してください。
| 技術 | 用途 | 備考 |
|---|---|---|
| Python 3.9+ | ビルドスクリプト | make.py がエントリーポイント。ローカルビルドは uv run python3 make.py |
| markdown-it-py | Markdown→HTML変換 | GitHub Flavored Markdown (GFM) 互換 |
| uv | 依存管理・実行環境 | uv run でスクリプトを実行 |
| GitHub Actions | CI/CD | convert_markdown.yml でビルド・デプロイを自動化 |
| pytest | テスト | uv run pytest で実行 |
| ruff | リンター/フォーマッター | uv run ruff check . / uv run ruff format . |
pyproject.toml |
ビルド対象定義 | [tool.pwssite] targets でビルド対象フォルダを指定 |
Markdownを書く際に知っておくと便利なポイントです。 HTML変換には markdown-it-py を使用しており、GitHub Flavored Markdown (GFM) 互換です。
| Tips | 説明 |
|---|---|
| GFM対応 | GitHub上のプレビューと同じ見た目でビルドされます。打ち消し線(~~text~~)、タスクリスト(- [ ])、テーブル等が使えます |
| titleタグ | 最初に登場した # ... の文字列がHTMLの <title> タグに採用されます。見つからない場合は "PWS" になります |
| 画像の配置 | markdown/Images/ に配置し、mdファイル内では ./Images/hoge.png の形で参照 |
| マージのタイミング | Actionsタブで全ジョブの完了（緑チェック）を確認してからmasterにマージしてください |
上記セクションに該当しない注意事項です。
| 項目 | 内容 |
|---|---|
| スタイルシート・フッタ | 編集しない想定です（style.css や template 内のフッタ） |
| 大きなデータ | GitHubにはサイズの大きなデータを置けません。Google Driveの公開URL等を利用してください |
不明点や問題があれば以下を参照してください。
| リソース | 説明 |
|---|---|
| PWS Slack | 質問・相談はこちら |
| 全体構成スライド | サイトの思想と全体構成 |
| GitHub Actionsタブ | ビルド・デプロイの実行状況 |
| テスト環境 | gh-pagesブランチの表示確認 |
| 本番環境 | masterブランチのデプロイ先 |