From c74551e116e80103aaa3c97c2592b7fb6f16ec90 Mon Sep 17 00:00:00 2001 From: tanaka takashi Date: Wed, 26 Aug 2026 21:43:16 +0900 Subject: 仕様書と設計書を改訂 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/Design.md | 2054 ++++++++++----------------------------------------------- 1 file changed, 350 insertions(+), 1704 deletions(-) (limited to 'doc/Design.md') 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// - └── current -> releases// - │ - ▼ - 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 -│ │ └── ... +│ │ └── .md │ └── software/ │ ├── _index.md -│ ├── example-software.md -│ └── ... +│ ├── .md +│ └── / +│ ├── index.md +│ └── ├── 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) %} - {{ related.title }} -{% endfor %} -``` - -Missing referenceはbuild/checkで検出できるよう、原則 `allow_missing=true` を使用しない。 - ---- - -## 8. Template設計 - -### 8.1 `base.html` - -責務： - -- HTML document skeleton -- `` -- `` -- 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 - - - - ... - - - - - - - {% include "partials/header.html" %} -
- {% block content %}{% endblock content %} -
- {% include "partials/footer.html" %} - - -``` - -#### 8.1.1 Page title - -原則： - -- Home: `たかしの記録` -- Other: ` | たかしの記録` - -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` - -表示： - -- `© 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` - -- `
` または適切なlist item -- `