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/Design.md | 1851 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1851 insertions(+) create mode 100644 doc/Design.md (limited to 'doc/Design.md') diff --git a/doc/Design.md b/doc/Design.md new file mode 100644 index 0000000..bddd04f --- /dev/null +++ b/doc/Design.md @@ -0,0 +1,1851 @@ +# Design.md + +# たかしの記録 — Zola 基本・詳細設計書 + +## 1. 文書目的 + +本書は `Specifications.md` の要求を、Zolaによる静的Webサイトとして矛盾なく実装するための基本設計・詳細設計を定義する。 + +設計上の基本原則は次のとおり。 + +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. 参照仕様と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. システム構成 + +```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 +``` + +ZolaはVPSへインストールしない。 + +--- + +## 4. Zolaサイト構造 + +```text +website/ +├── zola.toml +├── content/ +│ ├── _index.md +│ ├── about.md +│ ├── notes/ +│ │ ├── _index.md +│ │ ├── example-note.md +│ │ └── ... +│ └── software/ +│ ├── _index.md +│ ├── example-software.md +│ └── ... +├── templates/ +│ ├── base.html +│ ├── index.html +│ ├── page.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 +├── 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 +├── static/ +│ ├── favicon.svg +│ └── js/ +│ └── theme.js +├── 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 = "日々考えたこととか思ったことを記録します" ++++ +``` + +Home自体はZolaのroot sectionとして扱い、`templates/index.html` で描画する。 + +### 6.2 About Page + +`content/about.md` + +```toml ++++ +title = "About" +template = "page.html" ++++ +``` + +本文に以下をMarkdownで記述する。 + +- 名前 +- 一言プロフィール +- サイトの目的 +- 関心分野 +- 連絡先 + +構造化metadataを必要以上に増やさない。 + +### 6.3 Notes Section + +`content/notes/_index.md` + +```toml ++++ +title = "Notes" +sort_by = "date" +template = "notes/section.html" +page_template = "notes/page.html" ++++ +``` + +#### 6.3.1 Notesのsort + +Sectionはdate順にする。 +テンプレートでは新しい順で表示されることを検証する。 + +#### 6.3.2 Notes Page front matter + +```toml ++++ +title = "記事タイトル" +description = "記事の短い説明" +date = 2026-08-21 +updated = 2026-08-22 + +[taxonomies] +tags = ["情報工学", "AI"] + +[extra] +related_software = [ + "software/example-software.md" +] ++++ + +本文... +``` + +#### 6.3.3 Notes必須/任意項目 + +| Field | 必須 | 用途 | +|---|---:|---| +| `title` | Yes | タイトル | +| `date` | Yes | 公開日 | +| `description` | No | 一覧・meta description | +| `updated` | No | 更新日 | +| `taxonomies.tags` | No | 一覧分類 | +| `extra.related_software` | No | 明示的な関連Software | +| Body | Yes | 本文 | + +#### 6.3.4 Slug + +Markdown filenameを英語ASCII slugとする。 + +例： + +```text +content/notes/llm-compute-and-energy.md +``` + +表示タイトルは日本語でよい。 + +### 6.4 Software Section + +`content/software/_index.md` + +```toml ++++ +title = "Software" +sort_by = "date" +template = "software/section.html" +page_template = "software/page.html" ++++ +``` + +Software一覧の順序は初期状態ではdate順とする。 +公開日を表示する必要はないが、並び順制御に利用する。 + +将来、並びを明示したくなった場合は`weight`へ変更可能。 + +#### 6.4.1 Software Page 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対策を別途必要と判断した場合のみ変更する。 + +### 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 +- `