# Specifications.md # たかしの記録 — 要求仕様書 ## 1. 文書目的 本書は、個人Webサイト「たかしの記録」の利用者視点・コンテンツ視点での要求仕様を定義する。 本書では「何を提供するサイトか」「誰がどのように読むか」「どの情報をどのように見せるか」を定義し、具体的なZola/Tera/SCSS実装方法は `Design.md` に委ねる。 --- ## 2. サイト概要 ### 2.1 サイト名 **たかしの記録** ### 2.2 サイトの目的 本サイトは、運営者が日頃考えたこと・感じたこと・調べたことを記録し、作成したソフトウェアとともに長期的に保存・公開する個人アーカイブである。 主な用途は次のとおり。 - 日々考えたことや感じたことの記録 - 読書を通じて考えたことの記録 - 技術調査・技術メモの公開 - 長文記事・考察の公開 - 作成したソフトウェアの紹介 - ソフトウェア制作の背景・過程・設計意図の記録 - ソフトウェアに関連する技術記事との相互参照 ### 2.3 主な対象分野 Notesでは特定分野に限定せず、少なくとも以下を扱う。 - 情報工学・ソフトウェア - 論理学 - マルクス・資本論・政治経済 - 地球環境 - 読書を通じた考察 - 上記にまたがる複合的なテーマ 分類は固定カテゴリではなくタグを基本とし、分野横断の記事を許容する。 ### 2.4 想定読者 - 運営者本人 - ソフトウェアエンジニア - 技術分野に関心のある一般読者 - 学生 - 個々の記事テーマに関心のある一般人 専門読者だけに限定せず、記事冒頭で主題を把握できることを重視する。 ### 2.5 更新頻度 通常は **2〜3か月に1〜2回程度** を想定する。 更新頻度を競うニュースサイトやSNSではなく、長期間残るアーカイブとして設計する。 --- ## 3. サイトの基本コンセプト ### 3.1 中心コンテンツ サイトの主役は以下の2つとする。 1. **Notes** 2. **Software** HomeとAboutは、この2つへの入口・補助情報として扱う。 ### 3.2 デザインコンセプト デザインは **Minimal Editorial Archive** を基本とする。 方向性は以下。 - 文章とリンクを主役にする - 装飾を抑える - 罫線・余白・タイポグラフィで情報階層を表現する - カードUIを乱用しない - 画像を主役にしない - 技術者向けダッシュボード風・SaaSランディングページ風にしない - 長文を落ち着いて読める - 更新間隔が長くても「止まったサイト」に見えにくい - Gwern.netの長文アーカイブ性とSimon Willison's Weblogの実用的な情報構造を参考にする ### 3.3 基本画面構造 全画面の基本構造は以下。 - 小さなHeader - Main content - 小さなFooter Header/Footerは本文より目立たせず、高さも必要以上に取らない。 Sidebarは使用しない。 --- ## 4. 情報アーキテクチャ ### 4.1 グローバル構成 トップレベルは以下を基本とする。 - `/` — Home - `/notes/` — Notes一覧 - `/software/` — Software一覧 - `/about/` — About - `/tags/` — タグ一覧 - `/tags//` — タグ別Notes等の一覧 ### 4.2 グローバルナビゲーション Headerに以下を表示する。 - Home - Notes - Software - About Source/cgitへのリンクはグローバルナビゲーションには常設せず、Software内で案内する。 --- ## 5. Home仕様 ### 5.1 役割 Homeはサイト全体の入口・索引として機能する。 ポートフォリオ用の大きなHero、自己宣伝CTA、プロフィール写真などは必須としない。 ### 5.2 表示内容 以下の順序を基本とする。 1. 短い説明文 2. 最近のNotes 3. Software 4. サイトについての短い説明 5. Aboutへの導線 サイト名はHeaderに表示されるため、Home本文では重複表示しない。 ### 5.3 トップ説明文 初期文言： > 日々考えたこととか思ったことを記録します 将来文言を修正できること。 ### 5.4 最近のNotes 初期表示件数は **5件** とする。 各項目には以下を表示する。 - 公開日 - タイトル - 必要に応じ短いdescription Homeでは情報量を抑え、本文を直接大量表示しない。 ### 5.5 Software 初期表示件数は **4件** とする。 Homeでは原則としてSoftware名を中心に表示する。 --- ## 6. Notes仕様 ### 6.1 Notesの定義 文章として残したい内容は原則としてNotesとして扱う。 技術メモ、読書記録、調査、考察、論考を別々のコンテンツ型へ過度に分割しない。 ### 6.2 Notes一覧 Notes一覧は **年別アーカイブ** とする。 例： - 2026 - 08-21 記事タイトル - 05-03 記事タイトル - 2025 - ... 年は新しい順、各年内も原則として公開日の新しい順に表示する。 ### 6.3 Notes一覧に表示する情報 - 公開日 - タイトル - タグ - 必要に応じdescription タグはNotes一覧およびタグ一覧で表示する。 ### 6.4 Note詳細 Note詳細では以下を表示する。 - タイトル - 公開日 - 更新日（存在する場合） - 目次 - 本文 - 脚注 - 参考文献 - 関連Software（設定されている場合） - 前後の記事導線は必須としない タグはNote詳細の主要表示項目にしない。 ### 6.5 目次 Note詳細では **目次を常時表示**する。 Sidebarは使わないため、本文冒頭付近にインラインで配置する。 見出しが存在しない場合は空の目次領域を表示しない。 ### 6.6 脚注 Markdown/Zola標準機能による脚注を日常的に利用できること。 脚注の見た目を本文と一貫させる。 ### 6.7 参考文献 長文記事の末尾にReferences/参考文献セクションを設けられること。 参考文献は通常のMarkdownで記述可能とし、共通の見た目を持つ。 ### 6.8 公開日と更新日 - 公開日は必須 - 更新日は任意 - 更新日が存在する場合は公開日とともに表示する ### 6.9 記事の成熟度 Draft / Note / Essay 等の成熟度・状態ラベルは導入しない。 Zola内部のdraft機能は公開制御に使用してよいが、利用者向けの成熟度表示は行わない。 --- ## 7. Tags仕様 ### 7.1 分類方針 初期実装ではカテゴリを設けず、**tagsのみ**を使用する。 ### 7.2 タグの目的 - 分野横断の記事を柔軟に分類する - 同じテーマの記事を探せるようにする - 固定カテゴリ階層を避ける ### 7.3 想定タグ例 - 情報工学 - 論理学 - 資本論 - 政治経済 - 地球環境 - AI - LLM - 読書 - Windows - Git タグ語彙はコンテンツ追加に応じて増やす。 --- ## 8. Software仕様 ### 8.1 役割 Softwareは作成したソフトウェアを人間向けに説明する場所とする。 ソースコードそのものの閲覧・履歴表示はcgitへ委ねる。 ### 8.2 Software一覧 一覧では情報量を抑え、**Software名を主表示**とする。 必要に応じ短いdescriptionを添えてよいが、画像や大量のmetadataは表示しない。 ### 8.3 Software詳細 以下の情報を扱えること。 - Software名 - 概要 - 作成した背景・目的 - 開発・制作の過程 - 特徴 - 使用言語 - ライセンス - Source（自前cgit） - GitHub mirror（存在する場合） - 関連Notes - スクリーンショット（必要な場合のみ） Implementation detailsは本文中で必要な範囲だけ記述し、固定項目として過剰に構造化しない。 ### 8.4 Sourceの優先順位 ソースコードの正本は **自前cgit** とする。 Software詳細では以下の順で扱う。 1. Source — cgit 2. GitHub mirror — 当面維持 ### 8.5 スクリーンショット - Software一覧では表示しない - Software詳細で必要な場合のみ表示する - 画像が多くなり本文の可読性を損なわないようにする --- ## 9. NotesとSoftwareの関連付け NotesとSoftwareは相互に関連付けられること。 例： - Softwareから関連Notesへ - Noteから関連Softwareへ 関連付けは明示的に管理し、単なるタグ一致だけで自動的に関連付けない。 --- ## 10. About仕様 Aboutには以下を掲載する。 - 名前 - 一言プロフィール - このサイトの目的 - 主な関心分野 - 連絡先 職務経歴書・詳細な履歴書としては設計しない。 --- ## 11. Header仕様 ### 11.1 表示内容 - サイト名「たかしの記録」 - Home - Notes - Software - About - Dark/Light theme切替（提供する場合） ### 11.2 レイアウト - 高さを抑える - サイト本文より主張しない - DesktopとMobileの双方で簡潔に表示 - 必要でなければHamburger menuは使用しない --- ## 12. Footer仕様 Footerには最低限以下を表示する。 - Copyright - RSS - Mail cgitリンクはSoftware側で扱う。 --- ## 13. Typography仕様 ### 13.1 本文 Sans-serifを使用する。 Web fontは外部取得せず、system font stackを使用する。 ### 13.2 UI Sans-serif + Monospaceを役割分担して使用する。 Monospaceは以下のような補助情報に使用できる。 - 日付 - metadata - ラベル - コード - 技術的な短い補助情報 ### 13.3 コード system monospaceを使用する。 --- ## 14. 色・テーマ仕様 ### 14.1 Light theme - 紙に近い暖かみのある明るい背景 - ほぼ黒の本文 - muted gray - 薄い罫線 - 青をaccent/link色として使用 ### 14.2 Dark theme Dark modeに対応する。 - 真っ黒ではなく濃いgrayを基本 - 明るい本文 - muted gray - dark border - light themeと対応する青系accent ### 14.3 Accent Accentは青系1色を基本とする。 具体的な色値はDesignで定義する。 --- ## 15. リンク仕様 - 通常リンクは青 - 原則として下線を付け、リンクであることを明確にする - Hoverでは色等を軽く変える - 大きなアニメーションを付けない - 外部リンクには `↗` 等の簡潔な外部リンク記号を表示する - 外部アイコンライブラリは使用しない --- ## 16. Layout仕様 - Sidebarなし - Main contentを中央付近に配置 - 長文は左右に十分な余白を確保 - 最大本文幅はDesign段階で具体値を定義 - Desktopでは広すぎない - Mobileでは横スクロールを発生させない - コードブロック等、必要な要素のみ内部横スクロールを許容 --- ## 17. Motion仕様 Animationは原則使用しない。 以下も初期実装では不要。 - View Transition - Parallax - Scroll animation - Fade-in animation - Decorative motion --- ## 18. 画像仕様 - 画像は最小限 - Homeに装飾目的の大量画像を置かない - Notesでは説明に必要な画像のみ - Softwareでは詳細ページのみ - 外部画像hotlinkを原則避ける - 代替テキストを付与する --- ## 19. Feed仕様 以下を提供する。 - Atom - RSS HeaderまたはFooterから購読導線を用意する。 Feed autodiscoveryに対応する。 --- ## 20. Search仕様 初期リリースではSearchを提供しない。 将来の記事数増加に応じて、Zolaの検索インデックス機能を第一候補として追加検討する。 --- ## 21. Comments仕様 初期リリースではコメント機能を提供しない。 理由： - 完全静的構成では保存先が存在しない - 自前backendを追加すると現行セキュリティ境界が変化する - 外部コメントサービスは外部依存・プライバシーの再検討が必要 将来機能として、以下を別途評価する。 - 自前軽量コメントbackend - Gitベース方式 - 外部コメントサービス - Mailによる感想受付 --- ## 22. SNS共有仕様 初期リリースでは大きなSNS共有ボタン群を必須としない。 外部dependencyを追加せず、簡潔なテキストリンクまたはWeb Share API等だけで実現できる場合に追加を検討する。 サイトのEditorialデザインを損なわないことを優先する。 --- ## 23. Analytics仕様 アクセス解析は導入しない。 - 外部Analytics scriptなし - Tracking cookieなし - Marketing trackerなし Webサーバの運用ログはサーバ運用上のログであり、サイト機能としてのアクセス解析とは扱わない。 --- ## 24. URL仕様 ### 24.1 URL構造 - `/notes//` - `/software//` - `/tags//` - `/about/` ### 24.2 Slug Content filename / slugは **英語ASCIIを基本**とする。 記事本文や表示タイトルは日本語でよい。 URLの安定性を優先し、公開後のslug変更は原則避ける。 --- ## 25. 日本語・多言語仕様 - 表示言語は日本語のみ - UI文言も日本語 - 初期設計では多言語対応を実装しない - 多言語化のための不要なUIやselectorは設けない --- ## 26. Accessibility要求 最低限以下を満たす。 - 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のみで成立すること。 - 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 - 多言語 - 画像処理の高度化 初期実装で将来拡張のための複雑な抽象化を先行導入しない。