アクセシブルな講義ノート（手書き・タイプ原稿から）
成果物は、文書ごとに 1 つの Markdown ファイルと、文書ごとに 1 つの図描画スクリプトです。タグ付き PDF とウェブサイトは、ここにバンドルされたツールキットから生成されます。Markdown が唯一のソースです。修正は .md に行い、生成された .tex や HTML には決して手を加えません。
┌─ mkweb.py → Sphinx + MyST + MathJax → site/
Markdown (*.md) ─────┤
└─ md2tex.py → <class>.cls → lualatex → PDF beside the .md
プロジェクトは次のようになります。
md2tex.py buildtex.py mkweb.py checkweb.py package.py contents.py ビルドスクリプト（プロジェクトルートから実行）
<class>.cls contents.yaml CONVENTIONS.md BUILD.md
src/ 講義: NN_Name.md、NN_Name.tex と .pdf が各ファイルの隣に
2026/ ある年度の宿題と試験、同じ構成
figures/ fig_<doc>_<NN>_<name>.svg、およびそこから作成された PDF
scripts/figures_audit.py
scripts/figures/ figlib.py、make_figures_<doc>.py、データヘルパー
originals/ work/ 原本とページ画像（追跡対象外）
バンドルされているもの
| パス | 用途 |
|---|---|
scripts/init_project.py | 新規プロジェクトをスキャフォールドする、または既存プロジェクトで --update-toolkit を使用 |
scripts/render_pages.py | 原本のページ（および拡大クロップ）をレンダリングして読む |
scripts/contact_sheet.py | 変更された SVG 図を 1 つの PNG にレンダリングして検査・送付する |
scripts/notation_lint.py | 表記の妥協点をフラグ付け：単語内の極限、注釈の説明、平らな下付き文字、数式外の文字、不正な alt ブロック、PDF フォントにないグリフ |
assets/toolkit/ | ビルドスクリプトと notes.cls。init_project.py によってプロジェクトに配置される |
assets/templates/ | contents.yaml、講義と描画スクリプトの例、.gitignore、package.json |
references/transcribing.md | 原本の読み方、OneNote の癖、講義と宿題、引き渡し前のチェック |
references/figures.md | レビューに耐える図の描き方 |
references/notation-pass.md | 既存文書を実際の表記法に修正する（単独または並列ヘルパーと共に） |
references/review-and-delivery.md | レビューラウンド、git、ファイルブリッジの操作、公開 |
references/conventions.md、references/building.md | プロジェクトの CONVENTIONS.md と BUILD.md になる |
0. プロジェクトをセットアップするか見つける
-
既存のプロジェクトを探す:
contents.yaml、md2tex.py、*.cls、CONVENTIONS.md、BUILD.mdがあるか確認します。もしあれば、まずそのCONVENTIONS.mdとBUILD.mdを読み、このスキルと異なる点はそちらに従います。これらは作成者が行った決定を記録しています。プロジェクトの最近のコミットも確認してください。作成者は文書を手作業で修正することが多く、その修正が現在のハウススタイル（フロントマターの文言、クロージングノートに残す内容）です。 -
それ以外の場合はスキャフォールドします:
python3 <skill>/scripts/init_project.py <フォルダ> \ --title "CHEM 101 — General Chemistry" --short "CHEM 101" \ --class chem101 --author "…" --copyright "…"サンプル講義を一度ビルドして、マシンのセットアップを確認します（
BUILD.mdにインストール手順が記載されています）。その後、contents.yaml、src/、scripts/figures/、figures/からサンプルを削除します。 -
推測できないことは1ラウンドで質問します: コース名と短縮コード、どの文書が最初か、原本とプロジェクトの場所（アップロード、作成者のコンピュータ上のフォルダ、git リポジトリ）、各ラウンドで PDF とウェブサイトをビルドするかどうか、誰がプッシュするか。特に指示がない限り、ローカルにコミットし、プッシュはしません。
-
以降のラウンドでは、指示が解除されるまで「スタンディングインストラクション」が保持されます（「ビルドしない」、「自分でプッシュする」など）。
1. 原本を読む
テキスト抽出ではタイプされたテキストのみが取得されます。手書き文字やスケッチはインクとして扱われるため、ページをレンダリングして画像として読み、小さな部分は拡大します。
python3 <skill>/scripts/render_pages.py originals/03.pdf work/03
python3 <skill>/scripts/render_pages.py originals/03.pdf work/03 --zoom 5 0.1 0.2 0.9 0.5
最初の文書の前に references/transcribing.md を読んでください。
2. 書き起こす
プロジェクトの CONVENTIONS.md に従います。最も重要なルールは次のとおりです。
- 保存場所。 講義は
src/NN_Name.mdに、宿題と試験は年度フォルダ（2026/homework03_solution.md）に配置します。それぞれをcontents.yamlにchecked: falseで追加します。作成者だけがtrueに設定でき、これによりウェブサイトに公開されます。 - フロントマター。
title、docheading（唯一の h1）、lang、runningfoot、description（" <トピック> 講義ノート: <トピック>。"）、subtitle（"<コースタイトル>。"）。本文の見出しは##から始め、レベルをスキップしないようにします。「この書き起こしについて」の注釈やページ区切りマーカーは入れません。作成者が削除するため、追加もしません。 - 宿題の解答。 解答のみを書き起こし、
## Problem Nと### Part (a): <何を求めるか>の下に配置します。作成者が問題セット（.tex または .pdf）を提供した場合は、それを解答の理解と表記法のために使用し、変換対象のテキストとしては使用しません。 - 数学: 原本の表記法を正しく組版。 LaTeX は
$…$で、$$…$$は::: eq内で使用します。総和、積、積分は極限を伴います。行列と行列式は組版します。スクリプト文字は\mathcal{}を使用します。ランニングインデックスはイタリック、ラベルは立体にします。真の入れ子下付き文字（x_{j}、x\, jは不可）を使用します。単語は\text{}内に配置します。裸の分数の周りには、描画上の理由がない限り\left(\rightは使用しません。\,は下付き文字リスト内のカンマの後、隣接する分数の間、微分の前でのみ使用します。\underbraceの後に演算子が続く場合は{}を付けます。分数を含む指数には\exp(…)を使用します。 - 手書き注釈は表記法に変換します（
\cancel、\underbrace{…}_{0}、ラベル付きブレース、\overset{…}{=}、\boxed、評価バー）。そのような数式には読み上げ形式を付けます:::: {.eq alt="…"}内にちょうど一つのディスプレイ数式を入れ、マークの名前を平文で記述します（LaTeX 不使用、二重引用符不使用）。通常の数式には alt は不要です: MathJax の MathML により、読者は数式を読み進められます。 - PDF テキストフォントにない記号（⋮、①、π、′、≪、≫）は、数学モードで記述します（
$\vdots$）。丸数字は「状態1」のように記述します。ビルドは欠落文字があると失敗します。 - テーブル: パイプテーブルのみ。ヘッダー行が必要で、罫線はありません。長いテーブルの前には図を配置し、直後に配置しないでください。テーブルはページに収まる幅に保ちます（ビルドは幅が広すぎると警告を出します）。
- ブロック:
::: eq、::: problem、::: keep、::: flush、::: quote、::: note。[H]はありません。 - 原本の誤り はそのまま書き起こし、クロージングノートで証拠と共にフラグを立てます。決して黙って修正しません。作成者が修正を指示した場合は修正します。
- クロージングノート（
## アクセシビリティのための変更に関するノート）には、作成者が確認または決定する必要があるもののみを記述します: 可能性のある誤り、曖昧な読み取り、追加。定型文は不要です。
ビルド前に python3 <skill>/scripts/notation_lint.py <doc>.md を実行します。そのエラーは修正し、警告は原本と照らし合わせて確認する必要があります。
3. すべての図を再描画する
すべてのスケッチは、figlib.py を使用する scripts/figures/make_figures_<doc>.py によって描画された SVG になります。ファイル名は fig_<doc>_<NN>_<name>.svg とします。Markdown からは相対パスで、次のように参照します: {#fig-<doc>-<NN> width=NNN alt="…"}。引用は [](#fig-<doc>-<NN>) で行います。図番号を手作業で記述しないでください。描画する前に references/figures.md を読んでください。 簡単に言うと: 曲線は方程式から計算し、プロット内で中央に配置し、矢印はオブジェクト上で開始・終了し、ラベルは線に近づけかつ明確に配置し（密なプロットでは place_label を使用）、アクセントや丸数字はタイプせずに描画し、viewBox を描画に合わせてサイズ設定し、描画が変更されるたびにキャプションを更新します。
4. ビルドと検証
python3 scripts/figures/make_figures_<NN>.py
python3 md2tex.py <名前> # 例: 09_Mixtures または homework03_solution
python3 buildtex.py <名前> # 12 のチェックと幅広すぎの警告
python3 mkweb.py && python3 checkweb.py # ページごとに 9 つのチェック、MathJax エラーを含む
python3 scripts/figures_audit.py
python3 <skill>/scripts/contact_sheet.py work/sheet.png figures/fig_<doc>_*.svg
- 出力を確認します。 変更されたすべての図のコンタクトシートを表示し、変更された数式、表、図を含む PDF ページをレンダリングします。シートを作成者に送信します。
checked: falseで保留された文書はウェブサイトに表示されません。そのページをテストするには、trueに設定したスクラッチコピーでサイトをビルドします。- チェック 11（「数式代替テキストが生の LaTeX ではない」）は、tagpdf 1.0 より古い TeX Live では失敗します。公開用 PDF を作成するマシンで失敗する場合は、非表示にせずその旨を伝えます。
- 作成者がビルドしないと指示した場合、そのフォルダにビルド出力を書き込みません。リスクのある変更を確認するために、他の場所にスクラッチコピーを作成するのは問題ありません。
- チェックは必要十分条件ではありません。公開前に PDF で PAC 2024 を、サイトで WCAG 監査を推奨します。
5. レビューラウンドと一括修正
references/review-and-delivery.md を読んでください。簡単に言うと: 最初に作成者の現在のファイルと同期し、各箇条書きに対して 1 つのタスクと検証タスクを作成し、各ポイントを原本と相互参照し、質問は編集とは別に回答します（質問の場合は作成者が決定するまで何も変更しません）。プロジェクト全体の規則はツールキットと CONVENTIONS.md で修正し、各項目を 1 行で報告します。
作成者が複数の文書にわたって同じ修正を依頼した場合（例：「05–10 を 01–04 に施した修正に合わせる」）、references/notation-pass.md を読んでください。作成者自身の修正をモデルとして研究し、機械的な部分はスクリプトで行い、数式ごとの作業は並列ヘルパーに、各文書 2〜3 つずつ、書面での指示と共に委任します。
6. 納品
- プロジェクトが作成者のマシン上にある場合は、そのマシン上で編集します。SVG をコピーするのではなく、そこで描画スクリプトを実行して再生成します。ファイルブリッジが転送中に画像を書き換える可能性があるためです。コピーする場合はチェックサムで確認します。
- 作成者自身の ID でコミットし、項目をリストしたメッセージを付けます。依頼がない限りプッシュはせず、プッシュを要求するフックも拒否します。
- 作成者のコンピュータへのリンクが切れた場合は、自分のクローンにコミットし、git バンドル（
git bundle create x.bundle <作成者のHEAD>..main）を渡してプルしてもらうか、リンクが戻ったときに適用します。 python3 package.pyはcontents.yamlからプロジェクト全体のアーカイブをビルドし、scripts/figures_audit.pyが失敗している間は実行を拒否します。- プロジェクトに新しいツールキットを適用するには:
python3 <skill>/scripts/init_project.py <フォルダ> --update-toolkit