個人用ウェブサイトのリポジトリです。
Typst / Tola を使って静的サイトを生成し、GitHub Pages で公開する前提です。
公開中のサイト:
- Typst 0.15.0
- Tola 0.7.1
- just 1.52.0
- Python 3.11+（OG画像のbuild補助。標準ライブラリのみ使用）
- GitHub Pages
OG画像の生成には次の日本語フォントが必要です（リポジトリには同梱しません）。
- Noto Sans JP（第一候補）
- Noto Sans CJK JP（第二候補）
どちらも typst fonts から見つからない場合、just og / just build は明示的に失敗します。
OS標準フォントへはフォールバックしません。
scripts/og_common.py にドキュメント上のツールバージョン（Typst 0.15.0 / Tola 0.7.1）を
記録しています。実際のバージョンと異なる場合、just doctor は mismatch を表示し、
just og / just build は警告を出します（buildは継続します）。
- リポジトリをクローンする。
typst、tola、justをインストールする。- 必要なコマンドが揃っているか確認する。
各コマンドの導入方法は以下を参照する。
typst: https://github.com/typst/typst から 0.15.0 を導入するtola: Rust/Cargo 環境がある場合はcargo install --locked tola --version 0.7.1just: https://just.systems/ から 1.52.0 を導入する
just doctorjust build- サイトをビルドする（出力:
docs/）。 - OG画像の生成 →
docs/images/og/の掃除 →tola build --skip-drafts→docs/.nojekyllの生成 → sitemap修正 → OG/HTML validation →.nojekyll/ CNAMEの確認、までを実行する。
just og- OG画像（
assets/images/og/）だけを再生成する。 - 記事の title / summary / date / tags などを変更した後に実行する。
just validate-og- 生成済み
docs/に対してOG metadataとPNGを検証する（build後のみ）。
just test-og- OGテンプレートのfixtureテスト。一時JSONからPNGを生成し、タイトル折り返し・
タグの省略・長いトークン・オーバーフロー失敗系を検証する。
公開contentや
docs/には書き込まない。
just serve- ローカル開発サーバーを起動する。起動前にdraft込みのOG画像を一度生成する。
just rebuilddocs/と.tola/を削除してから再生成する。
content/posts/*.typ の metadata
↓ Tola 標準の <tola-meta>
tola query（JSON: .og/posts.json）
↓ Python 3 standard library
og/*.typ（Typst, 1200x630, 144 ppi）
↓
assets/images/og/（Git管理しない一時生成物）
↓ Tola の nested assets
docs/images/og/（公開artifact。Git管理する）
↓ GitHub Pages
https://gomazarashi.com/images/og/...
- 記事metadataの single source of truth は
content/posts/*.typ。 - OG画像用にmetadataを別ファイルへ手入力しない。
- 記事metadataの抽出は
tola queryを使用し、独自parserは使わない。 - 記事一覧（
/posts/）とトップの最新記事は@tola/pagesから生成し、 一覧側へtitle / date / summaryを手入力しない。 - HTML側のOGPは
utils/meta.typに集約している。
| 対象 | URL |
|---|---|
| 固定ページ共通 | /images/og/default.png |
| 記事 | /images/og/posts/<source-stem>.png |
<source-stem> は content/posts 配下のsource filenameから拡張子を除いたもの
（例: content/posts/20260412-first-post.typ → 20260412-first-post）。
同一stemが複数ある場合はbuild errorになる。
#show: post.with(
title: "記事タイトル",
summary: "記事の要約（プレーンテキスト）",
date: datetime(year: 2026, month: 4, day: 12),
update: datetime(year: 2026, month: 4, day: 20), // 任意
author: "gomazarashi", // 任意（省略時はsite author）
tags: ("Typst", "Web"), // 任意
aliases: ("/old-url/",), // 任意
)- 公開記事では
title/summary/dateが必須。 date/updateはTypstのdatetime型で指定する（文字列は不可）。- filenameは
yyyymmdd-slug.typ。filenameの日付とdateが一致しない場合はbuild error。 updateがdateより前の場合はbuild error。- 記事OG内の著者は
authorがあればそれを、なければsite.info.authorを使う。
OG画像内のタイトルは実測しながら自動で縮小し、最大4行まで表示する。
それでも収まらない場合はproduction buildが失敗する。
productionを止めたくない場合のみ、短縮用の og-title を指定する。
og-title: "短縮したタイトル",og-title はOG画像とsocial title（og:title / twitter:title）に使われる。
browserの <title> は元のタイトルのまま。
- production build（
just build）はtola build --skip-draftsを使い、 draftのHTMLもOG PNGも公開しない。 just serveはローカル確認用にdraft込みでOGを生成する。- title / tagsなどを変更した場合は
just ogを再実行する。 OG画像のwatchは行わない。
OG画像やmetadataを更新しても、SNS側のcacheが残ることがある。 その場合は各SNSのcache更新（再クロール）を待つか、投稿し直す。
docs/はビルド成果物の出力先。.tola/は Tola の内部作業ディレクトリ。docs/は Git 管理し、just buildで更新してから commit / push する。- GitHub Pages は
Deploy from a branchを選び、公開元をmainブランチの/docsに設定する。 docs/.nojekyllは GitHub Pages の Jekyll 処理を無効化してdocs/.tola/を配信するために必要な空ファイル。just build/just rebuildが生成するため、手動で編集・削除しない。public/は旧ビルド出力先として不要だが、誤生成された場合に備えて引き続き Git 管理しない。.tola/は Git 管理しない運用（.gitignore設定済み）。assets/images/og/と.og/はOG生成用の中間ファイルであり、Git 管理しない。docs/images/og/は公開artifactなので Git 管理する。
mainは公開中の安定版です。mainブランチのdocs/を GitHub Pages から公開します。developは次回公開分を統合・確認するブランチです。- 機能・修正ごとに
developから作業ブランチを作成し、確認後にdevelopへマージします。 - 公開時に
developをmainへマージします。docs/のビルド結果はソース変更とあわせてコミットします。
content/posts/ 配下の記事は、以下の形式で作成する。
yyyymmdd-slug.typ
例: 20260412-first-post.typ