1. Create a Bundle

quarto use template で新しい OKF バンドルを作成する手順

新しいバンドルを作成する

前提条件

始める前に、次のツールが入っていることを確認してください。

ツール	必要バージョン	確認コマンド	導入方法
Quarto	>= 1.3	`quarto --version`	macOS: `brew install quarto` / 公式インストーラ
Node.js	>= 20	`node --version`	macOS: `brew install node` / 公式インストーラ
Git	任意(デプロイ・貢献時)	`git --version`	—

Node.js は tools/ の検証・バンドル生成スクリプト(*.mjs)が使うため必須です
未インストールならまず brew install quarto node を実行してください

バンドルの雛形を作る

quarto use template watanabe3tipapa/okf-seedling

空ディレクトリで実行すると、以下の成果物が生成されます。

_quarto.yml(サイト・OKF 設定)
concepts/(concept 型の雛形 .qmd)
tutorial/(このドキュメント群)
tools/(バンドル生成・検証・スキーマ生成スクリプト)
_extensions/okf/(frontmatter → HTML 表示の Quarto 拡張)

このコマンドで何が起きるか

quarto use template は GitHub からテンプレートを自動取得して現在のディレクトリへ展開します。git clone は不要です
展開に含まれるのは雛形だけです。.quartoignore に指定された okf/(生成物)・pipeline/(学習パイプライン)・.github/(CI)・DEV-MEMO.md は展開されません
テンプレートは複数の候補から選ぶこともできます。まず「okf-seedling」を選んでください

開発やコントリビューションでリポジトリ全体(CI・パイプライン込み)が欲しい場合のみ、git clone を使ってください。通常の利用では quarto use template が本命です。

最初にいじる場所

展開直後の最初の編集ポイントは concepts/ ディレクトリです。ここに type を記した .qmd を置くだけで、あなたの knowledge はバンドルの一部になります。

concepts/ に自分の知識を .qmd で書く(雛形をコピーして編集が早い)
編集後 quarto render を実行
node tools/validate-okf.mjs で検証

「何をどう書くか」は 2. Concept Types を参照してください。

レンダリング

quarto render

_site/ … 人間用 HTML(LP・チュートリアル)
okf/ … OKF v0.2 準拠バンドル(.md + frontmatter、機械読み取り用)

検証

node tools/validate-okf.mjs

出力バンドルが OKF v0.2 に準拠しているか、type レジストリ(tools/okf-types.json)駆動で必須 frontmatter・provenance・内部リンクの解決可能性をチェックします。

実際の入出力を見る

テンプレートが何を生むのか、実在ファイルで確認しましょう。ソースは concepts/api-endpoint.qmd(1 概念 1 ファイル)です。

入力(概念の 1 つ):

---
type: APIEndpoint
title: "Get User"
description: ユーザー情報を取得する。
resource: https://example.com/api/v1/users/{userId}
method: GET
path: /v1/users/{userId}
tags: [read, users]
status: stable
generated: { by: human:okf-seedling, at: 2026-08-11T00:00:00Z }
verified: { by: human:okf-seedling, at: 2026-08-11T00:00:00Z }
stale_after: 2026-12-31
---

# Summary

ユーザーID からユーザー情報を取得する。

# Responses

- 200: OK
  - schema: [UserResponse](api-schema.qmd)

出力 okf/concepts/api-endpoint.md(機械用バンドル):

quarto render が .qmd のまま okf/concepts/ へコピーし、frontmatter を保持します。エージェントはこの .md を読み、type: APIEndpoint / method: GET / stale_after などの辞書情報と見出し(Summary / Responses)を構造として解釈します。

人間用 HTML では:

同じソースが _site/concepts/api-endpoint.html としてレンダリングされ、frontmatter はページ上部の メタ情報ブロック(.concept-meta)に表示されます。人間が読むサイトと、エージェントが読むバンドルが、同じ 1 ファイルから同時に生まれていることが実感できます。

リンターとして使う

validate-okf.mjs は単なる合格/不合格の検査でなく、情報バンドル向けリンターとして品質にも目を配ります。

エラー(CI を止める): frontmatter 欠落、必須 type なし、型ごとの必須フィールド不足、解決できない内部リンク
警告(成功のまま報告): stale_after の期限切れ、title / description の欠落、本文が空、未登録 type

鮮度・発見可能性・学習可能性の観点で、保守性を下げるサインを早めに知らせてくれます。

Peek セクションを LP に設置する

「知識の頭出し」はテンプレート同梱ツールとして誰のバンドルでも動きます。あなたの LP(通常は index.qmd)に Peek セクションを置くと、「うろ覚えの知識をチラ見して気づきを得る」入口になります。

手順

_quarto.yml に post-render と CSS を追加:

project:
  post-render:
    - node tools/stamp-okf.mjs
    - node tools/gen-peek.mjs   # stamp-okf の後に実行

format:
  html:
    css:
      - assets/grid.css         # 既存
      - assets/peek.css

LP(index.qmd) に Peek セクションをコピー。必要なのは次の 4 点セットです(本リポジトリの index.qmd 「知識の頭出し」セクションからそのまま持ってこられます):
- <div id="peek-cards" class="peek-grid"></div> … カードの描画先
-  … データ注入ポイント(gen-peek が差し替えるプレースホルダ)
- セクション内の <script> … カード描画・「今日の頭出し」ボタンの vanilla JS
- assets/peek.css
quarto render を実行 → gen-peek.mjs が okf/concepts/*.md(stamp-okf の生成物)を読み、type・title・description・status・stale_after・本文の頭を JSON 化して _site/index.html に注入します。

仕組みと注意

fetch を使わない post-render 注入のため、file:// で開いても動作し、描画時の非同期フラッシュがありません
 がないページでは gen-peek は警告を出して正常終了します(CI 非破壊)。Peek セクションを置かないバンドルでも追記の害はありません
カードの内容はバンドル .md が唯一の source です。.qmd を直すだけで Peek・HTML・バンドルの 3 系統が同時に更新されます

秘密領域 notes/

ルート直下の notes/ は あなた専用のシークレット領域です。git 管理外のため clone にも含まれず、公開サイトにも出ません。

.gitignore の /notes/ により、コミット・push の対象になりません
_quarto.yml の render 除外(!notes/)により、_site/(公開物)に混入しません
誤って git add -f 等で追跡した場合は node tools/validate-okf.mjs がエラーで検知します(解除は git rm -r --cached notes)

メモ・下書き・個人的な調整ファイルなど、公開したくないものはここに置いてください。clone 直後はフォルダ自体が存在しないのが正常です(mkdir notes で作成できます)。