Document

SK のサイトを作る・直すときの決まりごとです。リポジトリは sy9-k/sk-hub.jp。

はじめに

sk-hub.jp は GitHub Pages で配信する静的なサイトです。サーバーで動く処理は持たず、ログインやデータの保存は Firebase(SK Hub Systems)に任せています。プッシュするとそのまま公開されます。

場所中身
index.htmlトップページ。ほかのページのヘッダー・フッターの型にもなる
_build/ページの元ファイルと build.py。_ で始まるフォルダは公開されない
assets/サイト共通の CSS・スクリプト・翻訳
admin/・develop/サブドメインで開くページ(Worker が中継する)
_workers/Cloudflare Workers のコード

SK Material

SK のアプリ(SK Share・SK Study・この Develop サイトなど)は、マテリアルデザインをもとにした SK Material で作ります。色は CSS のカスタムプロパティ --md-* に集め、明るい・暗いは同じ名前の値を入れ替えるだけで切りかえます。

名前明るい暗い使いどころ
--md-primary#004ac6#b4c5ffボタン・リンク・強調
--md-secondary-container#dce2ff#33467e選んでいる項目・やわらかいボタン
--md-surface#faf8ff#11131bページの背景
--md-surface-container-low#f3f3fe#191b23カード
--md-on-surface#191b23#e1e2ed本文の文字
--md-outline-variant#c3c6d7#434655区切り線
--md-error#ba1a1a#ffb4abエラー

全部の値は view/view.css の先頭にあります。文字は M PLUS 1、アイコンは Material Symbols、動きは cubic-bezier(.2, 0, 0, 1)(--md-emphasized)です。

明るい・暗いの切りかえ

端末の設定(prefers-color-scheme)に従い、人が選んだときだけ data-theme を付けます。この順で書くと、選んだほうがいつも勝ちます。

:root { /* 明るい */ }
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) { /* 暗い */ }
}
:root[data-theme="dark"] { /* 暗い(選んだとき) */ }

多言語

URL は変えず、/lang/ で選んだ言語でページを訳して表示します(assets/i18n.js)。日本語が正式で、日本語の文そのものを翻訳のキーにします。

  • 訳は _build/i18n/<言語>.json(en・zh-CN・zh-TW・ko)。build すると assets/i18n/<言語>.js ができる。
  • 訳のない文は、build が _build/i18n/missing/<言語>.json に書き出す。訳を足してもう一度 build する。
  • スクリプトの中の文は t("…") で包む。build で作らないページは build.py の STANDALONE_PAGES・RUNTIME_SOURCES に入れておく。
  • 日本語と英語だけのページは <html data-i18n-langs="ja en"> にして、英訳を en.json にだけ足す。

ページのビルド

python _build/build.py

トップの index.html の <main id="main"> の外側(<head>・ヘッダー・フッター)を型にして、_build/pages/*.html の中身を差し込み、各ページの index.html と sitemap.xml を書き出します。

書き出された about/index.html などを直接直しても、次の build で上書きされます。直すのは _build/pages/ の元ファイルです。

ページの一覧・タイトル・説明は build.py の pages と EXTRA にあります。SK Share・admin・この Develop サイトのような、独自の見た目のページは build を通さず、そのフォルダのファイルを直接直します。

サブドメインと Worker

admin.sk-hub.jp・support.sk-hub.jp・develop.sk-hub.jp は、Cloudflare Worker が sk-hub.jp(GitHub Pages)の決まったフォルダをそのつど取ってきて返す中継です。ページを直すときは、リポジトリにプッシュするだけで済みます。

開く URL実際のファイル
develop.sk-hub.jp/sk-hub.jp/develop/
develop.sk-hub.jp/docs/sk-hub.jp/develop/docs/
develop.sk-hub.jp/assets/…sk-hub.jp/assets/…(共通の部品はそのままの道筋)
  • Worker のコードは _workers/<名前>/。公開するアドレスは wrangler.jsonc の routes(custom_domain: true)で決める。
  • サイト共通の部品を新しく使うときは、Worker の SHARED に道筋を足して deploy する。
  • 取ってきたものは Cloudflare に 60 秒置く。直してから出るまで最大それだけかかる。
  • 初めて出すときは _workers/develop/ で npx wrangler deploy。DNS は自動で作られる。