path: root/doc/Specifications.md

はい。公式ドキュメントに沿って見直すと、前回の要求仕様にはいくつか **Zola固有の構成・命名に寄せた方がよい点**があります。

特に重要なのは、Zolaは公式に「サイト構造を決めつけない」としており、基本は `content/` 配下の **Section (`_index.md`) と Page (`*.md`)**、そして `template` / `page_template` でテンプレートを結びつける構造です。公式の初期ディレクトリも `zola.toml / content / sass / static / templates / themes` です。 ([Zola][1])

その前提で、Codex向け仕様は次のように修正するのがよいです。

````markdown
# Zola Web Site Client Implementation Requirements

## 1. 目的

自前VPS上で Caddy により配信する個人Webサイトを Zola で構築する。

本番VPSでは動的Webアプリケーションを実行せず、クライアントPC上で Zola により静的HTML/CSS/JSを生成し、生成済み成果物のみをVPSへデプロイする。

npm / Node.js に依存しない構成とし、Webサイト構築に伴うサプライチェーン攻撃面を最小化する。

---

# 2. Zola採用方針

Zola公式ドキュメントの構造・概念・標準機能に従うこと。

Zolaは以下を基本概念として使用する。

- Site configuration: `zola.toml`
- Content
  - Section: `_index.md`
  - Page: 通常のMarkdownファイル
- Templates: Tera
- Sass: `sass/`
- Static assets: `static/`
- Themes: `themes/`
- Build output: `public/`

独自のディレクトリ規約や別SSG由来の設計を持ち込まず、Zola標準のSection/Pageモデルを優先する。

---

# 3. 必須技術構成

| 領域 | 採用 |
|---|---|
| Static Site Generator | Zola |
| Configuration | `zola.toml` |
| Content | CommonMark Markdown |
| Content model | Zola Section / Page |
| Template engine | Tera |
| Style | Sass / SCSS |
| JavaScript | 必要最小限の vanilla JavaScript |
| Backend | なし |
| Database | なし |
| npm / Node.js | 使用しない |
| htmx | 使用しない |
| External CDN | 原則使用しない |
| Production Web server | Caddy |

---

# 4. Zola標準ディレクトリ構造

`zola init` が生成する構造を基準とする。

```text
website/
├── zola.toml
├── content/
├── sass/
├── static/
├── templates/
└── themes/
````

build後には以下が生成される。

```text
public/
```

`public/` は生成物でありGit管理しない。

`themes/` はZola標準ディレクトリとして保持してよいが、本プロジェクトでは外部themeを原則使用しない。

---

# 5. 初期サイト構造

以下のコンテンツ領域を実装する。

```text
/
├── about/
├── projects/
└── notes/
```

想定URL:

```text
https://www.takashi-2521.com/
https://www.takashi-2521.com/about/
https://www.takashi-2521.com/projects/
https://www.takashi-2521.com/notes/
```

ZolaのSection/Pageモデルに従い、以下を基本構造とする。

```text
content/
├── about.md
│
├── projects/
│   ├── _index.md
│   ├── project-a.md
│   └── project-b.md
│
└── notes/
    ├── _index.md
    ├── note-a.md
    └── note-b.md
```

`projects/_index.md` と `notes/_index.md` は Zola Section とする。

`projects/*.md` および `notes/*.md` は Zola Page とする。

About は単独Pageとして扱う。

必要な理由がある場合のみPage Bundle等の別構造を採用してよい。

---

# 6. Section設計

## 6.1 Projects Section

`content/projects/_index.md` を作成する。

例:

```toml
+++
title = "Projects"
sort_by = "date"
template = "projects.html"
page_template = "project-page.html"
+++
```

Zola標準のSection変数を使用する。

Projects一覧はTera側で、

```text
section.pages
```

を利用して生成する。

独自JSON index等を作成しない。

---

## 6.2 Notes Section

`content/notes/_index.md` を作成する。

例:

```toml
+++
title = "Notes"
sort_by = "date"
template = "notes.html"
page_template = "note-page.html"
+++
```

新しいNoteは `content/notes/*.md` を追加するだけで一覧へ反映されること。

---

# 7. Page設計

## 7.1 Project Page

Projectは1 Markdown = 1 Zola Pageとする。

例:

```toml
+++
title = "Example Project"
date = 2026-08-21
description = "Project description"

[extra]
status = "active"
repository = "https://example.invalid/"
+++
```

Zola標準front matterで直接扱えないプロジェクト固有metadataは `[extra]` を使用する。

最低限以下を扱えるようにする。

* `title`
* `date`
* `description`

Project固有情報:

* `extra.status`
* `extra.repository`

必要なら以下も追加可能。

* `extra.homepage`
* `extra.language`
* `extra.license`

metadataを過剰に増やさないこと。

---

## 7.2 Note Page

例:

```toml
+++
title = "Example Note"
date = 2026-08-21
description = "Note description"
+++

本文...
```

本文はZolaの `page.content` としてtemplateから表示する。

---

# 8. Templates

Zola公式ドキュメントのtemplate inheritanceを利用する。

最低限以下を構成する。

```text
templates/
├── base.html
├── index.html
├── projects.html
├── project-page.html
├── notes.html
├── note-page.html
└── page.html
```

必要であれば以下を追加する。

```text
templates/
└── partials/
    ├── header.html
    ├── navigation.html
    └── footer.html
```

`base.html` を共通レイアウトとし、各templateはTeraの

```text
{% extends "base.html" %}
```

およびblockを使用する。

---

# 9. Internal Link方針

サイト内部リンクは、可能な限りURL文字列をハードコードせず、Zolaの `get_url` と `@/` internal link記法を使用する。

例:

```tera
<a href="{{ get_url(path='@/projects/_index.md') }}">Projects</a>
```

これによりcontent path変更時のリンク破損を減らす。

---

# 10. Home Page

Homeは `templates/index.html` で生成する。

最低限以下を表示可能にする。

* サイト名
* 簡単な説明
* Aboutへのリンク
* Projectsへのリンク
* Notesへのリンク

Home用の不要なCMS的データ構造は作らない。

必要なら `zola.toml` の `extra` をサイト全体metadataとして使用してよい。

---

# 11. Sass / SCSS

Zola標準Sass compilationを使用する。

`zola.toml`:

```toml
compile_sass = true
```

構成例:

```text
sass/
├── main.scss
├── _variables.scss
├── _base.scss
├── _typography.scss
├── _layout.scss
└── _components.scss
```

npm Sass / Dart Sass / PostCSS等は追加しない。

---

# 12. Static assets

Zolaの `static/` はbuild時に出力先へそのままコピーされる前提で使用する。

例:

```text
static/
├── favicon.svg
├── robots.txt
├── images/
└── js/
    └── site.js
```

外部CDN依存を原則禁止する。

JavaScriptが必要な場合は `static/js/site.js` 等として自前配信する。

---

# 13. JavaScript

JavaScriptは必要最小限の vanilla JavaScript のみ使用する。

以下の原則に従う。

1. HTML標準機能で実現可能ならJSを使用しない。
2. CSSのみで実現可能ならJSを使用しない。
3. 外部frontend frameworkを導入しない。
4. inline event handlerを使用しない。
5. `eval()` を使用しない。
6. JavaScript無効でも主要コンテンツを閲覧可能にする。

---

# 14. Syntax Highlighting

技術記事用のコードブロックsyntax highlightingにはZola標準機能を使用する。

独自のPrism.js / highlight.js等は初期実装では導入しない。

設定は採用するZola versionの公式configuration仕様に従うこと。

---

# 15. Feeds

NotesについてRSS/Atom等のfeedを生成する。

Zola標準feed生成機能を使用する。

独自feed generatorは実装しない。

採用するZola versionにおける推奨設定を確認して実装すること。

---

# 16. Sitemap

Zola標準のsitemap生成機能を使用する。

独自 `sitemap.xml` generatorは作らない。

---

# 17. robots.txt

Zolaの標準 `robots.txt` template機能または `static/robots.txt` のうち、公式ドキュメントに沿った単純な方法を採用する。

不要な独自処理を作らない。

---

# 18. 404 Page

Zola標準の404 template仕様に従って実装する。

想定:

```text
templates/404.html
```

Caddyから静的404として扱える成果物を生成する。

---

# 19. Search

初期実装では検索を無効とする。

`zola init` / configuration上もsearch indexを生成しない設定とする。

将来必要になった場合のみZola標準search indexを再検討する。

外部検索libraryは現時点では導入しない。

---

# 20. Themes

Zolaは `themes/` を標準で持つが、本プロジェクトでは外部themeを原則使用しない。

理由:

* supply-chain面積を増やさない
* upstream theme更新への依存を避ける
* CSS/templateを完全に管理可能にする
* 不要なJavaScriptを取り込まない

したがって自前template + 自前SCSSを基本とする。

---

# 21. Zola Configuration

設定ファイル名は公式構成に合わせて、

```text
zola.toml
```

を使用する。

最低限:

```toml
base_url = "https://www.takashi-2521.com"
compile_sass = true
build_search_index = false
```

実際のsyntax highlighting、feed、taxonomy等については、使用するZola versionの公式documentationを確認して正しいconfiguration keyを使用すること。

推測で設定名を追加しないこと。

---

# 22. Development

ローカル開発ではZola標準development serverを使用する。

```bash
zola serve
```

Zolaは `zola.toml`, `content`, `sass`, `static`, `templates` の変更を監視し、local live reloadに使用できる。

追加のdev serverは作成しない。

---

# 23. Validation / Build

実装中は以下を使用する。

```bash
zola check
zola build
```

local preview:

```bash
zola serve
```

build output:

```text
public/
```

`public/` のみでサイトが成立すること。

---

# 24. Git

sourceのみGit管理する。

`.gitignore`:

```gitignore
/public/
```

Zolaが実際に生成しない独自cache directoryを推測で追加しないこと。

Editor / OS固有ファイルは必要に応じて追加可能。

---

# 25. Deployment境界

本仕様ではVPS側の配信基盤は変更しない。

既存:

```text
/srv/www/takashi-2521.com/
├── releases/
└── current -> releases/<release-id>
```

Caddy:

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

クライアント側では将来、

```text
zola check
→ zola build
→ public/
→ archive
→ SSH transfer
→ releases/<release-id>
→ current切替
```

を行う。

本Client Phaseでは `public/` が自己完結したbuild artifactになることを保証する。

---

# 26. Security Requirements

必須:

* npmを使用しない
* Node.js dependencyを使用しない
* React/Vue/Svelteを使用しない
* htmxを使用しない
* Tailwindを使用しない
* 外部CDNを使用しない
* external themeを原則使用しない
* backendを実装しない
* DBを使用しない
* buildをVPSで実行しない

可能な限り以下の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 script / inline event handlerは避ける。

---

# 27. Accessibility

最低限以下を満たす。

* semantic HTML
* 正しいheading hierarchy
* keyboard navigation
* visible focus
* alt text
* color contrast
* `prefers-reduced-motion` を考慮
* JSなしでも主要navigationが利用可能

---

# 28. Client Phase

## Client-1: Zola initialization

* Zola version確認
* `zola init` 相当の標準構成を確認
* `zola.toml`
* 標準directory作成
* `zola check`
* `zola build`

PASS:

```text
zola check PASS
zola build PASS
public/index.html exists
```

---

## Client-2: Section / Page architecture

* Home
* About Page
* Projects Section
* Project Pages
* Notes Section
* Note Pages

PASS:

```text
/
 /about/
 /projects/
 /projects/<page>/
 /notes/
 /notes/<page>/
```

が生成される。

---

## Client-3: Tera templates / UI

* `base.html`
* template inheritance
* navigation
* header/footer
* SCSS
* responsive layout

PASS:

* Desktop正常
* Mobile正常
* internal navigation正常

---

## Client-4: Content model

Projects/NotesをZola Pageとして管理する。

PASS:

Markdownを1件追加すると、

```text
Section listing
+
individual Page
```

の両方へ自動反映される。

---

## Client-5: Zola static features

* syntax highlighting
* feed
* sitemap
* robots.txt
* 404
* favicon

Zola標準機能を優先する。

PASS:

`zola build` の成果物に必要な静的ファイルが生成される。

---

## Client-6: Git / final validation

* `.gitignore`
* sourceのみGit管理
* external dependenciesなし
* final `zola check`
* final `zola build`

---

# 29. Final Acceptance Criteria

以下をすべて満たすこと。

* [ ] Zola公式のSection/Pageモデルを使用している
* [ ] `zola.toml` を使用している
* [ ] `content/` を使用している
* [ ] Sectionは `_index.md` で定義されている
* [ ] ProjectはZola Pageとして実装されている
* [ ] NoteはZola Pageとして実装されている
* [ ] Section `template` / `page_template` を適切に使用している
* [ ] Tera template inheritanceを使用している
* [ ] internal linkにZola標準機能を利用している
* [ ] Sass compilationはZola標準機能
* [ ] syntax highlightingはZola標準機能
* [ ] feedはZola標準機能
* [ ] sitemapはZola標準機能
* [ ] 404はZola標準機能
* [ ] `zola serve` が動作
* [ ] `zola check` が成功
* [ ] `zola build` が成功
* [ ] `public/` 単独で静的サイトとして成立
* [ ] npm dependencyなし
* [ ] Node.js dependencyなし
* [ ] frontend frameworkなし
* [ ] htmxなし
* [ ] external CDNなし
* [ ] external theme依存なし
* [ ] backendなし
* [ ] DBなし
* [ ] `public/` はGit管理外

[1]: https://www.getzola.org/documentation/getting-started/overview/ "Overview | Zola"