diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Design.md | 2054 | ||||
| -rw-r--r-- | doc/Specifications.md | 881 |
2 files changed, 535 insertions, 2400 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構成 | diff --git a/doc/Specifications.md b/doc/Specifications.md index 1cffd4a..86a6a2f 100644 --- a/doc/Specifications.md +++ b/doc/Specifications.md @@ -1,721 +1,210 @@ -# Specifications.md - # たかしの記録 — 要求仕様書 -## 1. 文書目的 - -本書は、個人Webサイト「たかしの記録」の利用者視点・コンテンツ視点での要求仕様を定義する。 +## 1. 文書の役割 -本書では「何を提供するサイトか」「誰がどのように読むか」「どの情報をどのように見せるか」を定義し、具体的なZola/Tera/SCSS実装方法は `Design.md` に委ねる。 +本書は、個人サイト「たかしの記録」が利用者へ提供する内容と体験を定義する。対象はサイトの目的、掲載情報、閲覧導線、品質方針であり、実装技術や内部構造は扱わない。 ---- +技術選定、ファイル構成、コンテンツ形式、画面生成、スタイル、ビルドおよび検証方法は[Design.md](Design.md)に記載する。 ## 2. サイト概要 -### 2.1 サイト名 - -**たかしの記録** - -### 2.2 サイトの目的 +| 項目 | 内容 | +|---|---| +| サイト名 | たかしの記録 | +| 公開URL | `https://www.takashi-2521.com` | +| 言語 | 日本語 | +| 運営者 | Takashi | +| 主な内容 | 日々考えたこと、調べたこと、作成したソフトウェア | +| 更新方針 | 更新頻度を固定せず、残す価値のある内容を公開する | -本サイトは、運営者が日頃考えたこと・感じたこと・調べたことを記録し、作成したソフトウェアとともに長期的に保存・公開する個人アーカイブである。 +## 3. コンセプト -主な用途は次のとおり。 +### 3.1 目的 -- 日々考えたことや感じたことの記録 -- 読書を通じて考えたことの記録 -- 技術調査・技術メモの公開 -- 長文記事・考察の公開 -- 作成したソフトウェアの紹介 -- ソフトウェア制作の背景・過程・設計意図の記録 -- ソフトウェアに関連する技術記事との相互参照 +このサイトは、文章とソフトウェアに関する記録を、あとから読み返せる形で長期的に公開する個人アーカイブである。 -### 2.3 主な対象分野 +### 3.2 基本方針 -Notesでは特定分野に限定せず、少なくとも以下を扱う。 +| ID | 方針 | +|---|---| +| C-01 | 更新の速さや量より、記録を継続して残せることを優先する。 | +| C-02 | 短いメモと長い考察を同じNotesとして扱い、分野を過度に限定しない。 | +| C-03 | Softwareでは成果物だけでなく、背景、判断、制作過程も説明する。 | +| C-04 | 余白、文字、罫線を中心とした静かな編集デザインを採用する。 | +| C-05 | 広告、反応数、推薦表示など、本文の読解を妨げる要素を置かない。 | +| C-06 | ソースコードは自分で管理するGitリポジトリを正本とし、cgitで公開する。外部サービスは必要に応じてミラーとして利用する。 | -- 情報工学・ソフトウェア -- 論理学 -- マルクス・資本論・政治経済 -- 地球環境 -- 読書を通じた考察 -- 上記にまたがる複合的なテーマ - -分類は固定カテゴリではなくタグを基本とし、分野横断の記事を許容する。 - -### 2.4 想定読者 +### 3.3 想定読者 - 運営者本人 -- ソフトウェアエンジニア -- 技術分野に関心のある一般読者 -- 学生 -- 個々の記事テーマに関心のある一般人 - -専門読者だけに限定せず、記事冒頭で主題を把握できることを重視する。 - -### 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/<tag>/` — タグ別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/<slug>/` -- `/software/<slug>/` -- `/tags/<slug>/` -- `/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のみで成立すること。 +## 4. 情報構成 -- Backend runtime不要 -- DB不要 -- npm/Node.js不要 -- 外部CDN不要 -- Web font不要 -- 大きなfrontend framework不要 -- 初期表示に不要な画像を読み込まない -- JavaScriptが無効でも主要本文が読める +| 領域 | 利用者に提供する役割 | +|---|---| +| Home | 最近のNotesとSoftwareへ案内する。 | +| Notes | 考えたこと、感じたこと、調べたことを時系列で公開する。 | +| Tags | タグ付きのNotesがある場合、主題ごとに横断して探せる索引を提供する。 | +| Software | 作成したソフトウェアと、その背景や過程を公開する。 | +| About | 運営者、このサイトの目的、連絡先を示す。 | ---- +主要な移動先はHeaderから常に利用できるようにする。Feedとメールへの導線はFooterから提供する。 -## 28. Security / Privacy要求 +## 5. ページ別要求 -- npm package dependencyを使用しない -- Node.js runtimeを使用しない -- 外部themeを原則使用しない -- 外部JavaScript CDNを使用しない -- Inline JavaScriptを避ける -- `eval()` を使用しない -- 外部trackingを使用しない -- CSP `default-src 'self'` を中心とした厳格な設定と互換性を持つ -- Static Siteとして本番にserver-side codeを置かない -- Caddyは生成済み成果物のみを配信する +### 5.1 Home ---- +| ID | 要求 | +|---|---| +| H-01 | 最近のNotesを新しいものから表示する。 | +| H-02 | Softwareを新しいものから表示する。 | +| H-03 | NotesとSoftwareの各一覧へ移動できる。 | +| H-04 | コンテンツがない領域には、準備中であることが分かる説明を表示する。 | +| H-05 | サイト名や説明を本文で重複表示せず、一覧への導線を中心にする。 | -## 29. 技術基盤に関する制約 +### 5.2 Notes -以下はDesignに委ねるが、要求上の前提とする。 +#### 一覧 + +| ID | 要求 | +|---|---| +| N-01 | Notesを年単位で整理し、日付とともに表示する。 | +| N-02 | 各項目にタイトルを表示し、説明とタグがある場合は併記する。 | +| N-03 | 各項目からNote詳細へ移動できる。 | +| N-04 | タグから同じタグを持つNotesの一覧へ移動できる。 | + +#### 詳細 + +| ID | 要求 | +|---|---| +| N-05 | タイトルと公開日を表示する。 | +| N-06 | 更新日と説明がある場合だけ表示する。 | +| N-07 | 見出しを持つ記事では目次を利用できる。 | +| N-08 | 見出し、一覧、表、引用、コード、画像、脚注を読みやすく表示する。 | +| N-09 | 関連Softwareが指定されている場合は記事末尾から移動できる。 | -- 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 -- 多言語 -- 画像処理の高度化 - -初期実装で将来拡張のための複雑な抽象化を先行導入しない。 +### 5.3 Tags + +| ID | 要求 | +|---|---| +| T-01 | タグ付きのNotesがある場合、使用中のタグと各記事数を一覧表示する。 | +| T-02 | タグ付きのNotesがある場合、タグごとに該当するNotesを一覧表示する。 | +| T-03 | タグは補助的な索引とし、細分化しすぎない。 | + +### 5.4 Software + +#### 一覧 + +| ID | 要求 | +|---|---| +| S-01 | Software名を主情報として表示する。 | +| S-02 | 説明がある場合はSoftware名とともに表示する。 | +| S-03 | 各項目からSoftware詳細へ移動できる。 | +| S-04 | ソースコード公開先としてcgitへの導線を示す。 | + +#### 詳細 + +| ID | 要求 | +|---|---| +| S-05 | Software名、概要、背景、制作過程などを掲載できる。 | +| S-06 | 使用言語とライセンスがある場合は表示する。 | +| S-07 | ソースコードの正本へのリンクを表示する。 | +| S-08 | 外部サービスのミラーがある場合は、正本と区別して表示する。 | +| S-09 | 必要に応じてスクリーンショットなどの記事固有画像を掲載できる。 | +| S-10 | 関連Notesが指定されている場合は記事末尾から移動できる。 | + +### 5.5 About + +| ID | 要求 | +|---|---| +| A-01 | 運営者のプロフィールを簡潔に示す。 | +| A-02 | サイトの目的を示す。 | +| A-03 | メールによる連絡先を示す。 | + +### 5.6 404 + +存在しないURLへ到達した利用者に、ページが見つからないことを明示し、Home、Notes、Softwareへ戻る導線を提供する。 + +## 6. 閲覧体験 + +### 6.1 デザイン + +| ID | 要求 | +|---|---| +| U-01 | 本文を中心とし、装飾より読みやすさを優先する。 | +| U-02 | ページ間で見出し、余白、一覧、Footerの見た目を一貫させる。 | +| U-03 | デスクトップとモバイルの双方で横方向のはみ出しを避ける。 | +| U-04 | コード、表、画像など幅を必要とする要素を本文の可読性を損なわず表示する。 | + +### 6.2 テーマ + +| ID | 要求 | +|---|---| +| U-05 | OSの表示設定に応じたLight／Dark themeを初期表示に使用する。 | +| U-06 | 利用者がLight／Dark themeを手動で切り替えられる。 | +| U-07 | 手動で選んだthemeを次回閲覧時にも維持する。 | + +### 6.3 アクセシビリティ + +| ID | 要求 | +|---|---| +| U-08 | キーボードだけで主要な導線を利用できる。 | +| U-09 | フォーカス位置と現在表示中のページを視覚的かつ機械的に判別できる。 | +| U-10 | 本文へ直接移動できる手段を提供する。 | +| U-11 | 見出し、ナビゲーション、日時、一覧などを意味に合った構造で提供する。 | +| U-12 | Light／Dark themeの双方で十分な文字とリンクのコントラストを確保する。 | +| U-13 | 動きを減らすOS設定を尊重する。 | + +## 7. 配信・プライバシー方針 + +| ID | 方針 | +|---|---| +| P-01 | NotesをAtomおよびRSSで購読できる。 | +| P-02 | 検索エンジンが公開ページを発見できるようにする。 | +| P-03 | サイト内検索は提供しない。 | +| P-04 | コメント機能は提供しない。 | +| P-05 | SNS共有ボタンや反応数を表示しない。 | +| P-06 | アクセス解析を導入しない。 | +| P-07 | 広告、外部フォント、外部配信の表示部品を使用しない。 | +| P-08 | theme選択以外の利用者情報をブラウザへ保存しない。 | + +## 8. 品質要求 + +| ID | 要求 | +|---|---| +| Q-01 | 公開ページ内にリンク切れを残さない。 | +| Q-02 | theme切替が利用できない環境でも、本文と主要な移動先を閲覧できる。 | +| Q-03 | ページの種類や本文量によって共通UIの配置が不自然に変化しない。 | +| Q-04 | 記事を追加・削除しても、一覧と個別ページの対応が維持される。 | +| Q-05 | 各ページを固有のURLで開き、共有できる。 | +| Q-06 | 各ページの内容を識別できるタイトルと説明を提供する。 | + +## 9. 対象外 + +現時点では、次の機能を対象外とする。 + +- 利用者アカウントとログイン +- 投稿画面や管理画面 +- データベース +- コメント、リアクション、評価 +- サイト内検索 +- SNS共有機能 +- アクセス解析 +- 多言語表示 +- 動的APIやバックエンド処理 + +## 10. 受入条件 + +| 分類 | 完了条件 | +|---|---| +| 情報構成 | Home、Notes、Software、About、404を閲覧でき、タグ使用時はTagsも閲覧できる。 | +| コンテンツ | NotesとSoftwareを追加すると一覧と詳細へ反映され、削除後に無効な参照が残らない。 | +| ナビゲーション | Header、Footer、一覧、関連コンテンツから目的のページへ移動できる。 | +| 表示 | Light／Dark themeとモバイル表示で本文を支障なく読める。 | +| アクセシビリティ | キーボード操作、フォーカス表示、見出し構造、スキップリンクが機能する。 | +| 配信 | 公開ページ、記事画像、Atom、RSSを継続して閲覧できる。 | +| プライバシー | コメント、解析、広告、外部配信の表示部品を含まない。 | |