仕様書と設計書を改訂

1 files changed, 350 insertions, 1704 deletions

diff --git a/doc/Design.md b/doc/Design.md
index f479e72..a588d39 100644
--- a/doc/Design.md
+++ b/doc/Design.md
@@ -1,1857 +1,503 @@
-# Design.md
+# たかしの記録 — 技術設計書
 
-# たかしの記録 — Zola 基本・詳細設計書
+## 1. 文書の役割
 
-## 1. 文書目的
+本書は、[Specifications.md](Specifications.md)で定義した利用者向け要求を、現在のリポジトリでどのように実現しているかを記録する。
 
-本書は `Specifications.md` の要求を、Zolaによる静的Webサイトとして矛盾なく実装するための基本設計・詳細設計を定義する。
+記載対象は、実装済みの構成、設定、コンテンツモデル、テンプレート、スタイル、クライアント処理、生成物、検証方法である。将来案や完了済みの実装計画は含めない。コードと本書が異なる場合はコードを正とし、本書を同じ変更内で更新する。
 
-設計上の基本原則は次のとおり。
+## 2. システム構成
 
-1. Zola公式のSection / Page / Taxonomy / Tera modelに従う
-2. Zola標準機能を優先する
-3. 外部dependencyを増やさない
-4. Build artifact `public/` のみで本番サイトを成立させる
-5. Client PCでbuildし、VPSでbuildしない
-6. 本番runtimeはCaddyのみ
-7. コンテンツ構造とデザインを不要に複雑化しない
+### 2.1 技術要素
 
----
+| 項目 | 採用内容 |
+|---|---|
+| Static Site Generator | Zola 0.23.3 |
+| Content | Markdown + TOML Front Matter |
+| Template | Tera 2 |
+| Style | SCSSをZolaでコンパイル |
+| Client script | theme切替用のVanilla JavaScript 1ファイル |
+| Syntax highlight | Zola組み込み、class方式、`github-light`／`github-dark` |
+| 配信形式 | 静的なHTML、CSS、JavaScript、XML、SVG、記事asset |
+| 外部theme | 使用しない。`themes/`は空で保持する。 |
+| Node.js／frontend framework | 使用しない |
+| CDN／外部font | 使用しない |
+| Backend／database | 使用しない |
 
-## 2. 参照仕様とZola準拠方針
-
-本設計は `Specifications.md` を上位仕様とする。
-
-実装時は使用するZolaバージョンの公式ドキュメントを確認すること。
-設定キー・front matter・Tera関数を推測して追加してはならない。
-
-主に以下のZola概念を使用する。
-
-- `zola.toml`
-- Section (`_index.md`)
-- Page (`*.md`)
-- Taxonomy
-- Tera templates
-- Sass/SCSS compilation
-- Static assets
-- Colocated assets
-- Built-in feeds
-- Built-in sitemap
-- Built-in robots.txt
-- `page.toc`
-- `get_page`
-- `get_section`
-- `get_url`
-- `get_taxonomy_url`
-- Internal link `@/`
-
-Zolaはディレクトリ構造からSection/Pageを構成するため、独自CMS層やJSON indexを追加しない。
-
----
-
-## 3. システム構成
+### 2.2 生成フロー
 
 ```text
-Client PC
-│
-├── Zola
-├── Git repository
-│   ├── zola.toml
-│   ├── content/
-│   ├── templates/
-│   ├── sass/
-│   └── static/
-│
-├── zola check
-└── zola build
-      │
-      ▼
-    public/
-      │
-      │ archive + SSH
-      ▼
-VPS
-└── /srv/www/takashi-2521.com/
-    ├── releases/<release-id>/
-    └── current -> releases/<release-id>/
-                     │
-                     ▼
-                   Caddy
+content/*.md ─┐
+templates/* ──┼─> Zola ─> public/ ─> 静的配信
+sass/*.scss ──┤
+static/* ─────┘
 ```
 
-ZolaはVPSへインストールしない。
+ZolaがSection、Page、Taxonomyを解決し、TeraでHTMLを生成する。SCSSは`main.css`へコンパイルし、`static/`とPage Bundle内のassetを出力へコピーする。公開環境は`public/`の内容だけで成立する。
 
----
-
-## 4. Zolaサイト構造
+## 3. リポジトリ構造
 
 ```text
-website/
+.
 ├── zola.toml
 ├── content/
 │   ├── _index.md
 │   ├── about.md
 │   ├── notes/
 │   │   ├── _index.md
-│   │   ├── example-note.md
-│   │   └── ...
+│   │   └── <slug>.md
 │   └── software/
 │       ├── _index.md
-│       ├── example-software.md
-│       └── ...
+│       ├── <slug>.md
+│       └── <slug>/
+│           ├── index.md
+│           └── <article-assets>
 ├── templates/
 │   ├── base.html
 │   ├── index.html
 │   ├── page.html
+│   ├── 404.html
 │   ├── notes/
-│   │   ├── section.html
-│   │   └── page.html
 │   ├── software/
-│   │   ├── section.html
-│   │   └── page.html
 │   ├── tags/
-│   │   ├── list.html
-│   │   └── single.html
-│   ├── partials/
-│   │   ├── header.html
-│   │   ├── footer.html
-│   │   ├── note-list-item.html
-│   │   ├── software-list-item.html
-│   │   ├── toc.html
-│   │   ├── related-notes.html
-│   │   └── related-software.html
-│   └── 404.html
+│   └── partials/
 ├── sass/
 │   ├── main.scss
-│   ├── _tokens.scss
-│   ├── _reset.scss
-│   ├── _base.scss
-│   ├── _typography.scss
-│   ├── _layout.scss
-│   ├── _header.scss
-│   ├── _footer.scss
-│   ├── _archive.scss
-│   ├── _article.scss
-│   ├── _software.scss
-│   ├── _taxonomy.scss
-│   ├── _code.scss
-│   ├── _theme.scss
-│   └── _utilities.scss
+│   └── _*.scss
 ├── static/
 │   ├── favicon.svg
-│   └── js/
-│       └── theme.js
+│   └── js/theme.js
+├── doc/
+│   ├── Specifications.md
+│   ├── Design.md
+│   └── content-templates/
+├── draft/
 ├── themes/
-└── public/              # generated; Git ignored
-```
-
-### 4.1 Themes
-
-`themes/` はZola標準ディレクトリとして存在してよいが、空のままとする。
-外部themeを使用しない。
-
-### 4.2 public
-
-`public/` は生成物でありGit管理対象外。
-
----
-
-## 5. `zola.toml` 基本設計
-
-初期値の基準を以下とする。
-
-```toml
-base_url = "https://www.takashi-2521.com"
-title = "たかしの記録"
-description = "日々考えたこととか思ったことを記録します"
-default_language = "ja"
-
-output_dir = "public"
-compile_sass = true
-minify_html = false
-
-generate_feeds = true
-feed_filenames = ["atom.xml", "rss.xml"]
-
-generate_sitemap = true
-generate_robots_txt = true
-
-build_search_index = false
-
-taxonomies = [
-    { name = "tags", feed = false }
-]
-
-[markdown]
-render_emoji = false
-external_links_class = "external-link"
-external_links_target_blank = false
-external_links_no_follow = false
-external_links_no_referrer = false
-external_links_external = true
-smart_punctuation = false
-lazy_async_image = true
-bottom_footnotes = true
-insert_anchor_links = "heading"
-
-[markdown.highlighting]
-error_on_missing_language = true
-style = "class"
-light_theme = "github-light"
-dark_theme = "github-dark"
-
-[link_checker]
-internal_level = "error"
-external_level = "warn"
-
-[slugify]
-paths = "on"
-taxonomies = "on"
-anchors = "on"
-paths_keep_dates = false
-
-[extra]
-home_notes_limit = 5
-home_software_limit = 4
-```
-
-### 5.1 設定上の注意
-
-- `base_url` は本番URLと一致させる。
-- Searchは初期無効。
-- Taxonomyは`tags`のみ。
-- FeedはAtomとRSS。
-- Syntax highlightはclass方式とし、inline styleへの依存を避ける。
-- `external_links_class` を利用し外部リンク記号をCSSで表現する。
-- `minify_html` は開発中false。最終的にtrueへ変更する場合は生成結果を確認してから行う。
-- Highlight themeの具体設定は使用Zola版の公式仕様に合わせる。
-- 利用中Zola版で設定名・構造が異なる場合は、公式ドキュメントを優先してこの設計を等価に実現する。
-
----
-
-## 6. Content model
-
-### 6.1 Root Section
-
-`content/_index.md`
-
-```toml
-+++
-title = "たかしの記録"
-description = "日々考えたこととか思ったことを記録します"
-+++
+└── public/
 ```
 
-Home自体はZolaのroot sectionとして扱い、`templates/index.html` で描画する。
+| ディレクトリ | 管理方針 |
+|---|---|
+| `content/` | 公開対象の原稿だけを置く。 |
+| `draft/` | 非公開原稿を置き、Git管理とZola処理の対象外にする。 |
+| `themes/` | 外部themeを導入せず空で保持する。 |
+| `public/` | ビルド生成物。Git管理対象外とする。 |
 
-### 6.2 About Page
+## 4. Zola設定
 
-`content/about.md`
+設定の完全な値と各項目の説明は`zola.toml`を正とする。本節では、サイト構造に影響する設定をまとめる。
 
-```toml
-+++
-title = "About"
-template = "page.html"
-+++
-```
+### 4.1 サイト設定
 
-本文に以下をMarkdownで記述する。
+| Key | 現在値 | 用途 |
+|---|---|---|
+| `base_url` | `https://www.takashi-2521.com` | canonical URLと絶対URLの基準 |
+| `title` | `たかしの記録` | Header、HTML title、Feed |
+| `description` | サイト説明文 | meta description、About、Feed |
+| `default_language` | `ja` | HTML言語と既定言語 |
+| `output_dir` | `public` | 生成先 |
+| `compile_sass` | `true` | SCSSコンパイル |
+| `minify_html` | `false` | HTMLを可読な状態で出力 |
+| `author` | `Takashi` | PageとFeedの既定author |
+
+### 4.2 配信機能
+
+| Key | 現在値 | 結果 |
+|---|---|---|
+| `generate_feeds` | `true` | サイト全体のFeedを生成 |
+| `feed_filenames` | `atom.xml`, `rss.xml` | AtomとRSSを生成 |
+| `taxonomies` | `tags`, `feed=false` | タグページを生成し、タグ別Feedは生成しない |
+| `build_search_index` | `false` | 検索indexを生成しない |
+| `generate_sitemap` | `true` | `sitemap.xml`を生成 |
+| `generate_robots_txt` | `true` | `robots.txt`を生成 |
 
-- 名前
-- 一言プロフィール
-- サイトの目的
-- 関心分野
-- 連絡先
+Software Pageは`include_in_feeds = false`とし、日付を持っていてもサイトFeedへ含めない。現在のサイトFeedは実質的にNotesを購読対象とする。
 
-構造化metadataを必要以上に増やさない。
+### 4.3 Markdown
 
-### 6.3 Notes Section
+| 設定 | 現在値 | 設計意図 |
+|---|---|---|
+| `bottom_footnotes` | `true` | 脚注を記事末尾へ集約し、本文への戻りリンクを生成 |
+| `insert_anchor_links` | `heading` | 見出し全体をdeep linkにする |
+| `lazy_async_image` | `true` | 画像へ遅延・非同期decode属性を付与 |
+| `external_links_class` | `external-link` | 外部リンクをCSSで識別 |
+| `external_links_external` | `true` | 外部リンクへ`rel="external"`を付与 |
+| `smart_punctuation` | `false` | 原稿の文字を自動置換しない |
 
-`content/notes/_index.md`
+### 4.4 Syntax highlight
 
-```toml
-+++
-title = "Notes"
-sort_by = "date"
-template = "notes/section.html"
-page_template = "notes/page.html"
-+++
-```
+| 設定 | 現在値 |
+|---|---|
+| 出力方式 | `class` |
+| Light theme | `github-light` |
+| Dark theme | `github-dark` |
+| 未対応言語 | エラー |
+| 生成CSS | `giallo-light.css`, `giallo-dark.css` |
 
-#### 6.3.1 Notesのsort
+class方式を使用し、コード色をHTMLのinline styleへ埋め込まない。Light／Dark用CSSは`base.html`から個別に読み込む。
 
-Sectionはdate順にする。
-テンプレートでは新しい順で表示されることを検証する。
+### 4.5 カスタム設定
 
-#### 6.3.2 Notes Page front matter
+`[extra]`はTeraから参照するサイト固有値である。
 
-新規記事用の完全な雛形は`doc/content-templates/note.md`を使用する。
+| Key | 参照先 |
+|---|---|
+| `home_notes_limit` | Homeに表示するNotes件数 |
+| `home_software_limit` | Homeに表示するSoftware件数 |
+| `copyright_year` | Footer |
+| `mail` | AboutとFooter |
+| `cgit` | Software一覧 |
+| `github` | 予約済み。現在のTemplateでは未使用 |
 
-```toml
-+++
-title = "記事タイトル"
-description = "記事の短い説明"
-date = 2026-08-21
-updated = 2026-08-22
+## 5. コンテンツモデル
 
-[taxonomies]
-tags = ["情報工学", "AI"]
+### 5.1 SectionとPage
 
-[extra]
-related_software = [
-    "software/example-software.md"
-]
-+++
+| Source | Zola model | Template | 並び順 |
+|---|---|---|---|
+| `content/_index.md` | Root Section | `index.html` | 各Sectionの設定に従う |
+| `content/about.md` | Page | `page.html` | 対象外 |
+| `content/notes/_index.md` | Section | `notes/section.html` | `date`降順 |
+| `content/notes/*.md` | Page | `notes/page.html` | `date` |
+| `content/software/_index.md` | Section | `software/section.html` | `date`降順 |
+| `content/software/*.md` | Page | `software/page.html` | `date` |
+| `content/software/*/index.md` | Page Bundle | `software/page.html` | `date` |
 
-本文...
-```
+`_index.md`はSection、通常の`.md`と`index.md`はPageとして扱う。Softwareに画像などを併置する場合だけPage Bundleを使用する。
 
-#### 6.3.3 Notes必須/任意項目
+### 5.2 Notes Front Matter
 
-| Field | 必須 | 用途 |
-|---|---:|---|
-| `title` | Yes | タイトル |
-| `date` | Yes | 公開日 |
-| `description` | No | 一覧・meta description |
-| `updated` | No | 更新日 |
-| `taxonomies.tags` | No | 一覧分類 |
-| `extra.related_software` | No | 明示的な関連Software |
-| Body | Yes | 本文 |
+完全な作成用雛形は[content-templates/note.md](content-templates/note.md)に置く。
 
-#### 6.3.4 Slug
+| Field | 型 | 必須 | 利用箇所 |
+|---|---|---:|---|
+| `title` | String | Yes | 一覧、詳細、HTML title |
+| `description` | String | No | 一覧、詳細、meta description |
+| `date` | Date | Yes | 公開日、並び順、年別分類 |
+| `updated` | Date | No | 詳細の更新日 |
+| `taxonomies.tags` | Array[String] | No | 一覧、タグページ |
+| `extra.related_software` | Array[String] | No | 詳細末尾の関連Software |
 
-Markdown filenameを英語ASCII slugとする。
+Markdownファイル名は英語ASCIIのslugとする。表示タイトルは日本語を許可する。
 
-例：
+### 5.3 Software Front Matter
 
-```text
-content/notes/llm-compute-and-energy.md
-```
-
-表示タイトルは日本語でよい。
+完全な作成用雛形は[content-templates/software.md](content-templates/software.md)に置く。
 
-### 6.4 Software Section
+| Field | 型 | 必須 | 利用箇所 |
+|---|---|---:|---|
+| `title` | String | Yes | 一覧、詳細、HTML title |
+| `description` | String | No | 一覧、詳細、meta description |
+| `date` | Date | Yes | 並び順 |
+| `include_in_feeds` | Boolean | Yes | `false`でサイトFeedから除外 |
+| `extra.language` | Array[String] | No | 詳細の使用言語 |
+| `extra.license` | String | No | 詳細のライセンス |
+| `extra.source` | URL String | Yes | cgit正本へのリンク |
+| `extra.github_mirror` | URL String | No | GitHub mirrorへのリンク |
+| `extra.related_notes` | Array[String] | No | 詳細末尾の関連Notes |
 
-`content/software/_index.md`
+本文の章立ては固定しないが、原則として概要、背景、開発の過程を含める。スクリーンショットはPage Bundle内へ置き、相対pathで参照する。
 
-```toml
-+++
-title = "Software"
-sort_by = "date"
-template = "software/section.html"
-page_template = "software/page.html"
-+++
-```
+### 5.4 Aboutとサイト共通値
 
-Software一覧の順序は初期状態ではdate順とする。
-公開日を表示する必要はないが、並び順制御に利用する。
+Aboutは汎用`page.html`を使用する。サイト説明とメールアドレスは本文へ重複記載せず、`config.description`と`config.extra.mail`を参照する。
 
-将来、並びを明示したくなった場合は`weight`へ変更可能。
+### 5.5 関連コンテンツ
 
-#### 6.4.1 Software Page front matter
-
-新規記事用の完全な雛形は`doc/content-templates/software.md`を使用する。
+関連付けはタグから自動推測せず、Front Matterで明示する。
 
 ```toml
-+++
-title = "example-software"
-description = "短い概要"
-date = 2026-08-21
-include_in_feeds = false
-
 [extra]
-language = ["Rust", "HTML"]
-license = "MIT"
-source = "https://git.takashi-2521.com/example-software/"
-github_mirror = "https://github.com/example/example-software"
-related_notes = [
-    "notes/example-note.md"
-]
-+++
-
-## 概要
-
-...
-
-## 作った背景
-
-...
-
-## 開発の過程
-
-...
-```
-
-#### 6.4.2 Software項目
-
-| Field | 必須 | 用途 |
-|---|---:|---|
-| `title` | Yes | PJ名 |
-| `description` | No | 短い概要 |
-| `date` | Yes | 並び順 |
-| `include_in_feeds` | Yes (`false`) | Notes中心のsite feedからSoftwareを除外 |
-| `extra.language` | No | 使用言語 |
-| `extra.license` | No | ライセンス |
-| `extra.source` | Yes | cgit正本 |
-| `extra.github_mirror` | No | GitHub mirror |
-| `extra.related_notes` | No | 関連Note |
-| Body | Yes | 背景・過程・詳細 |
-
-#### 6.4.3 Software image
-
-画像をSoftwareに紐付ける場合、Zolaのcolocated assetを優先する。
-
-例：
-
-```text
-content/software/example-software/
-├── index.md
-└── screenshot.webp
-```
-
-この場合、Page URLは `/software/example-software/` とし、画像を同じPage Bundle内に置く。
-
-画像が不要なSoftwareは単一Markdownでよい。
-
----
-
-## 7. Related content設計
-
-### 7.1 基本方針
-
-関連付けはタグから自動推測せず、front matterで明示する。
-
-理由：
-
-- 意図しない関連付けを防止
-- 記事数が少ないため手動管理コストが低い
-- Zola `get_page` で確実に参照できる
-
-### 7.2 Path形式
-
-`extra.related_software` / `extra.related_notes` には **contentディレクトリからのMarkdown path** を保存する。
-
-例：
-
-```toml
-related_software = ["software/ollama-web.md"]
-related_notes = ["notes/ollama-tool-calling.md"]
-```
-
-### 7.3 Tera resolution
-
-例：
-
-```tera
-{% for path in page.extra.related_notes %}
-  {% set related = get_page(path=path) %}
-  <a href="{{ related.permalink }}">{{ related.title }}</a>
-{% endfor %}
-```
-
-Missing referenceはbuild/checkで検出できるよう、原則 `allow_missing=true` を使用しない。
-
----
-
-## 8. Template設計
-
-### 8.1 `base.html`
-
-責務：
-
-- HTML document skeleton
-- `<html lang="ja">`
-- `<head>`
-- charset / viewport
-- title
-- description
-- canonical
-- RSS/Atom autodiscovery
-- CSS
-- Zola生成syntax-highlight CSS (`giallo-light.css` / `giallo-dark.css`)
-- theme JS
-- Header
-- Main block
-- Footer
-
-概念構造：
-
-```tera
-<!doctype html>
-<html lang="ja">
-<head>
-  ...
-  <link rel="stylesheet" href="{{ get_url(path='main.css') }}">
-  <link id="syntax-light" rel="stylesheet" href="{{ get_url(path='giallo-light.css') }}" media="(prefers-color-scheme: light)">
-  <link id="syntax-dark" rel="stylesheet" href="{{ get_url(path='giallo-dark.css') }}" media="(prefers-color-scheme: dark)">
-  <script src="{{ get_url(path='js/theme.js') }}" defer></script>
-</head>
-<body>
-  {% include "partials/header.html" %}
-  <main id="main-content">
-    {% block content %}{% endblock content %}
-  </main>
-  {% include "partials/footer.html" %}
-</body>
-</html>
-```
-
-#### 8.1.1 Page title
-
-原則：
-
-- Home: `たかしの記録`
-- Other: `<Page title> | たかしの記録`
-
-Tera blockまたは共通変数で実現する。
-
-#### 8.1.2 meta description
-
-優先順位：
-
-1. `page.description` / `section.description`
-2. `config.description`
-
-### 8.2 Header
-
-`partials/header.html`
-
-Desktop:
-
-```text
-たかしの記録        Home  Notes  Software  About  [Theme]
-```
-
-Mobileでは自然にwrapさせ、初期実装ではHamburger menuを導入しない。
-
-サイト名自体はHomeへのリンク。
-
-Navigationには`aria-label="メインナビゲーション"`を設定する。
-
-### 8.3 Footer
-
-`partials/footer.html`
-
-表示：
-
-- `© <year> Takashi`
-- RSS
-- Mail
-
-Mail addressは設定値に直接埋め込むか、`config.extra`へ置く。
-公開時のspam対策を別途必要と判断した場合のみ変更する。
-
-Footerは全Pageで同じ高さ・内側余白を使用する。Bodyを縦Flex layoutとし、短いPageではFooterをviewport下端へ配置する。Page固有の本文高や`main`の固定最小高でFooter位置を調整しない。
-
-### 8.4 Home Template
-
-`templates/index.html`
-
-処理：
-
-1. root `section`
-2. `get_section(path="notes/_index.md")`
-3. Notesから上位5件取得
-4. `get_section(path="software/_index.md")`
-5. Softwareから上位4件取得
-6. Aboutへのリンク
-
-概念：
-
-```tera
-{% set notes = get_section(path="notes/_index.md") %}
-{% set software = get_section(path="software/_index.md") %}
-```
-
-件数は`config.extra.home_notes_limit` / `home_software_limit`で管理する。
-
-Homeでタグは必須表示としない。
-
-### 8.5 Notes一覧 Template
-
-`templates/notes/section.html`
-
-#### 8.5.1 年別グルーピング
-
-Zola公式Archive patternに従い、`section.pages | group_by(attribute="year")` を利用する。
-
-表示：
-
-```text
-Notes
-
-2026
-  08-21  タイトル
-         タグ1 / タグ2
-
-2025
-  ...
-```
-
-ZolaのSection `sort_by = "date"` を前提とする。
-
-#### 8.5.2 Note list item
-
-`partials/note-list-item.html`
-
-- `<article>` または適切なlist item
-- `<time datetime="">`
-- title link
-- tags
-- optional description
-
-タグURLは `get_taxonomy_url(kind="tags", term=...)` を利用する。
-
-### 8.6 Note detail Template
-
-`templates/notes/page.html`
-
-構造：
-
-```text
-article
-├── header
-│   ├── h1
-│   ├── published
-│   └── updated (optional)
-├── TOC
-├── body
-├── related software (optional)
-└── article footer
-```
-
-#### 8.6.1 Tags
-
-仕様に従い、本文詳細ではタグ一覧を主要表示しない。
-
-#### 8.6.2 TOC
-
-`page.toc` を使用する。
-
-- `page.toc` が空なら非表示
-- Sidebar化しない
-- 記事headerと本文の間に置く
-- H2/H3等の階層を維持
-- Recursive Tera partial/componentで描画可能
-
-#### 8.6.3 TOC accessibility
-
-- `<nav aria-label="目次">`
-- 見出し「目次」
-- ordered/unordered list
-- Anchorは`header.permalink`
-
-#### 8.6.4 Date
-
-公開：
-
-```html
-<time datetime="2026-08-21">2026-08-21</time>
+related_software = ["software/example/index.md"]
+related_notes = ["notes/example.md"]
 ```
 
-更新日がある場合だけ表示。
-
-#### 8.6.5 Footnotes
+pathは`content/`を基準にしたMarkdown pathとする。Partial内で`get_page(path=path)`を使用するため、対象を削除すると`zola check`が失敗する。記事削除時は相互参照と本文中の内部リンクも同時に削除する。
 
-Zola Markdown rendererが生成するfootnote markupへSCSSを適用する。
+## 6. URLと生成物
 
-独自脚注システムを作らない。
+### 6.1 Page URL
 
-#### 8.6.6 References
+| 種別 | URL |
+|---|---|
+| Home | `/` |
+| About | `/about/` |
+| Notes一覧 | `/notes/` |
+| Note詳細 | `/notes/<slug>/` |
+| Software一覧 | `/software/` |
+| Software詳細 | `/software/<slug>/` |
+| タグ一覧 | `/tags/`（タグ使用時） |
+| タグ別一覧 | `/tags/<term-slug>/`（タグ使用時） |
+| 404 | `/404.html` |
 
-Markdown本文の通常Headingとして「参考文献」を記述する。
+`slugify.paths`、`slugify.taxonomies`、`slugify.anchors`は`on`とする。Markdown内の内部リンクは`@/`記法、Tera内は`get_url(path="@/...")`を使用し、`base_url`や配置変更へ追従させる。
 
-例：
-
-```markdown
-## 参考文献
-
-1. ...
-2. ...
-```
+### 6.2 サイト共通出力
 
-専用front matter schemaは導入しない。
+| 出力 | 生成元 |
+|---|---|
+| `main.css` | `sass/main.scss` |
+| `giallo-light.css` | Zola syntax highlight |
+| `giallo-dark.css` | Zola syntax highlight |
+| `js/theme.js` | `static/js/theme.js` |
+| `favicon.svg` | `static/favicon.svg` |
+| `atom.xml` | Zola built-in Feed template |
+| `rss.xml` | Zola built-in Feed template |
+| `sitemap.xml` | Zola built-in sitemap template |
+| `robots.txt` | Zola built-in robots template |
 
-### 8.7 Software一覧 Template
+## 7. Template設計
 
-`templates/software/section.html`
-
-表示の中心はSoftware名。
-
-例：
+### 7.1 継承構造
 
 ```text
-Software
-
-ollama-web
-短い説明（存在する場合）
-
-winagent-sandbox-mcp
-...
-```
-
-一覧には以下を表示しない。
-
-- screenshot
-- license
-- source URL全文
-- language一覧
-- 大量のbadge
-
-### 8.8 Software detail Template
-
-`templates/software/page.html`
-
-構造：
-
-```text
-article
-├── h1 Software名
-├── description
-├── metadata
-│   ├── 使用言語
-│   ├── ライセンス
-│   ├── Source
-│   └── GitHub mirror (optional)
-├── Body
-│   ├── 概要
-│   ├── 背景
-│   └── 過程等
-├── screenshot/assets (optional)
-└── Related Notes (optional)
-```
-
-SourceはGitHubより先に表示。
-
-外部リンクclassによって`↗`表示を適用する。
-
-### 8.9 About
-
-標準`page.html`で十分な場合は専用templateを作らない。
-
-`page.html` は汎用Editorial pageとして以下を描画。
-
-- h1
-- page.content
-
-About固有レイアウトが必要になった時だけ`about.html`を追加する。
-
-### 8.10 Taxonomy templates
-
-`tags/list.html`
-
-- 全タグの一覧
-- term name
-- article count
-
-`tags/single.html`
-
-- タグ名
-- 該当Pages一覧
-- Note/Softwareの混在が読みづらい場合は種類ごとに分離可能
-
-初期仕様ではタグは主にNotes用だが、Zola taxonomy自体はPages全般で利用可能。
-
-### 8.11 404
-
-`templates/404.html`
-
-- base designと同じHeader/Footer
-- 「ページが見つかりません」
-- Homeへのリンク
-- Notesへのリンク
-- Softwareへのリンク
-
-外部依存なし。
-
----
-
-## 9. Internal Link設計
-
-Markdown本文内の内部リンクはZolaの `@/` syntaxを使用する。
-
-例：
-
-```markdown
-[関連する記事](@/notes/example-note.md)
-```
-
-Template内は`get_url`, `get_page`, `get_section`を使用する。
-
-Content pathを手書きURLへ変換しない。
-
-Broken internal linkは`zola check`でerror扱い。
-
----
-
-## 10. Tags / Taxonomy設計
-
-`zola.toml`:
-
-```toml
-taxonomies = [
-    { name = "tags", feed = false }
-]
-```
-
-Page:
-
-```toml
-[taxonomies]
-tags = ["情報工学", "地球環境"]
-```
-
-### 10.1 Tag URL
-
-Zola slugificationに任せる。
-
-表示termは日本語を許容する。
-Taxonomy URL生成はZola APIを使用し、自前slug生成をしない。
-
-### 10.2 Category
-
-初期実装ではcategory taxonomyを作らない。
-
----
-
-## 11. Feed設計
-
-Site-level feed:
-
-- `/atom.xml`
-- `/rss.xml`
-
-Site-level feedを使用する。Software Pageには `include_in_feeds = false` を設定し、日付を持つSoftwareがsite feedへ混入しないようにする。これにより初期feedは実質的にNotesを購読対象とする。
-
-Notes section固有feedは初期実装では生成しない。必要になった場合のみ `content/notes/_index.md` の `generate_feeds = true` を追加する。
-
-`base.html`にautodiscoveryを設定。
-
-概念：
-
-```tera
-<link rel="alternate"
-      type="application/atom+xml"
-      title="Atom"
-      href="{{ get_url(path='atom.xml', trailing_slash=false) }}">
-<link rel="alternate"
-      type="application/rss+xml"
-      title="RSS"
-      href="{{ get_url(path='rss.xml', trailing_slash=false) }}">
-```
-
-FooterのRSSリンクは`rss.xml`を優先してよい。
-Atomもアクセス可能とする。
-
----
-
-## 12. Sitemap / robots
-
-Zola built-in生成を利用する。
-
-```toml
-generate_sitemap = true
-generate_robots_txt = true
-```
-
-独自generatorを作らない。
-
-robots policyを変更する必要が生じた場合のみbuilt-in template overrideまたはstatic fileを検討する。
-
----
-
-## 13. Sass設計
-
-### 13.1 基本原則
-
-- 自前SCSS
-- CSS frameworkなし
-- Tailwindなし
-- external reset packageなし
-- BEM等の厳格な命名体系を強制しない
-- component responsibilityが分かる程度のclass設計
-
-### 13.2 Design tokens
-
-`_tokens.scss`
-
-初期候補：
-
-```scss
-:root {
-  --color-bg: #f6f5f1;
-  --color-surface: #fbfaf7;
-  --color-text: #202124;
-  --color-muted: #6d7177;
-  --color-border: #d6d8da;
-  --color-link: #315f82;
-  --color-link-hover: #244a67;
-
-  --font-sans:
-    system-ui, -apple-system, BlinkMacSystemFont,
-    "Segoe UI", "Noto Sans JP", sans-serif;
-
-  --font-mono:
-    ui-monospace, "Cascadia Code", "SFMono-Regular",
-    Consolas, "Liberation Mono", monospace;
-
-  --content-max: 72ch;
-  --site-max: 72rem;
-}
-```
-
-具体色は実装時に視認性を確認して調整可能。
-Accentは青系から逸脱しない。
-
-### 13.3 Dark tokens
-
-```scss
-@media (prefers-color-scheme: dark) {
-  :root:not([data-theme="light"]) {
-    --color-bg: #17191b;
-    --color-surface: #1d2022;
-    --color-text: #e9e9e6;
-    --color-muted: #a0a3a6;
-    --color-border: #363a3e;
-    --color-link: #86b6d8;
-    --color-link-hover: #add3ed;
-  }
-}
-```
-
-User override用`data-theme`も定義する。
-
----
-
-## 14. Theme switch設計
-
-### 14.1 初期状態
-
-CSS `prefers-color-scheme` を優先。
-
-### 14.2 手動切替
-
-`static/js/theme.js` のみを使用。
-
-責務：
-
-- 現在theme取得
-- light/dark切替
-- `document.documentElement.dataset.theme`
-- `localStorage`保存
-- toggle buttonの`aria-pressed`/label更新
-- `#syntax-light` / `#syntax-dark` の `media` を切り替え、本文themeとsyntax highlighting themeを同期
-
-明示的にLightを選んだ場合：
-
-- `syntax-light.media = "all"`
-- `syntax-dark.media = "not all"`
-
-明示的にDarkを選んだ場合：
-
-- `syntax-light.media = "not all"`
-- `syntax-dark.media = "all"`
-
-保存themeがない場合はHTML/CSSとも `prefers-color-scheme` に従う。
-
-### 14.3 CSP
-
-JSは外部fileのみ。
-Inline scriptは使用しない。
-
-Theme JSが失敗してもOS themeにより読みやすい状態を保つ。
-
-### 14.4 No-JS
-
-No-JSではmanual toggleだけ利用不可。
-本文・navigation・Light/Dark OS preferenceは利用可能。
-
----
-
-## 15. External link表示
-
-Zola Markdown設定：
-
-```toml
-external_links_class = "external-link"
-```
-
-SCSS：
-
-```scss
-.external-link::after {
-  content: " ↗";
-  font-size: 0.8em;
-  text-decoration: none;
-}
-```
-
-装飾SVG dependencyを使用しない。
-
-Navigationや内部リンクには付けない。
-
----
-
-## 16. Layout設計
-
-### 16.1 Site container
-
-```scss
-.site-container {
-  width: min(100% - 2rem, var(--site-max));
-  margin-inline: auto;
-}
-```
-
-### 16.2 Article
-
-初期値：
-
-```scss
-.prose {
-  max-width: var(--content-max); // 72ch
-  margin-inline: auto;
-}
-```
-
-仕様で本文幅は未確定だったため、初期実装は **72ch** とする。
-実際の日本語可読性を確認し、65〜75ch相当の範囲で調整可能。
-
-### 16.3 Mobile
-
-- Side padding最低1rem
-- Header navigation wrap可
-- Horizontal body scroll禁止
-- pre/code/tableは必要に応じ内部scroll
-- 画像max-width:100%
-
----
-
-## 17. Typography設計
-
-### 17.1 Body
-
-Sans-serif system stack。
-
-```scss
-body {
-  font-family: var(--font-sans);
-  line-height: 1.75;
-}
-```
-
-### 17.2 Heading
-
-Sans-serif。
-過度な巨大見出しにしない。
-Pageタイトルは本文を圧迫しない控えめな大きさとする。HomeのH1はheading hierarchy維持のため視覚的に非表示とし、サイト名はHeaderだけに表示する。
-
-### 17.3 Metadata
-
-Monospaceまたは小さめSans。
-日付などにMonoを利用。
-
-### 17.4 Code
-
-`var(--font-mono)`。
-
----
-
-## 18. Editorial visual rules
-
-- Border radius最小限
-- Card shadow原則なし
-- Gradientなし
-- Neon/glowなし
-- Glassmorphismなし
-- 1px ruleを主要区切りに使用
-- Section間余白でhierarchyを作る
-- 大きなHero画像なし
-- Iconsは最小限
-- Badge乱用なし
-
----
-
-## 19. Code block設計
-
-Zola syntax highlightingを利用。
-
-- Client-side highlighting libraryなし
-- Prism/highlight.jsなし
-- class-based highlight
-- `github-light` / `github-dark` のdual theme
-- Zola生成 `giallo-light.css` / `giallo-dark.css` を読み込む
-- theme toggle時にstylesheet mediaも同期する
-- code blockは横scroll可
-- light/darkの視認性を確認
-
-Highlight CSSの生成/適用方法は使用Zola versionの公式仕様に従う。
-
----
-
-## 20. Image設計
-
-### 20.1 Notes
-
-Markdown imageを使用。
-
-`lazy_async_image = true` により遅延loadを利用する。
-
-Altはplain textで記述。
-
-### 20.2 Software
-
-Colocated assetを推奨。
-
-Screenshotは本文内で説明と一緒に表示。
-
-### 20.3 Formats
-
-原則：
-
-- SVG: icon/diagram
-- WebP/AVIF/JPEG/PNG: screenshot用途に応じて選択
-
-画像最適化toolchainは初期実装に追加しない。
-
----
-
-## 21. Accessibility設計
-
-### 21.1 Landmarks
-
-- `<header>`
-- `<nav>`
-- `<main>`
-- `<article>`
-- `<footer>`
-
-### 21.2 Skip link
-
-Header先頭にskip linkを設けることを推奨。
-
-```html
-<a class="skip-link" href="#main-content">本文へ移動</a>
-```
-
-### 21.3 Focus
-
-`:focus-visible`を明確に表示。
-
-### 21.4 Color
-
-リンクは青色だけでなく下線でも識別可能にする。
-
-### 21.5 Theme toggle
-
-Button要素を使用。
-Keyboard操作可能。
-
-### 21.6 TOC
-
-`nav aria-label="目次"`。
-
----
-
-## 22. SEO / metadata設計
-
-最低限：
-
-- `<title>`
-- `<meta name="description">`
-- canonical URL
-- `lang="ja"`
-- RSS/Atom autodiscovery
-- sitemap
-- robots
-
-Open Graph / Twitter Cardは初期必須ではない。
-外部依存なしで容易に実装可能な場合は後で追加可。
-
----
-
-## 23. SNS共有
-
-初期実装対象外。
-
-理由：
-
-- 仕様が条件付き
-- Editorial designを優先
-- Mastodon等は単一固定share endpointにしづらい
-- 外部service/仕様変化への依存を避ける
-
-将来追加する場合、以下の順で検討。
-
-1. Web Share API
-2. Copy link
-3. 外部dependencyなしのSNS share URL
-
----
-
-## 24. Comments
-
-初期実装対象外。
-
-Template上に空のcomment UIや未使用placeholderを作らない。
-
-将来commentsを採用する場合は別設計として以下を再評価。
-
-- Data persistence
-- Authentication/abuse
-- Spam
-- Moderation
-- Privacy
-- CSP
-- Backup
-- VPS resource
-- External service dependency
-
----
-
-## 25. Search
-
-初期：
-
-```toml
-build_search_index = false
-```
-
-Search UIを作らない。
-
-将来追加時はZola built-in search indexを第一候補とし、日本語indexing対応について使用Zola binaryの機能を確認する。
-
----
-
-## 26. Git設計
-
-Git管理対象：
-
-- `zola.toml`
-- `content/`
-- `templates/`
-- `sass/`
-- `static/`
-- documentation
-- deploy script（別Phaseで追加）
-
-`.gitignore`：
-
-```gitignore
-/public/
-```
-
-Editor/OS生成物は必要に応じ追加。
-
-`themes/` が空でGitに残らない場合、`.gitkeep`は必須ではない。
-
----
-
-## 27. Build設計
-
-### 27.1 Development
-
-```bash
-zola serve
-```
-
-### 27.2 Validation
-
-```bash
-zola check
-```
-
-### 27.3 Production build
-
-```bash
-zola build
-```
-
-Build成功後、`public/`が自己完結していること。
-
-### 27.4 Build Gate
-
-以下のいずれかで失敗したらDeploy不可。
-
-- `zola check` failure
-- `zola build` failure
-- broken internal link
-- required related content path missing
-- missing required template
-- missing syntax language when error_on_missing_language=true
-
----
-
-## 28. Deployment interface
-
-Deployment詳細は別Phaseだが、Client siteは以下の契約を満たす。
-
-Input:
-
-```text
-source repository
-```
-
-Build output:
-
-```text
-public/
-```
-
-Deploy sideは`public/`の中身をrelease rootへ展開する。
-
-最終URL rootに余計な`public/` directory layerを作らない。
-
-例：
-
-```text
-release/
+base.html
 ├── index.html
-├── notes/
-├── software/
-├── tags/
-├── main.css
-└── ...
+├── page.html
+├── 404.html
+├── notes/section.html
+├── notes/page.html
+├── software/section.html
+├── software/page.html
+├── tags/list.html
+└── tags/single.html
 ```
 
----
-
-## 29. Caddy互換性
+`base.html`は文書骨格、metadata、共通CSS／JavaScript、Header、Footer、`main`を提供する。各ページは`title`、`description`、`content` blockを上書きする。
 
-既存Caddy:
-
-```text
-root * /srv/www/takashi-2521.com/current
-file_server
-```
+### 7.2 共通部品
 
-Zola outputはCaddy static file serverだけで利用できること。
+| Partial | 役割 |
+|---|---|
+| `partials/header.html` | サイト名、Home／Notes／Software／About、theme切替 |
+| `partials/footer.html` | copyright、Atom、RSS、Mail |
+| `partials/note-list-item.html` | Noteの日付、タイトル、説明、タグ |
+| `partials/software-list-item.html` | Software名と説明 |
+| `partials/related-notes.html` | Softwareから関連Notesを解決 |
+| `partials/related-software.html` | Noteから関連Softwareを解決 |
+| `partials/toc.html` | Zolaの階層化された目次を再帰描画 |
 
-以下を要求しない。
+### 7.3 Metadata
 
-- rewrite application router
-- server-side include
-- PHP
-- CGI
-- Node
-- Python backend
+`base.html`は全ページへ次を出力する。
 
-404 handlingがCaddyで専用設定を必要とする場合は、Deploy統合Phaseで既存Caddy設定との整合を確認する。
-
----
-
-## 30. CSP compatibility
-
-目標CSP：
-
-```text
-default-src 'self';
-script-src 'self';
-style-src 'self';
-img-src 'self' data:;
-font-src 'self';
-object-src 'none';
-base-uri 'self';
-frame-ancestors 'none';
-```
-
-実装規則：
-
-- Inline JSなし
-- Inline event handlerなし
-- External fontなし
-- External CSSなし
-- External JSなし
-- Evalなし
-- CSS assetはself
-- imageはself/data中心
-
-Syntax highlightがinline styleを生成しないclass modeを優先。
-
----
-
-## 31. Error handling
-
-Static siteのためruntime error UIは不要。
-
-Build-timeに可能な限り失敗を検知する。
-
-- Broken internal links: error
-- Related page missing: Tera error
-- Missing templates: build error
-- Invalid front matter: build error
+- UTF-8とresponsive viewport
+- `lang="ja"`
+- ページ固有またはサイト共通のdescription
+- ページ固有のtitle
+- canonical URL
+- SVG favicon
+- Atom／RSS autodiscovery
+- Light／Dark syntax CSS
+- `main.css`と`theme.js`
 
-External linksは一時障害を考慮し`warn`を基本とする。
+Page titleは詳細・一覧とも`<ページ名> | <サイト名>`、Homeはサイト名だけとする。
 
----
+### 7.4 HeaderとFooter
 
-## 32. Content authoring rules
+Headerは`current_path`から現在地を判定し、対象リンクへ`aria-current="page"`を付ける。モバイルではHeaderを折り返し、ナビゲーションを次行へ配置する。
 
-### 32.1 Notes
+`body`を縦Flex、`main`を可変領域、Footerを固定高ではない終端領域とする。短いページではFooterをviewport下端へ置き、長いページでは本文の直後へ配置する。Footer内の上下paddingは全ページ共通である。
 
-- filename: lowercase ASCII kebab-case
-- `date`必須
-- title日本語可
-- tags任意
-- headingsはH2以降を本文主階層に使用
-- H1はtemplate titleに委ねる
-- referencesは本文末尾H2
+### 7.5 Home
 
-### 32.2 Software
+Homeは本文用`h1`や紹介文を表示せず、最近のNotesとSoftwareだけを表示する。それぞれのSection Pageを取得し、`config.extra.home_*_limit`件まで描画する。対象が0件の場合は説明付き空状態を表示する。
 
-- filename: software slug
-- cgit source必須
-- GitHubはmirrorとしてoptional
-- Overview/background/processはMarkdown本文
-- screenshotは必要時のみ
+### 7.6 Notes
 
-### 32.3 Internal references
+一覧は`section.pages`を`year`でgroup化し、年見出しとNote一覧を生成する。詳細はタイトル、公開日、任意の更新日・説明、目次、本文、関連Softwareの順に描画する。
 
-`@/` linkまたはfront matter pathを使用。
-公開URLを内部参照用にhard-codeしない。
+目次は`page.toc`が空でない場合だけ表示する。脚注はMarkdown rendererが記事末尾へ生成する。
 
----
+### 7.7 Software
 
-## 33. Date display
+一覧はSoftware名と説明を簡潔に表示し、末尾からサイト共通のcgitへ案内する。詳細はタイトル、説明、metadata、本文、関連Notesの順に描画する。
 
-内部データはISO date。
+metadataはデスクトップで2列、モバイルで1列とする。項目数が奇数の場合、最後の項目を全幅にして罫線を維持する。Sourceは必須、language、license、Mirrorは値がある場合だけ表示する。
 
-表示は初期実装で：
+### 7.8 Tagsと404
 
-```text
-2026-08-21
-```
+タグ一覧は`terms`の名称と記事数を表示する。タグ別ページは`term.pages`をNote一覧Partialで表示する。404はHome、Notes、Softwareへの復帰導線を持つ。
 
-とする。
+## 8. Presentation設計
 
-将来日本語表記`2026年8月21日`へ変更してもcontent metadataは変えない。
+### 8.1 SCSS構成
 
----
+`sass/main.scss`から次の順でPartialを読み込む。
 
-## 34. Home content algorithm
+| Partial | 責務 |
+|---|---|
+| `_tokens.scss` | 色、font、幅、罫線のcustom properties |
+| `_reset.scss` | box modelと既定marginの初期化 |
+| `_base.scss` | body、link、focus、外部link |
+| `_typography.scss` | 見出しとmetadata文字 |
+| `_layout.scss` | container、page余白、共通配置 |
+| `_header.scss` | Header、navigation、theme button |
+| `_footer.scss` | Footer |
+| `_archive.scss` | Notes一覧、タグ表示、空状態 |
+| `_article.scss` | 記事header、目次、本文、脚注、関連項目 |
+| `_software.scss` | Software一覧とmetadata |
+| `_taxonomy.scss` | タグ一覧 |
+| `_code.scss` | inline codeとcode block |
+| `_theme.scss` | 手動themeとreduced motion |
+| `_utilities.scss` | skip link、視覚非表示utility |
 
-Pseudo:
+### 8.2 Design tokens
 
-```text
-notes = get_section(notes)
-software = get_section(software)
-
-recent_notes = first 5 notes
-recent_software = first 4 software
-
-render:
-  site intro
-  recent notes
-  all notes link
-  software
-  all software link
-  about short text
-```
+| Token | Light | Dark |
+|---|---|---|
+| Background | `#f6f5f1` | `#17191b` |
+| Surface | `#fbfaf7` | `#1d2022` |
+| Text | `#202124` | `#e9e9e6` |
+| Muted | `#666b70` | `#a0a3a6` |
+| Border | `#d6d8da` | `#363a3e` |
+| Link | `#315f82` | `#86b6d8` |
+| Focus | `#1e668f` | `#86b6d8` |
 
-Homeは最新更新日を強く演出せず、`最近のNotes`と表記する。
+本文fontはsystem sans-serif、metadataとcodeはsystem monospaceを使用する。外部fontは読み込まない。本文最大幅は`72ch`、サイト最大幅は`72rem`とする。
 
----
+### 8.3 Responsive layout
 
-## 35. Archive algorithm
+| 対象 | Breakpoint | 変更 |
+|---|---:|---|
+| Footer | `32rem` | 縦積み |
+| Home section heading | `38rem` | 縦積み |
+| Notes一覧 | `40rem` | 年・日付と本文を1列化 |
+| Header／Software | `42rem` | Header折返し、Softwareを1列化 |
 
-Zola公式archive patternを使用。
+containerは左右に最低`1rem`の余白を確保する。表とcode blockは必要に応じて横スクロールさせ、ページ全体の横overflowを防ぐ。画像はcontainer幅を超えない。
 
-Pseudo Tera:
+## 9. Theme切替
 
-```tera
-{% set pages_by_year = section.pages | group_by(attribute="year") %}
-{% for year, pages in pages_by_year %}
-  <section>
-    <h2>{{ year }}</h2>
-    {% for page in pages %}
-       ...
-    {% endfor %}
-  </section>
-{% endfor %}
-```
+初期themeは`prefers-color-scheme`に従う。JavaScriptが動作するとtheme buttonを表示し、選択した`light`または`dark`を`localStorage.theme`へ保存する。
 
-使用Zola/Tera版でyear orderが期待通りでない場合、公式Archive例のreverse処理を採用する。
+`static/js/theme.js`は次を同期する。
 
----
+1. `<html data-theme>`
+2. theme buttonの表示、`aria-label`、`aria-pressed`
+3. Light／Dark syntax CSSの`media`
+4. OS theme変更。ただし手動選択済みの場合は上書きしない。
 
-## 36. TOC recursive rendering
+Storageへアクセスできない場合も現在のページでは切替を継続する。JavaScriptが無効な場合はbuttonを非表示にし、CSSの`prefers-color-scheme`だけで表示する。
 
-`page.toc`の`children`を階層描画する。
+## 10. Accessibility設計
 
-概念：
+| 要求 | 実装 |
+|---|---|
+| Landmark | `header`、`nav`、`main`、`article`、`section`、`footer`を用途に応じて使用 |
+| Skip link | ページ先頭から`#main-content`へ移動 |
+| 現在地 | Header linkの`aria-current="page"` |
+| Focus | 全操作要素へ3px outlineを表示 |
+| 見出し | 一覧・詳細はページ名を`h1`、本文を`h2`以下とする。Homeはサイト名の重複表示を避け、各領域を`h2`とする。 |
+| 日付 | 表示値と`datetime`を持つ`time` |
+| 目次 | `nav`と`aria-label="目次"` |
+| Theme | buttonの状態と操作内容をARIAへ反映 |
+| Motion | `prefers-reduced-motion: reduce`でanimationとtransitionを抑制 |
+| 画像 | Markdownで代替textを必須とする |
 
-```text
-toc(headers):
-  ul
-    foreach header
-      li
-        a header.permalink / title
-        if children
-          toc(children)
-```
+## 11. Feed・Taxonomy・SEO
 
-使用Zola版がTera componentを推奨する場合はcomponentを使用する。
-古いshortcode設計を新規導入しない。
+### 11.1 Feed
 
----
+サイトrootへAtomとRSSを生成し、全HTMLからautodiscovery linkを提供する。SoftwareはPage単位でFeedから除外する。タグ別Feedは生成しない。
 
-## 37. Dark mode persistence
+### 11.2 Taxonomy
 
-`theme.js` concept:
+`tags`だけを定義する。Noteの`taxonomies.tags`からタグ一覧とタグ別ページを自動生成する。タグを持つNoteが0件の場合、Zolaはタグページを生成しない。タグURLは`slugify.taxonomies = "on"`に従う。
 
-```text
-on load:
-  stored = localStorage.getItem("theme")
-  if stored light/dark:
-      set data-theme
-
-on toggle:
-  determine current
-  toggle
-  store
-  update accessible label
-```
+### 11.3 SEO metadata
 
-System preferenceはCSS側で処理する。
+全ページにtitle、description、canonical URLを設定する。sitemapとrobots.txtはZola組み込みtemplateで生成する。Open Graph、SNS card、構造化dataは実装しない。
 
-localStorageが利用不可でもerrorで本文表示を妨げない。
+## 12. Security・Privacy・Performance
 
----
+### 12.1 SecurityとPrivacy
 
-## 38. Favicon
+- inline scriptとinline event handlerを使用しない。
+- Syntax highlightはclass方式とし、inline styleを生成しない。
+- 外部theme、CDN、外部font、analytics、commentsを使用しない。
+- 新しいtabを開く明示的な外部linkには`noopener noreferrer`を付ける。
+- theme選択以外の利用者dataを保存しない。
+- 動的入力、認証、server-side処理を持たない。
 
-初期faviconは自作SVG 1ファイル。
+この構成は厳格なContent Security Policyを適用しやすいが、CSP header自体は配信環境の責務であり本リポジトリでは設定しない。
 
-モチーフは単純な文字または記号。
+### 12.2 Performance
 
-例候補：
+- JavaScriptはtheme切替の1ファイルだけを`defer`で読み込む。
+- system fontを使用し、font downloadを発生させない。
+- Markdown画像へlazy loadingとasync decodingを付ける。
+- Pageごとに必要な静的HTMLを生成し、実行時renderingを行わない。
+- Syntax CSSはthemeごとに分離する。
 
-- 「記」
-- `T`
-- 小さな本/ノートを抽象化した幾何形状
+## 13. 執筆・保守手順
 
-初期実装では複雑なfavicon pipelineを作らない。
+### 13.1 記事追加
 
----
+1. [content-templates/README.md](content-templates/README.md)を確認する。
+2. NotesまたはSoftwareの雛形をコピーする。
+3. Front Matterの説明コメントを削除し、必須値を入力する。
+4. 関連pathとMarkdown内部リンクを確認する。
+5. `zola check`と`zola build`を実行する。
 
-## 39. 404 design
+Markdownを追加するだけでSection一覧、個別URL、Homeの最新一覧へ反映される。Templateの変更は不要である。
 
-通常Pageと同じwidth/token/themeを使用。
+### 13.2 記事削除
 
-内容：
+削除対象を参照する次の箇所を先に検索する。
 
 ```text
-404
-ページが見つかりません。
-
-Home
-Notes
-Software
+extra.related_notes
+extra.related_software
+Markdownの @/ 内部リンク
 ```
 
-Animationやillustration不要。
-
----
-
-## 40. Testing / Validation checklist
-
-### 40.1 Zola
-
-- [ ] `zola check`
-- [ ] `zola build`
-- [ ] `/public/index.html`
-- [ ] `/public/notes/index.html`
-- [ ] `/public/software/index.html`
-- [ ] `/public/about/index.html`
-- [ ] `/public/404.html`
-- [ ] `/public/atom.xml`
-- [ ] `/public/rss.xml`
-- [ ] `/public/giallo-light.css`
-- [ ] `/public/giallo-dark.css`
-- [ ] sitemap
-- [ ] robots
-
-### 40.2 Content
-
-- [ ] Note 2件以上でyear grouping確認
-- [ ] 複数年でarchive確認
-- [ ] tag link確認
-- [ ] updatedあり/なし確認
-- [ ] TOCあり/なし確認
-- [ ] footnote確認
-- [ ] references style確認
-- [ ] related software確認
-- [ ] related note確認
-- [ ] Software GitHub mirrorあり/なし確認
-- [ ] Screenshotあり/なし確認
-
-### 40.3 Responsive
-
-- [ ] Desktop
-- [ ] Narrow desktop
-- [ ] Tablet
-- [ ] Mobile
-- [ ] Long title
-- [ ] Long URL
-- [ ] Code block
-- [ ] Table
-- [ ] Image
-
-### 40.4 Accessibility
-
-- [ ] Keyboard only
-- [ ] Focus visible
-- [ ] Skip link
-- [ ] Heading hierarchy
-- [ ] Theme toggle keyboard
-- [ ] Link underline
-- [ ] Dark contrast
-- [ ] Light contrast
-
-### 40.5 Security
-
-- [ ] no external JS
-- [ ] no external CSS
-- [ ] no npm
-- [ ] no Node
-- [ ] no inline event handler
-- [ ] no eval
-- [ ] CSP-compatible
-- [ ] no tracking script
-
----
-
-## 41. Traceability / 仕様整合性確認
-
-| Specifications要求 | Design対応 | 状態 |
-|---|---|---|
-| Notes + Software中心 | Sectionsとして分離 | OK |
-| Home index | `index.html`で5 Notes / 4 Software | OK |
-| 年別Notes | Zola archive `group_by(year)` | OK |
-| tagsのみ | `taxonomies = [{name="tags"}]` | OK |
-| Note Sans/余白 | Typography/Layout | OK |
-| Note TOC常時 | `page.toc` inline nav | OK |
-| Footnotes | Zola Markdown標準 | OK |
-| References | Markdown H2 +共通SCSS | OK |
-| 公開日/更新日 | date/updated | OK |
-| Software一覧はPJ名中心 | software/section | OK |
-| Software背景・過程 | Markdown body | OK |
-| 言語/License | `extra` | OK |
-| cgit正本 | `extra.source`必須 | OK |
-| GitHub mirror | optional extra | OK |
-| Related Notes/Software | explicit content path + `get_page` | OK |
-| About | `about.md` | OK |
-| Header小型 | partial/header | OK |
-| Source navなし | Headerには含めない | OK |
-| 日本語のみ | `default_language="ja"` | OK |
-| Sans + Mono | SCSS token | OK |
-| 青accent | color token | OK |
-| Dark mode | CSS + minimal JS | OK |
-| Sidebarなし | article inline layout | OK |
-| タグは一覧中心 | Note detailで主要表示しない | OK |
-| RSS + Atom | built-in feeds | OK |
-| Search将来 | initial false | OK |
-| Comments条件付き | initial scope外 | OK |
-| SNS条件付き | initial scope外 | OK |
-| Analyticsなし | scriptなし | OK |
-| Images最小限 | colocated assets optional | OK |
-| No animation | motionなし | OK |
-| Blue links | SCSS | OK |
-| External marker | `external_links_class` + CSS | OK |
-| ASCII slug | authoring rules | OK |
-| Caddy static | public artifact only | OK |
-| npm/Nodeなし | no dependency toolchain | OK |
-
----
-
-## 42. 仕様上の未確定事項に対する設計判断
-
-### 42.1 本文最大幅
-
-仕様では後決めだったため、初期値 **72ch** を採用。
-日本語本文で広すぎる場合は65〜75ch相当の範囲で調整する。
-
-### 42.2 青の具体色
-
-初期候補として落ち着いた`#315f82`系を採用。
-WCAG contrast確認後に調整可。
-
-### 42.3 Home件数
-
-仕様上「おまかせ」だったため以下を採用。
-
-- Notes 5
-- Software 4
-
-### 42.4 favicon
-
-自作単純SVGとし、外部assetを導入しない。
-最終モチーフはvisual tuning時に決定可能。
-
-### 42.5 Comments
-
-静的構成との境界が未確定のため、初期実装対象外。
-
-### 42.6 SNS共有
+参照を残すと`get_page`またはlink checkerによりビルドが失敗する。削除後は必ず`zola check`を実行する。
 
-「簡単に対応できれば」という条件付き要件のため、初期実装対象外。
-外部dependencyなしで必要性が確認できた時点で追加する。
-
----
-
-## 43. 実装Phase
-
-### Phase C1 — Foundation
-
-- Zola version確認
-- `zola.toml`
-- content structure
-- base template
-- SCSS entry
-- `zola check/build`
-
-PASS:
-- Build成功
-- Home生成
-
-### Phase C2 — Information Architecture
-
-- Notes Section
-- Software Section
-- About
-- Tags taxonomy
-- URLs
-
-PASS:
-- `/notes/`, `/software/`, `/about/`, `/tags/`
-
-### Phase C3 — Editorial UI
-
-- Header/Footer
-- typography
-- layout
-- light/dark
-- links
-- responsive
-
-PASS:
-- Desktop/Mobile
-- no external dependencies
-
-### Phase C4 — Notes
+### 13.3 Draft
 
-- year archive
-- tags in list
-- note dates
-- TOC
-- footnotes
-- references
+公開しない原稿はrootの`draft/`へ置く。`draft/`は`.gitignore`に含まれ、Gitでも管理しない。公開時にFront Matterを整え、対応する`content/`配下へ移す。
 
-PASS:
-- 複数年sampleで表示確認
+## 14. Build・検証・配信境界
 
-### Phase C5 — Software
+### 14.1 Command
 
-- software list
-- detail metadata
-- source/mirror
-- related notes
-- optional images
+| 目的 | Command |
+|---|---|
+| 開発表示 | `zola serve` |
+| 構造・link検証 | `zola check` |
+| 生成 | `zola build` |
 
-PASS:
-- Source優先表示
-- related page resolution
+### 14.2 必須検証
 
-### Phase C6 — Static Features
+| 分類 | 確認内容 |
+|---|---|
+| Zola | `zola check`と`zola build`が成功する。 |
+| Page | Home、About、Notes、Software、404が生成され、タグ使用時はTagsも生成される。 |
+| Feed | `atom.xml`と`rss.xml`が生成され、Softwareを含まない。 |
+| Crawler | `sitemap.xml`と`robots.txt`が生成される。 |
+| Asset | `main.css`、syntax CSS 2種、theme.js、favicon、記事assetが生成される。 |
+| Link | 削除済みPage、存在しない関連path、誤った内部linkがない。 |
+| HTML | canonical URLとFeed autodiscoveryが正しい。 |
+| Security | inline script、inline event handler、外部CDN参照がない。 |
+| Responsive | Header、一覧、Software metadata、Footerが各breakpointで崩れない。 |
+| Accessibility | skip link、focus、現在地、見出し順、theme buttonを確認する。 |
 
-- feeds
-- sitemap
-- robots
-- 404
-- syntax highlighting
-- favicon
+### 14.3 配信境界
 
-PASS:
-- expected artifacts生成
+本リポジトリの責務は`public/`の生成までとする。VPS、Caddy、TLS、cache、CSP header、deploy scriptは外部の配信環境で管理し、本設計の対象外とする。
 
-### Phase C7 — Final Validation
+## 15. 仕様との対応
 
-- `zola check`
-- `zola build`
-- link checks
-- accessibility
-- responsive
-- CSP compatibility
-- Git status
-
-PASS:
-- Specifications受入条件を全件満たす
-
----
-
-## 44. 実装禁止事項
-
-Codex等の実装エージェントは以下を勝手に追加しない。
-
-- npm
-- Node.js
-- React
-- Vue
-- Svelte
-- htmx
-- Tailwind
-- Bootstrap
-- external CSS framework
-- external icon framework
-- external JS CDN
-- Google Fonts等external font
-- client-side syntax highlighter
-- analytics
-- comments
-- search
-- server backend
-- database
-- Docker
-- unnecessary build script
-- external Zola theme
-- animations
-
-必要が生じた場合は実装前に要求変更として報告する。
-
----
-
-## 45. 完了判定
-
-Design実装完了時に以下を報告する。
-
-1. 使用Zola version
-2. 実装したdirectory tree
-3. `zola check`結果
-4. `zola build`結果
-5. 生成ファイル確認
-6. 主要URL一覧
-7. external dependencyがないこと
-8. Specifications traceability結果
-9. 未実装項目
-10. 仕様からの逸脱の有無
-
-仕様から逸脱した場合は、理由・影響・代替案を明記する。
-
----
-
-## 46. 公式Zola仕様との整合上の注意
-
-- `zola.toml` を正式設定ファイルとして使用する。
-- `content/notes/_index.md` と `content/software/_index.md` をSection定義とする。
-- `about.md` はPageとして扱う。
-- Homepageはroot Sectionとして`templates/index.html`を使用する。
-- Notes/SoftwareはSectionの`template` / `page_template`で専用Templateへ接続する。
-- ZolaのTaxonomyで`tags`を実装する。
-- 年別ArchiveはZola公式例と同じ`group_by(attribute="year")`系の実装を使う。
-- 関連Pageは`get_page(path=...)`で解決する。
-- Markdown本文内の内部リンクは`@/`を優先する。
-- Feed、sitemap、robotsはZola built-inを優先する。
-- `static/`はas-is copy、`sass/`はZola compile対象として扱う。
-- Page/SectionのTera contextを使用し、独自content indexを作らない。
-- 利用Zola版でTera Componentsが利用可能・推奨なら、TOC等の再利用可能UIに採用してよい。
-- 将来Searchを有効化する際、日本語検索index対応はZola binary build featureの確認を必須とする。
+| 仕様領域 | 主な実装箇所 |
+|---|---|
+| Home | `templates/index.html`、`home_*_limit` |
+| Notes | `content/notes/`、`templates/notes/`、`_archive.scss`、`_article.scss` |
+| Tags | `taxonomies`、`templates/tags/`、`_taxonomy.scss` |
+| Software | `content/software/`、`templates/software/`、`_software.scss` |
+| About | `content/about.md`、`templates/page.html`、`zola.toml` |
+| 共通navigation | `partials/header.html`、`partials/footer.html` |
+| Theme | `_tokens.scss`、`_theme.scss`、`static/js/theme.js` |
+| Accessibility | `base.html`、各semantic template、`_utilities.scss` |
+| Feed・crawler | `zola.toml`、`base.html`、Zola built-in templates |
+| Privacy・Security | `zola.toml`、`base.html`、local asset構成 |