From 9f2fb3bda733c32995c008bd0f40365e43c348da Mon Sep 17 00:00:00 2001 From: tanaka takashi Date: Sat, 22 Aug 2026 00:18:56 +0900 Subject: feat: Zolaで「たかしの記録」を構築 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Specifications.mdとDesign.mdを実装の基準として、個人アーカイブサイトをZola 0.23.3向けに構築する。 - Home、Notes、Software、About、Tagsの情報設計と専用URLを追加 - Notesの年別アーカイブ、タグ分類、目次、脚注、参考文献、更新日表示を実装 - Softwareの一覧・詳細、cgit/GitHub情報、Notesとの明示的な相互参照を実装 - Tera 2 componentによる再帰TOCと共通partialsを追加 - Minimal Editorial ArchiveのSCSS、レスポンシブ表示、アクセシビリティ対応を追加 - OS設定とlocalStorageに対応するLight/Darkテーマ切替を外部JavaScriptで実装 - Atom/RSS、sitemap、robots.txt、404、favicon、syntax highlightingを設定 - メールアドレスをzola.tomlへ一元化し、AboutとFooterから参照 - 表示名・内部ディレクトリ・変数・URLをSoftware/softwareへ統一 - public/をGit管理対象外とし、外部CDNやNode.js依存を導入しない - zola checkおよびzola buildの成功を確認 --- doc/Specifications.md | 995 ++++++++++++++++++++++++-------------------------- 1 file changed, 480 insertions(+), 515 deletions(-) (limited to 'doc/Specifications.md') diff --git a/doc/Specifications.md b/doc/Specifications.md index d2e9157..9f9c60f 100644 --- a/doc/Specifications.md +++ b/doc/Specifications.md @@ -1,755 +1,720 @@ -はい。公式ドキュメントに沿って見直すと、前回の要求仕様にはいくつか **Zola固有の構成・命名に寄せた方がよい点**があります。 +# Specifications.md -特に重要なのは、Zolaは公式に「サイト構造を決めつけない」としており、基本は `content/` 配下の **Section (`_index.md`) と Page (`*.md`)**、そして `template` / `page_template` でテンプレートを結びつける構造です。公式の初期ディレクトリも `zola.toml / content / sass / static / templates / themes` です。 ([Zola][1]) +# たかしの記録 — 要求仕様書 -その前提で、Codex向け仕様は次のように修正するのがよいです。 +## 1. 文書目的 -````markdown -# Zola Web Site Client Implementation Requirements +本書は、個人Webサイト「たかしの記録」の利用者視点・コンテンツ視点での要求仕様を定義する。 -## 1. 目的 - -自前VPS上で Caddy により配信する個人Webサイトを Zola で構築する。 - -本番VPSでは動的Webアプリケーションを実行せず、クライアントPC上で Zola により静的HTML/CSS/JSを生成し、生成済み成果物のみをVPSへデプロイする。 - -npm / Node.js に依存しない構成とし、Webサイト構築に伴うサプライチェーン攻撃面を最小化する。 +本書では「何を提供するサイトか」「誰がどのように読むか」「どの情報をどのように見せるか」を定義し、具体的なZola/Tera/SCSS実装方法は `Design.md` に委ねる。 --- -# 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/` +## 2. サイト概要 -独自のディレクトリ規約や別SSG由来の設計を持ち込まず、Zola標準のSection/Pageモデルを優先する。 +### 2.1 サイト名 ---- +**たかしの記録** -# 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 | +### 2.2 サイトの目的 ---- +本サイトは、運営者が日頃考えたこと・感じたこと・調べたことを記録し、作成したソフトウェアとともに長期的に保存・公開する個人アーカイブである。 -# 4. Zola標準ディレクトリ構造 +主な用途は次のとおり。 -`zola init` が生成する構造を基準とする。 +- 日々考えたことや感じたことの記録 +- 読書を通じて考えたことの記録 +- 技術調査・技術メモの公開 +- 長文記事・考察の公開 +- 作成したソフトウェアの紹介 +- ソフトウェア制作の背景・過程・設計意図の記録 +- ソフトウェアに関連する技術記事との相互参照 -```text -website/ -├── zola.toml -├── content/ -├── sass/ -├── static/ -├── templates/ -└── themes/ -```` +### 2.3 主な対象分野 -build後には以下が生成される。 +Notesでは特定分野に限定せず、少なくとも以下を扱う。 -```text -public/ -``` +- 情報工学・ソフトウェア +- 論理学 +- マルクス・資本論・政治経済 +- 地球環境 +- 読書を通じた考察 +- 上記にまたがる複合的なテーマ -`public/` は生成物でありGit管理しない。 +分類は固定カテゴリではなくタグを基本とし、分野横断の記事を許容する。 -`themes/` はZola標準ディレクトリとして保持してよいが、本プロジェクトでは外部themeを原則使用しない。 +### 2.4 想定読者 ---- +- 運営者本人 +- ソフトウェアエンジニア +- 技術分野に関心のある一般読者 +- 学生 +- 個々の記事テーマに関心のある一般人 -# 5. 初期サイト構造 +専門読者だけに限定せず、記事冒頭で主題を把握できることを重視する。 -以下のコンテンツ領域を実装する。 +### 2.5 更新頻度 -```text -/ -├── about/ -├── projects/ -└── notes/ -``` +通常は **2〜3か月に1〜2回程度** を想定する。 -想定URL: +更新頻度を競うニュースサイトやSNSではなく、長期間残るアーカイブとして設計する。 -```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モデルに従い、以下を基本構造とする。 +## 3. サイトの基本コンセプト -```text -content/ -├── about.md -│ -├── projects/ -│ ├── _index.md -│ ├── project-a.md -│ └── project-b.md -│ -└── notes/ - ├── _index.md - ├── note-a.md - └── note-b.md -``` +### 3.1 中心コンテンツ -`projects/_index.md` と `notes/_index.md` は Zola Section とする。 +サイトの主役は以下の2つとする。 -`projects/*.md` および `notes/*.md` は Zola Page とする。 +1. **Notes** +2. **Software** -About は単独Pageとして扱う。 +HomeとAboutは、この2つへの入口・補助情報として扱う。 -必要な理由がある場合のみPage Bundle等の別構造を採用してよい。 +### 3.2 デザインコンセプト ---- +デザインは **Minimal Editorial Archive** を基本とする。 -# 6. Section設計 +方向性は以下。 -## 6.1 Projects Section +- 文章とリンクを主役にする +- 装飾を抑える +- 罫線・余白・タイポグラフィで情報階層を表現する +- カードUIを乱用しない +- 画像を主役にしない +- 技術者向けダッシュボード風・SaaSランディングページ風にしない +- 長文を落ち着いて読める +- 更新間隔が長くても「止まったサイト」に見えにくい +- Gwern.netの長文アーカイブ性とSimon Willison's Weblogの実用的な情報構造を参考にする -`content/projects/_index.md` を作成する。 +### 3.3 基本画面構造 -例: +全画面の基本構造は以下。 -```toml -+++ -title = "Projects" -sort_by = "date" -template = "projects.html" -page_template = "project-page.html" -+++ -``` +- 小さなHeader +- Main content +- 小さなFooter -Zola標準のSection変数を使用する。 +Header/Footerは本文より目立たせず、高さも必要以上に取らない。 -Projects一覧はTera側で、 +Sidebarは使用しない。 -```text -section.pages -``` +--- -を利用して生成する。 +## 4. 情報アーキテクチャ -独自JSON index等を作成しない。 +### 4.1 グローバル構成 ---- +トップレベルは以下を基本とする。 -## 6.2 Notes Section +- `/` — Home +- `/notes/` — Notes一覧 +- `/software/` — Software一覧 +- `/about/` — About +- `/tags/` — タグ一覧 +- `/tags//` — タグ別Notes等の一覧 -`content/notes/_index.md` を作成する。 +### 4.2 グローバルナビゲーション -例: +Headerに以下を表示する。 -```toml -+++ -title = "Notes" -sort_by = "date" -template = "notes.html" -page_template = "note-page.html" -+++ -``` +- Home +- Notes +- Software +- About -新しいNoteは `content/notes/*.md` を追加するだけで一覧へ反映されること。 +Source/cgitへのリンクはグローバルナビゲーションには常設せず、Software内で案内する。 --- -# 7. Page設計 - -## 7.1 Project Page +## 5. Home仕様 -Projectは1 Markdown = 1 Zola Pageとする。 +### 5.1 役割 -例: +Homeはサイト全体の入口・索引として機能する。 -```toml -+++ -title = "Example Project" -date = 2026-08-21 -description = "Project description" +ポートフォリオ用の大きなHero、自己宣伝CTA、プロフィール写真などは必須としない。 -[extra] -status = "active" -repository = "https://example.invalid/" -+++ -``` +### 5.2 表示内容 -Zola標準front matterで直接扱えないプロジェクト固有metadataは `[extra]` を使用する。 +以下の順序を基本とする。 -最低限以下を扱えるようにする。 +1. サイト名 +2. 短い説明文 +3. 最近のNotes +4. Software +5. サイトについての短い説明 +6. Aboutへの導線 -* `title` -* `date` -* `description` +### 5.3 トップ説明文 -Project固有情報: +初期文言： -* `extra.status` -* `extra.repository` +> 日々考えたこととか思ったことを記録します -必要なら以下も追加可能。 +将来文言を修正できること。 -* `extra.homepage` -* `extra.language` -* `extra.license` +### 5.4 最近のNotes -metadataを過剰に増やさないこと。 +初期表示件数は **5件** とする。 ---- +各項目には以下を表示する。 -## 7.2 Note Page +- 公開日 +- タイトル +- 必要に応じ短いdescription -例: +Homeでは情報量を抑え、本文を直接大量表示しない。 -```toml -+++ -title = "Example Note" -date = 2026-08-21 -description = "Note description" -+++ +### 5.5 Software -本文... -``` +初期表示件数は **4件** とする。 -本文はZolaの `page.content` としてtemplateから表示する。 +Homeでは原則としてSoftware名を中心に表示する。 --- -# 8. Templates +## 6. Notes仕様 -Zola公式ドキュメントのtemplate inheritanceを利用する。 +### 6.1 Notesの定義 -最低限以下を構成する。 +文章として残したい内容は原則としてNotesとして扱う。 -```text -templates/ -├── base.html -├── index.html -├── projects.html -├── project-page.html -├── notes.html -├── note-page.html -└── page.html -``` +技術メモ、読書記録、調査、考察、論考を別々のコンテンツ型へ過度に分割しない。 -必要であれば以下を追加する。 +### 6.2 Notes一覧 -```text -templates/ -└── partials/ - ├── header.html - ├── navigation.html - └── footer.html -``` +Notes一覧は **年別アーカイブ** とする。 -`base.html` を共通レイアウトとし、各templateはTeraの +例： -```text -{% extends "base.html" %} -``` - -およびblockを使用する。 - ---- +- 2026 + - 08-21 記事タイトル + - 05-03 記事タイトル +- 2025 + - ... -# 9. Internal Link方針 +年は新しい順、各年内も原則として公開日の新しい順に表示する。 -サイト内部リンクは、可能な限りURL文字列をハードコードせず、Zolaの `get_url` と `@/` internal link記法を使用する。 +### 6.3 Notes一覧に表示する情報 -例: +- 公開日 +- タイトル +- タグ +- 必要に応じdescription -```tera -Projects -``` +タグはNotes一覧およびタグ一覧で表示する。 -これによりcontent path変更時のリンク破損を減らす。 +### 6.4 Note詳細 ---- +Note詳細では以下を表示する。 -# 10. Home Page +- タイトル +- 公開日 +- 更新日（存在する場合） +- 目次 +- 本文 +- 脚注 +- 参考文献 +- 関連Software（設定されている場合） +- 前後の記事導線は必須としない -Homeは `templates/index.html` で生成する。 +タグはNote詳細の主要表示項目にしない。 -最低限以下を表示可能にする。 +### 6.5 目次 -* サイト名 -* 簡単な説明 -* Aboutへのリンク -* Projectsへのリンク -* Notesへのリンク +Note詳細では **目次を常時表示**する。 -Home用の不要なCMS的データ構造は作らない。 +Sidebarは使わないため、本文冒頭付近にインラインで配置する。 -必要なら `zola.toml` の `extra` をサイト全体metadataとして使用してよい。 +見出しが存在しない場合は空の目次領域を表示しない。 ---- +### 6.6 脚注 -# 11. Sass / SCSS +Markdown/Zola標準機能による脚注を日常的に利用できること。 -Zola標準Sass compilationを使用する。 +脚注の見た目を本文と一貫させる。 -`zola.toml`: +### 6.7 参考文献 -```toml -compile_sass = true -``` +長文記事の末尾にReferences/参考文献セクションを設けられること。 -構成例: +参考文献は通常のMarkdownで記述可能とし、共通の見た目を持つ。 -```text -sass/ -├── main.scss -├── _variables.scss -├── _base.scss -├── _typography.scss -├── _layout.scss -└── _components.scss -``` +### 6.8 公開日と更新日 -npm Sass / Dart Sass / PostCSS等は追加しない。 +- 公開日は必須 +- 更新日は任意 +- 更新日が存在する場合は公開日とともに表示する ---- +### 6.9 記事の成熟度 -# 12. Static assets +Draft / Note / Essay 等の成熟度・状態ラベルは導入しない。 -Zolaの `static/` はbuild時に出力先へそのままコピーされる前提で使用する。 +Zola内部のdraft機能は公開制御に使用してよいが、利用者向けの成熟度表示は行わない。 -例: +--- -```text -static/ -├── favicon.svg -├── robots.txt -├── images/ -└── js/ - └── site.js -``` +## 7. Tags仕様 -外部CDN依存を原則禁止する。 +### 7.1 分類方針 -JavaScriptが必要な場合は `static/js/site.js` 等として自前配信する。 +初期実装ではカテゴリを設けず、**tagsのみ**を使用する。 ---- +### 7.2 タグの目的 -# 13. JavaScript +- 分野横断の記事を柔軟に分類する +- 同じテーマの記事を探せるようにする +- 固定カテゴリ階層を避ける -JavaScriptは必要最小限の vanilla JavaScript のみ使用する。 +### 7.3 想定タグ例 -以下の原則に従う。 +- 情報工学 +- 論理学 +- 資本論 +- 政治経済 +- 地球環境 +- AI +- LLM +- 読書 +- Windows +- Git -1. HTML標準機能で実現可能ならJSを使用しない。 -2. CSSのみで実現可能ならJSを使用しない。 -3. 外部frontend frameworkを導入しない。 -4. inline event handlerを使用しない。 -5. `eval()` を使用しない。 -6. JavaScript無効でも主要コンテンツを閲覧可能にする。 +タグ語彙はコンテンツ追加に応じて増やす。 --- -# 14. Syntax Highlighting - -技術記事用のコードブロックsyntax highlightingにはZola標準機能を使用する。 +## 8. Software仕様 -独自のPrism.js / highlight.js等は初期実装では導入しない。 +### 8.1 役割 -設定は採用するZola versionの公式configuration仕様に従うこと。 +Softwareは作成したソフトウェアを人間向けに説明する場所とする。 ---- +ソースコードそのものの閲覧・履歴表示はcgitへ委ねる。 -# 15. Feeds +### 8.2 Software一覧 -NotesについてRSS/Atom等のfeedを生成する。 +一覧では情報量を抑え、**Software名を主表示**とする。 -Zola標準feed生成機能を使用する。 +必要に応じ短いdescriptionを添えてよいが、画像や大量のmetadataは表示しない。 -独自feed generatorは実装しない。 +### 8.3 Software詳細 -採用するZola versionにおける推奨設定を確認して実装すること。 +以下の情報を扱えること。 ---- +- Software名 +- 概要 +- 作成した背景・目的 +- 開発・制作の過程 +- 特徴 +- 使用言語 +- ライセンス +- Source（自前cgit） +- GitHub mirror（存在する場合） +- 関連Notes +- スクリーンショット（必要な場合のみ） -# 16. Sitemap +Implementation detailsは本文中で必要な範囲だけ記述し、固定項目として過剰に構造化しない。 -Zola標準のsitemap生成機能を使用する。 +### 8.4 Sourceの優先順位 -独自 `sitemap.xml` generatorは作らない。 +ソースコードの正本は **自前cgit** とする。 ---- +Software詳細では以下の順で扱う。 -# 17. robots.txt +1. Source — cgit +2. GitHub mirror — 当面維持 -Zolaの標準 `robots.txt` template機能または `static/robots.txt` のうち、公式ドキュメントに沿った単純な方法を採用する。 +### 8.5 スクリーンショット -不要な独自処理を作らない。 +- Software一覧では表示しない +- Software詳細で必要な場合のみ表示する +- 画像が多くなり本文の可読性を損なわないようにする --- -# 18. 404 Page +## 9. NotesとSoftwareの関連付け -Zola標準の404 template仕様に従って実装する。 +NotesとSoftwareは相互に関連付けられること。 -想定: +例： -```text -templates/404.html -``` +- Softwareから関連Notesへ +- Noteから関連Softwareへ -Caddyから静的404として扱える成果物を生成する。 +関連付けは明示的に管理し、単なるタグ一致だけで自動的に関連付けない。 --- -# 19. Search +## 10. About仕様 -初期実装では検索を無効とする。 +Aboutには以下を掲載する。 -`zola init` / configuration上もsearch indexを生成しない設定とする。 +- 名前 +- 一言プロフィール +- このサイトの目的 +- 主な関心分野 +- 連絡先 -将来必要になった場合のみZola標準search indexを再検討する。 - -外部検索libraryは現時点では導入しない。 +職務経歴書・詳細な履歴書としては設計しない。 --- -# 20. Themes +## 11. Header仕様 -Zolaは `themes/` を標準で持つが、本プロジェクトでは外部themeを原則使用しない。 +### 11.1 表示内容 -理由: +- サイト名「たかしの記録」 +- Home +- Notes +- Software +- About +- Dark/Light theme切替（提供する場合） -* supply-chain面積を増やさない -* upstream theme更新への依存を避ける -* CSS/templateを完全に管理可能にする -* 不要なJavaScriptを取り込まない +### 11.2 レイアウト -したがって自前template + 自前SCSSを基本とする。 +- 高さを抑える +- サイト本文より主張しない +- DesktopとMobileの双方で簡潔に表示 +- 必要でなければHamburger menuは使用しない --- -# 21. Zola Configuration - -設定ファイル名は公式構成に合わせて、 - -```text -zola.toml -``` +## 12. Footer仕様 -を使用する。 +Footerには最低限以下を表示する。 -最低限: +- Copyright +- RSS +- Mail -```toml -base_url = "https://www.takashi-2521.com" -compile_sass = true -build_search_index = false -``` +cgitリンクはSoftware側で扱う。 -実際のsyntax highlighting、feed、taxonomy等については、使用するZola versionの公式documentationを確認して正しいconfiguration keyを使用すること。 +--- -推測で設定名を追加しないこと。 +## 13. Typography仕様 ---- +### 13.1 本文 -# 22. Development +Sans-serifを使用する。 -ローカル開発ではZola標準development serverを使用する。 +Web fontは外部取得せず、system font stackを使用する。 -```bash -zola serve -``` +### 13.2 UI -Zolaは `zola.toml`, `content`, `sass`, `static`, `templates` の変更を監視し、local live reloadに使用できる。 +Sans-serif + Monospaceを役割分担して使用する。 -追加のdev serverは作成しない。 +Monospaceは以下のような補助情報に使用できる。 ---- +- 日付 +- metadata +- ラベル +- コード +- 技術的な短い補助情報 -# 23. Validation / Build +### 13.3 コード -実装中は以下を使用する。 +system monospaceを使用する。 -```bash -zola check -zola build -``` +--- -local preview: +## 14. 色・テーマ仕様 -```bash -zola serve -``` +### 14.1 Light theme -build output: +- 紙に近い暖かみのある明るい背景 +- ほぼ黒の本文 +- muted gray +- 薄い罫線 +- 青をaccent/link色として使用 -```text -public/ -``` +### 14.2 Dark theme -`public/` のみでサイトが成立すること。 +Dark modeに対応する。 ---- +- 真っ黒ではなく濃いgrayを基本 +- 明るい本文 +- muted gray +- dark border +- light themeと対応する青系accent -# 24. Git +### 14.3 Accent -sourceのみGit管理する。 +Accentは青系1色を基本とする。 -`.gitignore`: +具体的な色値はDesignで定義する。 -```gitignore -/public/ -``` +--- -Zolaが実際に生成しない独自cache directoryを推測で追加しないこと。 +## 15. リンク仕様 -Editor / OS固有ファイルは必要に応じて追加可能。 +- 通常リンクは青 +- 原則として下線を付け、リンクであることを明確にする +- Hoverでは色等を軽く変える +- 大きなアニメーションを付けない +- 外部リンクには `↗` 等の簡潔な外部リンク記号を表示する +- 外部アイコンライブラリは使用しない --- -# 25. Deployment境界 +## 16. Layout仕様 -本仕様ではVPS側の配信基盤は変更しない。 +- Sidebarなし +- Main contentを中央付近に配置 +- 長文は左右に十分な余白を確保 +- 最大本文幅はDesign段階で具体値を定義 +- Desktopでは広すぎない +- Mobileでは横スクロールを発生させない +- コードブロック等、必要な要素のみ内部横スクロールを許容 -既存: +--- -```text -/srv/www/takashi-2521.com/ -├── releases/ -└── current -> releases/ -``` +## 17. Motion仕様 -Caddy: +Animationは原則使用しない。 -```text -root * /srv/www/takashi-2521.com/current -``` +以下も初期実装では不要。 -クライアント側では将来、 +- View Transition +- Parallax +- Scroll animation +- Fade-in animation +- Decorative motion -```text -zola check -→ zola build -→ public/ -→ archive -→ SSH transfer -→ releases/ -→ current切替 -``` +--- -を行う。 +## 18. 画像仕様 -本Client Phaseでは `public/` が自己完結したbuild artifactになることを保証する。 +- 画像は最小限 +- Homeに装飾目的の大量画像を置かない +- Notesでは説明に必要な画像のみ +- Softwareでは詳細ページのみ +- 外部画像hotlinkを原則避ける +- 代替テキストを付与する --- -# 26. Security Requirements - -必須: +## 19. Feed仕様 -* npmを使用しない -* Node.js dependencyを使用しない -* React/Vue/Svelteを使用しない -* htmxを使用しない -* Tailwindを使用しない -* 外部CDNを使用しない -* external themeを原則使用しない -* backendを実装しない -* DBを使用しない -* buildをVPSで実行しない +以下を提供する。 -可能な限り以下のCSPと互換な構造にする。 +- Atom +- RSS -```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'; -``` +HeaderまたはFooterから購読導線を用意する。 -inline script / inline event handlerは避ける。 +Feed autodiscoveryに対応する。 --- -# 27. Accessibility +## 20. Search仕様 -最低限以下を満たす。 +初期リリースではSearchを提供しない。 -* semantic HTML -* 正しいheading hierarchy -* keyboard navigation -* visible focus -* alt text -* color contrast -* `prefers-reduced-motion` を考慮 -* JSなしでも主要navigationが利用可能 +将来の記事数増加に応じて、Zolaの検索インデックス機能を第一候補として追加検討する。 --- -# 28. Client Phase +## 21. Comments仕様 -## Client-1: Zola initialization +初期リリースではコメント機能を提供しない。 -* Zola version確認 -* `zola init` 相当の標準構成を確認 -* `zola.toml` -* 標準directory作成 -* `zola check` -* `zola build` +理由： -PASS: +- 完全静的構成では保存先が存在しない +- 自前backendを追加すると現行セキュリティ境界が変化する +- 外部コメントサービスは外部依存・プライバシーの再検討が必要 -```text -zola check PASS -zola build PASS -public/index.html exists -``` +将来機能として、以下を別途評価する。 ---- +- 自前軽量コメントbackend +- Gitベース方式 +- 外部コメントサービス +- Mailによる感想受付 -## Client-2: Section / Page architecture +--- -* Home -* About Page -* Projects Section -* Project Pages -* Notes Section -* Note Pages +## 22. SNS共有仕様 -PASS: +初期リリースでは大きなSNS共有ボタン群を必須としない。 -```text -/ - /about/ - /projects/ - /projects// - /notes/ - /notes// -``` +外部dependencyを追加せず、簡潔なテキストリンクまたはWeb Share API等だけで実現できる場合に追加を検討する。 -が生成される。 +サイトのEditorialデザインを損なわないことを優先する。 --- -## Client-3: Tera templates / UI +## 23. Analytics仕様 -* `base.html` -* template inheritance -* navigation -* header/footer -* SCSS -* responsive layout +アクセス解析は導入しない。 -PASS: +- 外部Analytics scriptなし +- Tracking cookieなし +- Marketing trackerなし -* Desktop正常 -* Mobile正常 -* internal navigation正常 +Webサーバの運用ログはサーバ運用上のログであり、サイト機能としてのアクセス解析とは扱わない。 --- -## Client-4: Content model +## 24. URL仕様 -Projects/NotesをZola Pageとして管理する。 +### 24.1 URL構造 -PASS: +- `/notes//` +- `/software//` +- `/tags//` +- `/about/` -Markdownを1件追加すると、 +### 24.2 Slug -```text -Section listing -+ -individual Page -``` +Content filename / slugは **英語ASCIIを基本**とする。 -の両方へ自動反映される。 +記事本文や表示タイトルは日本語でよい。 ---- - -## Client-5: Zola static features - -* syntax highlighting -* feed -* sitemap -* robots.txt -* 404 -* favicon +URLの安定性を優先し、公開後のslug変更は原則避ける。 -Zola標準機能を優先する。 +--- -PASS: +## 25. 日本語・多言語仕様 -`zola build` の成果物に必要な静的ファイルが生成される。 +- 表示言語は日本語のみ +- UI文言も日本語 +- 初期設計では多言語対応を実装しない +- 多言語化のための不要なUIやselectorは設けない --- -## Client-6: Git / final validation +## 26. Accessibility要求 -* `.gitignore` -* sourceのみGit管理 -* external dependenciesなし -* final `zola check` -* final `zola build` +最低限以下を満たす。 ---- +- Semantic HTML +- 適切なheading hierarchy +- Keyboard navigation +- Visible focus +- 十分な色contrast +- 画像alt +- Linkが色だけで判別不能にならない +- HTML/主要navigationはJavaScriptなしでも利用可能 +- Theme切替機能がなくてもOS themeで十分読めること +- prefers-reduced-motionを尊重（原則motion自体を使用しない） + +--- + +## 27. Performance要求 + +サイトは静的HTML/CSS/最小JSのみで成立すること。 -# 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" +- Backend runtime不要 +- DB不要 +- npm/Node.js不要 +- 外部CDN不要 +- Web font不要 +- 大きなfrontend framework不要 +- 初期表示に不要な画像を読み込まない +- JavaScriptが無効でも主要本文が読める + +--- + +## 28. Security / Privacy要求 + +- npm package dependencyを使用しない +- Node.js runtimeを使用しない +- 外部themeを原則使用しない +- 外部JavaScript CDNを使用しない +- Inline JavaScriptを避ける +- `eval()` を使用しない +- 外部trackingを使用しない +- CSP `default-src 'self'` を中心とした厳格な設定と互換性を持つ +- Static Siteとして本番にserver-side codeを置かない +- Caddyは生成済み成果物のみを配信する + +--- + +## 29. 技術基盤に関する制約 + +以下はDesignに委ねるが、要求上の前提とする。 + +- SSG: Zola +- Template: Tera +- Content: Markdown +- Style: SCSS +- Client JS: minimal vanilla JavaScript +- Production: Caddy static file server +- Build: Client PC +- Deployment: `public/` build artifactをVPSへ転送 +- Git source管理とDeployは独立 +- cgitをソースコード正本とする + +--- + +## 30. 初期リリースの非目標 + +以下は初期リリースで実装しない。 + +- コメント +- Search +- CMS +- User login +- Database +- SSR +- SPA +- API backend +- WebSocket +- Analytics +- Frontend framework +- htmx +- Tailwind CSS +- npm/Node.js +- External theme +- Heavy animation +- Large image gallery +- Multilingual UI + +--- + +## 31. 受入条件 + +初期リリースは以下を満たすこと。 + +- [ ] 「たかしの記録」というサイト名が表示される +- [ ] Home / Notes / Software / Aboutへ到達可能 +- [ ] Homeに最近のNotes最大5件を表示 +- [ ] HomeにSoftware最大4件を表示 +- [ ] Notesが年別に表示される +- [ ] Notes一覧にタグが表示される +- [ ] Note詳細に公開日・更新日・目次・本文を表示できる +- [ ] 脚注を利用できる +- [ ] 参考文献を自然に表示できる +- [ ] Software一覧を画像なしの簡潔な一覧として表示 +- [ ] Software詳細に背景・過程・言語・ライセンス・Source等を記載できる +- [ ] cgitをSource正本として案内できる +- [ ] GitHub mirrorを任意表示できる +- [ ] NoteとSoftwareを明示的に相互関連付けできる +- [ ] Aboutに名前・一言プロフィール・目的・関心分野・連絡先を表示できる +- [ ] Light/Dark双方で読める +- [ ] 外部リンクを視覚的に判別できる +- [ ] RSSとAtomを提供 +- [ ] 404ページを提供 +- [ ] Mobile/Desktop双方で利用可能 +- [ ] JavaScriptなしでも主要コンテンツを閲覧可能 +- [ ] 外部CDN・npm・Node.js・frontend frameworkを必要としない +- [ ] サイト全体が静的ファイルとして生成可能 + +--- + +## 32. 将来拡張 + +要件変更時に別途設計する。 + +- Search +- Comments +- SNS共有 +- より高度な関連コンテンツ表示 +- タグ数増加へのUI改善 +- Page pagination +- 多言語 +- 画像処理の高度化 + +初期実装で将来拡張のための複雑な抽象化を先行導入しない。 -- cgit v1.2.3