nulab · lollipop-onl · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -66,6 +66,26 @@ Command reference pages are **auto-generated** from CLI source code — do NOT c
 
 **When adding or removing CLI commands**, also update the command table in `skills/using-bee/SKILL.md` to keep the Skill in sync with the CLI.
 
+#### Definition lists
+
+The docs site supports Markdown definition list syntax via `remark-definition-list`. Use this instead of raw `<dl>`/`<dt>`/`<dd>` HTML:
+
+```mdx
+<!-- Correct — Markdown definition list -->
+
+用語
+: 説明文
+
+<!-- Wrong — raw HTML -->
+
+<dl>
+  <dt>用語</dt>
+  <dd>説明文</dd>
+</dl>
+```
+
+This also works inside JSX components like `<Card>`.
+
 #### Internal link conventions
 
 All internal links in documentation content (`apps/docs/src/content/docs/`) must use **absolute paths with the base prefix `/bee/` and a trailing slash**:

diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
@@ -1,13 +1,18 @@
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
 import starlightLinksValidator from "starlight-links-validator";
+import { defListHastHandlers, remarkDefinitionList } from "remark-definition-list";
 import { loadCommandSidebar } from "./src/lib/sidebar-commands";
 
 const commandSidebar = await loadCommandSidebar();
 
 export default defineConfig({
   site: "https://nulab.github.io",
   base: "/bee",
+  markdown: {
+    remarkPlugins: [remarkDefinitionList],
+    remarkRehype: { handlers: { ...defListHastHandlers } },
+  },
   integrations: [
     starlight({
       plugins: [

diff --git a/apps/docs/package.json b/apps/docs/package.json
@@ -12,6 +12,7 @@
     "@astrojs/starlight": "^0.37.6",
     "astro": "^5.5.0",
     "marked": "^17.0.3",
+    "remark-definition-list": "^2.0.0",
     "sharp": "^0.34.5"
   },
   "devDependencies": {

diff --git a/apps/docs/src/content/docs/guides/authentication.mdx b/apps/docs/src/content/docs/guides/authentication.mdx
@@ -90,25 +90,21 @@ OAuth クライアント ID とシークレットは、フラグまたは環境
 <Card title="API キーがおすすめな場合">
   手軽に始めたいなら API キーが最適です。
 
-  <dl>
-    <dt>個人利用や CI/CD</dt>
-    <dd>セットアップがシンプルで、環境変数だけで完結します。</dd>
+  個人利用や CI/CD
+  : セットアップがシンプルで、環境変数だけで完結します。
 
-    <dt>すぐに使い始めたい場合</dt>
-    <dd>Backlog の個人設定から API キーを発行するだけで利用できます。</dd>
-  </dl>
+  すぐに使い始めたい場合
+  : Backlog の個人設定から API キーを発行するだけで利用できます。
 </Card>
 
 <Card title="OAuth がおすすめな場合">
   セキュリティを重視するなら OAuth がおすすめです。
 
-  <dl>
-    <dt>チームでの利用</dt>
-    <dd>OAuth クライアントを共有し、各メンバーが自分のアカウントで認証できます。</dd>
+  チームでの利用
+  : OAuth クライアントを共有し、各メンバーが自分のアカウントで認証できます。
 
-    <dt>有効期限の短いトークン</dt>
-    <dd>OAuth のアクセストークンは有効期限が短いため、AI ツールや外部サービスにトークンを渡す場合でも、漏洩時のリスクを抑えられます。期限切れ時は bee が自動で更新します。</dd>
-  </dl>
+  有効期限の短いトークン
+  : OAuth のアクセストークンは有効期限が短いため、AI ツールや外部サービスにトークンを渡す場合でも、漏洩時のリスクを抑えられます。期限切れ時は bee が自動で更新します。
 </Card>
 
 ## 複数スペースの管理

diff --git a/apps/docs/src/content/docs/guides/environment-variables.mdx b/apps/docs/src/content/docs/guides/environment-variables.mdx
@@ -12,26 +12,23 @@ description: |-
 
 ## 環境変数リファレンス
 
-<dl>
-  <dt><code>BACKLOG_SPACE</code></dt>
-  <dd>デフォルトのスペースホスト名（例: <code>xxx.backlog.com</code>）。設定すると、<code>bee auth login</code> でスペースの入力を省略できます。<code>BACKLOG_API_KEY</code> と併用すると、ログイン不要で bee を利用できます。</dd>
+`BACKLOG_SPACE`
+: デフォルトのスペースホスト名（例: `xxx.backlog.com`）。設定すると、`bee auth login` でスペースの入力を省略できます。`BACKLOG_API_KEY` と併用すると、ログイン不要で bee を利用できます。
 
-  <dt><code>BACKLOG_PROJECT</code></dt>
-  <dd>デフォルトのプロジェクト ID またはプロジェクトキー（例: <code>MY_PROJECT</code>）。設定すると、<code>--project</code> フラグを省略できます。</dd>
+`BACKLOG_PROJECT`
+: デフォルトのプロジェクト ID またはプロジェクトキー（例: `MY_PROJECT`）。設定すると、`--project` フラグを省略できます。
 
-  <dt><code>BACKLOG_REPO</code></dt>
-  <dd>デフォルトのリポジトリ名（例: <code>my-repo</code>）。設定すると、<code>--repo</code> フラグを省略できます。</dd>
+`BACKLOG_REPO`
+: デフォルトのリポジトリ名（例: `my-repo`）。設定すると、`--repo` フラグを省略できます。
 
-  <dt><code>BACKLOG_API_KEY</code></dt>
-  <dd>API キーによる認証に使用します。<code>BACKLOG_SPACE</code> と併用すると、<code>bee auth login</code> を実行しなくても認証済みの状態で bee を利用できます。CI/CD 環境で特に便利です。</dd>
+`BACKLOG_API_KEY`
+: API キーによる認証に使用します。`BACKLOG_SPACE` と併用すると、`bee auth login` を実行しなくても認証済みの状態で bee を利用できます。CI/CD 環境で特に便利です。
 
-  <dt><code>BACKLOG_OAUTH_CLIENT_ID</code></dt>
-  <dd>OAuth 認証で使用するクライアント ID。<code>bee auth login --method oauth</code> 時に <code>--client-id</code> フラグの代わりに使用できます。</dd>
+`BACKLOG_OAUTH_CLIENT_ID`
+: OAuth 認証で使用するクライアント ID。`bee auth login --method oauth` 時に `--client-id` フラグの代わりに使用できます。
 
-  <dt><code>BACKLOG_OAUTH_CLIENT_SECRET</code></dt>
-  <dd>OAuth 認証で使用するクライアントシークレット。<code>bee auth login --method oauth</code> 時に <code>--client-secret</code> フラグの代わりに使用できます。</dd>
-
-</dl>
+`BACKLOG_OAUTH_CLIENT_SECRET`
+: OAuth 認証で使用するクライアントシークレット。`bee auth login --method oauth` 時に `--client-secret` フラグの代わりに使用できます。
 
 ## よく使うパターン
 

diff --git a/apps/docs/src/content/docs/integrations/ai-agent.mdx b/apps/docs/src/content/docs/integrations/ai-agent.mdx
@@ -12,13 +12,11 @@ bee はターミナルツールとして、AI エージェントの「手足」
 
 bee のドキュメントサイトでは、LLM がコマンドの使い方を効率的に取得できるエンドポイントを提供しています。AI エージェントにドキュメントを読み込ませる際に活用してください。
 
-<dl>
-  <dt>[`/llms.txt`](/bee/llms.txt)</dt>
-  <dd>コマンド一覧のサマリー。全体像の把握に最適。</dd>
+[`/llms.txt`](/bee/llms.txt)
+: コマンド一覧のサマリー。全体像の把握に最適。
 
-  <dt>[`/llms-full.txt`](/bee/llms-full.txt)</dt>
-  <dd>全コマンドの完全なリファレンスを 1 ファイルで取得。</dd>
-</dl>
+[`/llms-full.txt`](/bee/llms-full.txt)
+: 全コマンドの完全なリファレンスを 1 ファイルで取得。
 
 各ドキュメントページにも `.md` エンドポイントがあり、個別のページを Markdown 形式で取得できます。
 

diff --git a/apps/docs/src/content/docs/recipes/pr-lifecycle-sync.mdx b/apps/docs/src/content/docs/recipes/pr-lifecycle-sync.mdx
@@ -124,22 +124,20 @@ jobs:
 
 ## カスタマイズ
 
-<dl>
-  <dt>ステータス ID を確認するには</dt>
-  <dd>`bee status list <PROJECT>` でプロジェクトのステータス一覧と ID を確認できます。`STATUS_IN_PROGRESS` の値をプロジェクトに合わせて変更してください。</dd>
+ステータス ID を確認するには
+: `bee status list <PROJECT>` でプロジェクトのステータス一覧と ID を確認できます。`STATUS_IN_PROGRESS` の値をプロジェクトに合わせて変更してください。
 
-  <dt>ステータス変更が不要</dt>
-  <dd>`bee issue edit` の行と `STATUS_IN_PROGRESS` 環境変数を削除すれば、リンクのコメントだけになります。</dd>
+ステータス変更が不要
+: `bee issue edit` の行と `STATUS_IN_PROGRESS` 環境変数を削除すれば、リンクのコメントだけになります。
 
-  <dt>自動クローズが不要</dt>
-  <dd>「Close linked issues」ステップを削除してください。</dd>
+自動クローズが不要
+: 「Close linked issues」ステップを削除してください。
 
-  <dt>クローズではなく別のステータスにしたい</dt>
-  <dd>`bee issue close` を `bee issue edit --status <ステータスID>` に変更してください。ステータス ID は `bee status list <PROJECT>` で確認できます。</dd>
+クローズではなく別のステータスにしたい
+: `bee issue close` を `bee issue edit --status <ステータスID>` に変更してください。ステータス ID は `bee status list <PROJECT>` で確認できます。
 
-  <dt>`edited` イベントが不要</dt>
-  <dd>トリガーの `types` から `edited` を削除し、「Comment PR link on newly added issues」ステップを削除してください。</dd>
-</dl>
+`edited` イベントが不要
+: トリガーの `types` から `edited` を削除し、「Comment PR link on newly added issues」ステップを削除してください。
 
 ## 関連するコマンド
 

diff --git a/apps/docs/src/content/docs/recipes/release-notify-issues.mdx b/apps/docs/src/content/docs/recipes/release-notify-issues.mdx
@@ -87,16 +87,14 @@ jobs:
 
 ## カスタマイズ
 
-<dl>
-  <dt>ドキュメント投稿が不要</dt>
-  <dd>「Post release notes to Backlog document」ステップと `BACKLOG_PROJECT`・`DOCUMENT_PARENT_ID` 環境変数を削除してください。</dd>
+ドキュメント投稿が不要
+: 「Post release notes to Backlog document」ステップと `BACKLOG_PROJECT`・`DOCUMENT_PARENT_ID` 環境変数を削除してください。
 
-  <dt>課題への通知が不要</dt>
-  <dd>「Collect issue keys ...」と「Comment release info ...」の2ステップを削除してください。</dd>
+課題への通知が不要
+: 「Collect issue keys ...」と「Comment release info ...」の2ステップを削除してください。
 
-  <dt>ドキュメントを特定のフォルダに入れたい</dt>
-  <dd>`DOCUMENT_PARENT_ID` にフォルダのドキュメント ID を設定してください。</dd>
-</dl>
+ドキュメントを特定のフォルダに入れたい
+: `DOCUMENT_PARENT_ID` にフォルダのドキュメント ID を設定してください。
 
 ## 関連するコマンド