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 はバンドルの一部になります。

  1. concepts/ に自分の知識を .qmd で書く(雛形をコピーして編集が早い)
  2. 編集後 quarto render を実行
  3. 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

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