path: root/doc/Design.md

# Design.md

# たかしの記録 — Zola 基本・詳細設計書

## 1. 文書目的

本書は `Specifications.md` の要求を、Zolaによる静的Webサイトとして矛盾なく実装するための基本設計・詳細設計を定義する。

設計上の基本原則は次のとおり。

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. 参照仕様と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. システム構成

```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
```

ZolaはVPSへインストールしない。

---

## 4. Zolaサイト構造

```text
website/
├── zola.toml
├── content/
│   ├── _index.md
│   ├── about.md
│   ├── notes/
│   │   ├── _index.md
│   │   ├── example-note.md
│   │   └── ...
│   └── software/
│       ├── _index.md
│       ├── example-software.md
│       └── ...
├── templates/
│   ├── base.html
│   ├── index.html
│   ├── page.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
├── 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
├── static/
│   ├── favicon.svg
│   └── js/
│       └── theme.js
├── 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 = "日々考えたこととか思ったことを記録します"
+++
```

Home自体はZolaのroot sectionとして扱い、`templates/index.html` で描画する。

### 6.2 About Page

`content/about.md`

```toml
+++
title = "About"
template = "page.html"
+++
```

本文に以下をMarkdownで記述する。

- 名前
- 一言プロフィール
- サイトの目的
- 関心分野
- 連絡先

構造化metadataを必要以上に増やさない。

### 6.3 Notes Section

`content/notes/_index.md`

```toml
+++
title = "Notes"
sort_by = "date"
template = "notes/section.html"
page_template = "notes/page.html"
+++
```

#### 6.3.1 Notesのsort

Sectionはdate順にする。
テンプレートでは新しい順で表示されることを検証する。

#### 6.3.2 Notes Page front matter

新規記事用の完全な雛形は`doc/content-templates/note.md`を使用する。

```toml
+++
title = "記事タイトル"
description = "記事の短い説明"
date = 2026-08-21
updated = 2026-08-22

[taxonomies]
tags = ["情報工学", "AI"]

[extra]
related_software = [
    "software/example-software.md"
]
+++

本文...
```

#### 6.3.3 Notes必須/任意項目

| Field | 必須 | 用途 |
|---|---:|---|
| `title` | Yes | タイトル |
| `date` | Yes | 公開日 |
| `description` | No | 一覧・meta description |
| `updated` | No | 更新日 |
| `taxonomies.tags` | No | 一覧分類 |
| `extra.related_software` | No | 明示的な関連Software |
| Body | Yes | 本文 |

#### 6.3.4 Slug

Markdown filenameを英語ASCII slugとする。

例：

```text
content/notes/llm-compute-and-energy.md
```

表示タイトルは日本語でよい。

### 6.4 Software Section

`content/software/_index.md`

```toml
+++
title = "Software"
sort_by = "date"
template = "software/section.html"
page_template = "software/page.html"
+++
```

Software一覧の順序は初期状態ではdate順とする。
公開日を表示する必要はないが、並び順制御に利用する。

将来、並びを明示したくなった場合は`weight`へ変更可能。

#### 6.4.1 Software Page front matter

新規記事用の完全な雛形は`doc/content-templates/software.md`を使用する。

```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>
```

更新日がある場合だけ表示。

#### 8.6.5 Footnotes

Zola Markdown rendererが生成するfootnote markupへSCSSを適用する。

独自脚注システムを作らない。

#### 8.6.6 References

Markdown本文の通常Headingとして「参考文献」を記述する。

例：

```markdown
## 参考文献

1. ...
2. ...
```

専用front matter schemaは導入しない。

### 8.7 Software一覧 Template

`templates/software/section.html`

表示の中心はSoftware名。

例：

```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/
├── index.html
├── notes/
├── software/
├── tags/
├── main.css
└── ...
```

---

## 29. Caddy互換性

既存Caddy:

```text
root * /srv/www/takashi-2521.com/current
file_server
```

Zola outputはCaddy static file serverだけで利用できること。

以下を要求しない。

- rewrite application router
- server-side include
- PHP
- CGI
- Node
- Python backend

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

External linksは一時障害を考慮し`warn`を基本とする。

---

## 32. Content authoring rules

### 32.1 Notes

- filename: lowercase ASCII kebab-case
- `date`必須
- title日本語可
- tags任意
- headingsはH2以降を本文主階層に使用
- H1はtemplate titleに委ねる
- referencesは本文末尾H2

### 32.2 Software

- filename: software slug
- cgit source必須
- GitHubはmirrorとしてoptional
- Overview/background/processはMarkdown本文
- screenshotは必要時のみ

### 32.3 Internal references

`@/` linkまたはfront matter pathを使用。
公開URLを内部参照用にhard-codeしない。

---

## 33. Date display

内部データはISO date。

表示は初期実装で：

```text
2026-08-21
```

とする。

将来日本語表記`2026年8月21日`へ変更してもcontent metadataは変えない。

---

## 34. Home content algorithm

Pseudo:

```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
```

Homeは最新更新日を強く演出せず、`最近のNotes`と表記する。

---

## 35. Archive algorithm

Zola公式archive patternを使用。

Pseudo Tera:

```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 %}
```

使用Zola/Tera版でyear orderが期待通りでない場合、公式Archive例のreverse処理を採用する。

---

## 36. TOC recursive rendering

`page.toc`の`children`を階層描画する。

概念：

```text
toc(headers):
  ul
    foreach header
      li
        a header.permalink / title
        if children
          toc(children)
```

使用Zola版がTera componentを推奨する場合はcomponentを使用する。
古いshortcode設計を新規導入しない。

---

## 37. Dark mode persistence

`theme.js` concept:

```text
on load:
  stored = localStorage.getItem("theme")
  if stored light/dark:
      set data-theme

on toggle:
  determine current
  toggle
  store
  update accessible label
```

System preferenceはCSS側で処理する。

localStorageが利用不可でもerrorで本文表示を妨げない。

---

## 38. Favicon

初期faviconは自作SVG 1ファイル。

モチーフは単純な文字または記号。

例候補：

- 「記」
- `T`
- 小さな本/ノートを抽象化した幾何形状

初期実装では複雑なfavicon pipelineを作らない。

---

## 39. 404 design

通常Pageと同じwidth/token/themeを使用。

内容：

```text
404
ページが見つかりません。

Home
Notes
Software
```

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共有

「簡単に対応できれば」という条件付き要件のため、初期実装対象外。
外部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

- year archive
- tags in list
- note dates
- TOC
- footnotes
- references

PASS:
- 複数年sampleで表示確認

### Phase C5 — Software

- software list
- detail metadata
- source/mirror
- related notes
- optional images

PASS:
- Source優先表示
- related page resolution

### Phase C6 — Static Features

- feeds
- sitemap
- robots
- 404
- syntax highlighting
- favicon

PASS:
- expected artifacts生成

### Phase C7 — Final Validation

- `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の確認を必須とする。