コンテンツ作成ガイドライン

このサイトのコンテンツを作成する際のガイドラインです。

⚠️ 重要なルール

フォルダ用ファイルに詳細ドキュメントを書かない

⛔ index.md / README.md には技術ドキュメントを書かない

フォルダの概要やナビゲーション用ファイル（index.md, README.md）には、詳細な技術ドキュメントは書きません。

✅ 良い使い方 - ナビゲーションのみ:

---
title: dbt検証レポート
---
 
dbt + BigQueryの設定項目検証結果の一覧です。
 
## カテゴリ別ガイド
 
- [プロジェクト設定](project-config.md)
- [BigQuery接続](bigquery-connection.md)
- [Models設定](models/)

❌ 禁止 - 詳細ドキュメント記載:

---
title: dbt検証レポート
---
 
## dbt_project.ymlの詳細設定
 
dbt_project.ymlは...（数百行の詳細説明）
 
### name設定の詳細
 
nameパラメータは...（詳細説明）

理由:

index/READMEファイルは目次・ナビゲーション専用
詳細な内容は個別ファイルに分けることで管理・検索性が向上
URLが明確に区別される（folder/ vs folder/specific-topic）

ルール: 詳細な技術ドキュメントは必ず個別ファイルとして作成し、index/READMEからリンクする

タイトルの重複を避ける

❌ ダメな例:

---
title: Gitメモ
---
 
# Gitメモ
 
内容...

✅ 良い例:

---
title: Gitメモ
---
 
内容...

理由: Quartzはtitleフィールドを自動的にページタイトルとして表示するため、H1見出しで同じタイトルを書くと重複します。

タイトル重複チェック方法

以下のコマンドでタイトル重複をチェックできます：

# 全ファイルのタイトル重複をチェック
grep -r "^title: " content/ | while IFS=: read -r file title; do
  # ファイル内でタイトルと同じH1見出しがあるかチェック
  echo "Checking $file"
done

index.mdファイルの使用ルール

⛔ index.mdはホームページ（content/index.md）のみ

index.md ファイルはサイトのホームページ（content/index.md）でのみ使用します。サブフォルダには index.md を作成しないでください。

❌ 禁止:

content/_index.md              # ⛔ _index.mdは使用禁止
content/Ideas/index.md         # ⛔ サブフォルダのindex.mdは不要
content/dbt/index.md           # ⛔ サブフォルダのindex.mdは不要
content/Tech/dbt/index.md      # ⛔ サブフォルダのindex.mdは不要

✅ 推奨:

content/index.md               # ✅ ホームページのみOK
content/dbt/overview.md        # ✅ 通常の記事ファイル
content/Tech/README.md         # ✅ README.mdは許可（ナビゲーション用）

理由:

index.md はホームページ専用
サブフォルダには通常のマークダウンファイルを使用
README.md はフォルダ概要・ナビゲーション用として許可
ファイル構成がシンプルで管理しやすい

index.md/README.mdに詳細なドキュメントを書かない

フォルダの概要やナビゲーション用ファイル（index.md, README.md）には、詳細なドキュメントは書かず、以下のように使用します：

✅ 良い使い方:

---
title: dbt関連記事
---
 
dbtに関する検証レポートとガイドの一覧です。
 
## 記事一覧
 
- [[Tech/dbt/dbt-unit-tests-bigquery-verification|dbt unit tests検証]]
- [[Tech/dbt/bigquery-dbt-model-config-verification|dbtモデル設定ガイド]]
- [[Tech/dbt/dbt-project-config-verification|dbtプロジェクト設定]]
 
## 関連リンク
 
- [dbt公式ドキュメント](https://docs.getdbt.com/)

❌ 悪い使い方:

---
title: dbt関連記事
---
 
# dbt unit testsの詳細な使い方
 
unit testsは、dbt 1.8+で導入された機能で...
（数百行の詳細なドキュメント）

理由:

indexファイルは目次・ナビゲーションの役割
詳細な内容は別ファイルに分けることで、管理しやすくなる
URLが folder/ と folder/article-name で明確に区別される

ルール:

_index.md は使用禁止（代わりに index.md または README.md を使用）
index/READMEファイルには詳細な技術ドキュメントを書かない（ナビゲーション専用）
詳細な技術ドキュメントは必ず個別ファイルとして作成

フォルダ構造のルール

⛔ フォルダ階層のガイドライン

基本ルール:

content/ 直下に機能別フォルダを作成
フォルダは1階層まで（content/xxx/ のみ）
2階層以上のネストは禁止

✅ 推奨される構造:

content/
├── dbt/                    # 1階層: メインエントリー (2ファイル)
│   ├── index.md
│   └── overview.md
├── dbt-connection/         # 1階層: 接続設定 (2ファイル)
│   ├── project-basic-config.md
│   └── bigquery-connection.md
├── dbt-bigquery/           # 1階層: BigQuery機能 (2ファイル)
│   ├── bigquery-configs-complete.md
│   └── bigquery-python-udf-deep-dive.md
├── dbt-config/             # 1階層: 基本設定 (5ファイル)
│   ├── performance-optimization.md
│   ├── other-config.md
│   └── seed-config.md
├── dbt-models/             # 1階層: モデル設定 (6ファイル)
│   ├── models.md
│   ├── models-materialization.md
│   └── models-partitioning.md
├── dbt-performance/        # 1階層: パフォーマンス (3ファイル)
│   ├── partitioning-clustering-guide.md
│   └── snapshot-config.md
├── dbt-testing/            # 1階層: テスト (4ファイル)
│   ├── testing-config.md
│   └── unit-tests-verification.md
└── dbt-tutorials/          # 1階層: チュートリアル (6ファイル)
    ├── quick-reference.md
    └── tutorial-01-setup.md

❌ 避けるべき構造 - 2階層以上のネスト:

content/
├── Tech/                   # 1階層
│   ├── dbt/                # 2階層 ❌ NG
│   │   └── models.md

理由:

URL が長くなりすぎる
ナビゲーションが複雑になる
ファイル管理が困難になる
フォルダ構造が把握しにくい

ガイドライン:

content/直下に機能別フォルダ作成（1階層のみ）
2階層以上は禁止
フォルダ名: 機能を明確に表す名前（dbt-connection, dbt-models など）
1フォルダあたり: 約2〜6ファイルを目安（最大15ファイル）
ファイル数が多い場合: 機能別に細分化して複数フォルダに分割

⛔ 1フォルダあたり最大約15ファイル

1つのフォルダに含まれるファイル数は約15個以下を目安にします。

✅ 良い例:

content/Tech/dbt/categories/
├── project-config.md        (1)
├── bigquery-connection.md   (2)
├── testing-config.md        (3)
...
├── other-config.md          (9)  # ✅ 15個以下

❌ 悪い例:

content/Tech/dbt/
├── article-01.md
├── article-02.md
...
├── article-25.md   # ❌ 多すぎる

理由:

ファイル数が多すぎると管理が困難
フォルダ内で目的のファイルを見つけにくい
サブフォルダで分類すべきサイン

対処法: ファイルが15個を超えそうな場合は、サブフォルダで分類するか、既存の分類を見直す

ファイル命名規則

⛔ ファイル名はkebab-case、英語のみ

ファイル名は小文字の英単語をハイフンで繋いだ形式（kebab-case）を使用します。

✅ 良い例:

project-basic-config.md
bigquery-connection.md
unit-tests-verification.md
partitioning-clustering-guide.md

❌ 悪い例:

Project_Basic_Config.md      # ❌ アンダースコア、大文字
BigQuery接続.md              # ❌ 日本語
unit tests verification.md   # ❌ スペース
ProjectConfig.md             # ❌ キャメルケース

理由:

URLに使いやすい（スペースのエンコード不要）
検索しやすい
Git履歴での追跡が容易
クロスプラットフォーム互換性

コードブロックの言語指定

⛔ コードブロックには必ず言語を指定

コードブロックを記載する際は、必ず言語を指定します。

✅ 良い例:

```python
def hello():
    print("Hello, World!")
```
 
```sql
SELECT * FROM users WHERE id = 1;
```
 
```yaml
title: ページタイトル
draft: false
```

❌ 悪い例:

```
def hello():
    print("Hello, World!")
```
 
```
SELECT * FROM users WHERE id = 1;
```

理由:

シンタックスハイライトが適用される
読みやすさが向上
コードの意図が明確になる

補足: 言語指定のないコードブロックや、コードのスクリーンショットは使用しないでください（コピペできないため）。

リンク管理

⛔ 内部リンクは相対パス、外部リンクは完全URL

リンクは用途に応じて適切な形式を使用します。

✅ 内部リンク - 相対パス:

[プロジェクト設定](categories/project-basic-config.md)
[Models](../categories/models/)
[クイックリファレンス](../../guides/quick-reference.md)

✅ 外部リンク - 完全URL:

[dbt公式ドキュメント](https://docs.getdbt.com/)
[BigQuery公式](https://cloud.google.com/bigquery/docs)

理由:

相対パスはファイル移動時に一括変更可能
完全URLは外部リンクの変更を追跡しやすい
リンク切れの検出が容易

注意: リンク切れが発生していないか定期的に確認してください。

日付フォーマット統一

⛔ 日付はISO 8601形式（YYYY-MM-DD）

すべての日付はISO 8601形式で記載します。

✅ 良い例:

date: 2026-02-17

**検証日時**: 2026-02-17
**最終更新**: 2026-02-17

❌ 悪い例:

date: 2026/2/17        # ❌ スラッシュ区切り
date: Feb 17, 2026     # ❌ 英語表記
date: 2026年2月17日    # ❌ 日本語表記

理由:

国際標準規格
ソート可能
パース（解析）が容易
曖昧さがない

タグの一貫性

⛔ タグは事前定義されたリストから選択

タグは小文字英語で、事前に定義されたリストから選択します。

許可されたタグ:

# 技術カテゴリ
tags: ["dbt", "bigquery", "data-engineering", "sql", "python"]
 
# 内容タイプ
tags: ["testing", "best-practices", "tutorial", "guide", "verification"]
 
# 機能
tags: ["partitioning", "clustering", "incremental", "snapshots", "hooks"]

✅ 良い例:

tags: ["dbt", "bigquery", "testing", "best-practices"]

❌ 悪い例:

tags: ["DBT", "BigQuery", "テスト", "Best-Practices"]  # ❌ 大文字、日本語、不統一
tags: ["random-tag", "my-custom-tag"]                  # ❌ 事前定義されていない

理由:

タグの一貫性が保たれる
検索性が向上
タグの乱立を防ぐ
サイト全体のタグ管理が容易

新しいタグの追加: 必要な場合は、まずCONTRIBUTING.mdのタグリストに追加してから使用してください。

📝 Frontmatter設定

基本構造

---
title: ページタイトル
draft: false # 下書きの場合はtrue
tags:
  - タグ1
  - タグ2
date: 2026-02-16
---

Authorship（著作権情報）

AI支援で作成した記事には必ず記載：

authorship:
  type: ai-assisted # または human-written, ai-generated
  model: Claude Sonnet 4.5
  date: 2026-02-16
  reviewed: false # レビュー済みの場合はtrue

Type の種類:

human-written: 完全に人間が書いた
ai-assisted: AIアシスタントの支援を受けた
ai-generated: AIが生成した（最小限の編集のみ）

📂 フォルダ構成

content/
├── index.md              # トップページ
├── about.md              # Aboutページ
├── Tech/                 # 技術関連の記事
├── Notes/                # 一般的なノート・メモ
└── CONTRIBUTING.md       # このファイル

フォルダの用途

フォルダ	用途	例
Tech/	技術メモ、チュートリアル	Git、セットアップ手順
Notes/	一般的な学習メモ、読書メモ	読書記録、学習ノート

✍️ 文章スタイル

見出しレベル

見出しは最大H4までにする

リンク

内部リンク (Obsidian形式):

[[Tech/git-memo|Gitメモ]]

外部リンク:

[Quartz公式ドキュメント](https://quartz.jzhao.xyz/)

コードブロック

```javascript
console.log("Hello, World!")
```

言語を明示することでシンタックスハイライトが適用されます。

🎨 Frontmatterの特殊機能

下書き機能

draft: true

draft: true を設定すると、サイトには表示されません。

日付管理

date: 2026-02-16

記事の作成日または最終更新日を記録します。フォルダページで日付順にソートされます。

📖 技術用語とスタイル

dbt固有名詞は英語で記載

dbt-specificな技術用語は、公式ドキュメントに合わせて英語で記載します：

✅ 推奨:

Seeds (not シード)
Snapshots (not スナップショット)
Hooks (not フック)
Models (not モデル)
Tests (not テスト)
Contracts (not コントラクト)
Exposures (not エクスポージャー)

理由:

公式ドキュメントとの一貫性
技術コミュニティでの検索性向上
グローバルな互換性

参考: dbt Developer Hub

プロモーショナル表現を避ける

客観的で正確な表現を使用します：

❌ 避けるべき表現:

“完全ガイド” → “ガイド” または機能名のみ
“完全検証” → “検証”
“完全網羅” → “網羅” または “詳細”
“全〇〇項目の完全ガイド” → “〇〇項目のガイド” または “詳細ガイド”

✅ 良い例:

title: "Partitioning & Clustering"
 
# BigQueryパーティショニング＆クラスタリング

❌ 悪い例:

title: "パーティショニング＆クラスタリング完全ガイド"
 
# BigQueryパーティショニング＆クラスタリング完全ガイド - 全設定を完全網羅

タグは小文字英語で統一

✅ 推奨:

tags: ["dbt", "bigquery", "testing", "best-practices"]

❌ 非推奨:

tags: ["DBT", "BigQuery", "テスト", "Best-Practices"]

フォルダ名は Title Case

content/
├── Tech/        # ✅ 技術記事
├── Ideas/       # ✅ アイデア・提案
├── Notes/       # ✅ 一般ノート
└── Projects/    # ✅ プロジェクト

🚫 避けるべきこと

_index.mdファイルの使用 - index.md または README.md を使用してください
index/READMEに詳細ドキュメント記載 - ナビゲーション専用、詳細は個別ファイルに
深すぎるフォルダ階層 - ネストは最小限に、URLが長くなりすぎないように
1フォルダに多数のファイル - 目安は約15ファイルまで、超える場合はサブフォルダで分類
不適切なファイル命名 - kebab-case以外、日本語、スペース含む
コードブロックの言語指定なし - 必ず言語を指定
不適切なリンク形式 - 内部は相対パス、外部は完全URL
非標準の日付フォーマット - YYYY-MM-DD形式を使用
未定義のタグ使用 - 事前定義されたタグリストから選択
絵文字の過度な使用 - 見出しや重要な箇所に限定
大きなバイナリファイルのコミット - 画像は最適化してから追加
プライベート情報の記載 - 公開されることを前提に
プロモーショナル表現 - “完全”、“最強”、“究極” などの誇張表現
dbt用語の日本語訳 - Seeds/Snapshots/Hooks/Models/Testsは英語で

📁 ドキュメント構成の原則

機能別に分割する

大きな技術ドキュメントは、機能ごとに分割して管理します。

✅ 良い構成:

Tech/dbt/
├── index.md                           # ナビゲーションハブ (40行)
├── overview.md                        # プロジェクト概要
├── partitioning-clustering-guide.md   # 機能別: パーティショニング
├── authentication-guide.md            # 機能別: 認証
├── incremental-strategies-guide.md    # 機能別: 増分戦略
└── guides/
    ├── learning-guide.md              # 学習パス
    └── execution-guide.md             # 実行手順

❌ 悪い構成:

Tech/dbt/
├── _index.md          # ⛔ 使用禁止
├── index.md           # すべての詳細を1ファイルに (可読性低下)
└── all-features.md    # すべての機能を1ファイルに (管理困難)

理由:

各ファイルが特定の目的を持つ
検索性・メンテナンス性の向上
読者が必要な情報に素早くアクセスできる

カテゴリ別 vs 機能別

カテゴリ別ガイド (包括的):

models.md - Models全般の30項目
tests.md - Tests全般の15項目

機能別ガイド (特化型):

partitioning-clustering-guide.md - パーティション＆クラスタ特化
unit-tests-guide.md - Unit Tests特化
contracts-guide.md - Contracts特化

両方を提供することで、概要を知りたい人と特定機能を深掘りしたい人の両方をサポートします。

✅ チェックリスト

新しいコンテンツを作成する前に：

🔄 更新フロー

1. メモを書く

Obsidianのpublishフォルダに書く

2. ローカルで確認

make serve

http://localhost:8080 で確認

3. 公開

make publish

約1-2分でサイトに反映されます。

🔒 禁止ワードチェック

コミット前に自動的に禁止ワードをチェックします。

設定方法

forbidden-words.txt ファイルで禁止ワードを管理：

# 個人情報保護関連ワードの例
forbidden_word_1
forbidden_word_2
forbidden_word_3
 
# カスタムワードの例
custom_forbidden_word

動作

コミット時に自動チェック
禁止ワードが見つかるとコミット失敗
大文字小文字を区別しない
行の先頭に # でコメント化

手動チェック

./scripts/check-forbidden-words.sh

禁止ワードが検出された場合

該当箇所を修正
誤検知の場合は forbidden-words.txt から削除
再度コミット

🐛 トラブルシューティング

タイトルが二重表示される

→ FrontmatterのtitleとH1見出しが重複している可能性があります。H1見出しを削除してください。

ページが表示されない

→ draft: true になっていないか確認してください。

リンクが壊れている

→ 相対パスが正しいか確認してください。Obsidian形式の[[]]リンクを使用している場合、パスが正しいか確認してください。

📚 参考

最終更新: 2026年2月17日

Scrap Notes

Explorer

コンテンツ作成ガイドライン

⚠️ 重要なルール

フォルダ用ファイルに詳細ドキュメントを書かない

タイトルの重複を避ける

タイトル重複チェック方法

index.mdファイルの使用ルール

フォルダ構造のルール

ファイル命名規則

コードブロックの言語指定

リンク管理

日付フォーマット統一

タグの一貫性

📝 Frontmatter設定

基本構造

Authorship（著作権情報）

📂 フォルダ構成

フォルダの用途

✍️ 文章スタイル

見出しレベル

リンク

コードブロック

🎨 Frontmatterの特殊機能

下書き機能

日付管理

📖 技術用語とスタイル

dbt固有名詞は英語で記載

プロモーショナル表現を避ける

タグは小文字英語で統一

フォルダ名は Title Case

🚫 避けるべきこと

📁 ドキュメント構成の原則

機能別に分割する

カテゴリ別 vs 機能別

✅ チェックリスト

🔄 更新フロー

1. メモを書く

2. ローカルで確認

3. 公開

🔒 禁止ワードチェック

設定方法

動作

手動チェック

禁止ワードが検出された場合

🐛 トラブルシューティング

タイトルが二重表示される

ページが表示されない

リンクが壊れている

📚 参考

グラフビュー

Table of Contents

Backlinks