# 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 新規記事用の完全な雛形は`doc/content-templates/note.md`を使用する。 ```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 新規記事用の完全な雛形は`doc/content-templates/software.md`を使用する。 ```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 - `