diff --git a/AGENTS.md b/AGENTS.md index 727a8f80..9f0431c0 100644 --- 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 `
`/`
`/`
` HTML: + +```mdx + + +用語 +: 説明文 + + + +
+
用語
+
説明文
+
+``` + +This also works inside JSX components like ``. + #### 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 index 11c09baf..2a084747 100644 --- a/apps/docs/astro.config.mjs +++ b/apps/docs/astro.config.mjs @@ -1,6 +1,7 @@ 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(); @@ -8,6 +9,10 @@ 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 index f781e02f..69d46a74 100644 --- 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 index 46a87eb6..016300b1 100644 --- a/apps/docs/src/content/docs/guides/authentication.mdx +++ b/apps/docs/src/content/docs/guides/authentication.mdx @@ -90,25 +90,21 @@ OAuth クライアント ID とシークレットは、フラグまたは環境 手軽に始めたいなら API キーが最適です。 -
-
個人利用や CI/CD
-
セットアップがシンプルで、環境変数だけで完結します。
+ 個人利用や CI/CD + : セットアップがシンプルで、環境変数だけで完結します。 -
すぐに使い始めたい場合
-
Backlog の個人設定から API キーを発行するだけで利用できます。
-
+ すぐに使い始めたい場合 + : Backlog の個人設定から API キーを発行するだけで利用できます。 セキュリティを重視するなら OAuth がおすすめです。 -
-
チームでの利用
-
OAuth クライアントを共有し、各メンバーが自分のアカウントで認証できます。
+ チームでの利用 + : OAuth クライアントを共有し、各メンバーが自分のアカウントで認証できます。 -
有効期限の短いトークン
-
OAuth のアクセストークンは有効期限が短いため、AI ツールや外部サービスにトークンを渡す場合でも、漏洩時のリスクを抑えられます。期限切れ時は bee が自動で更新します。
-
+ 有効期限の短いトークン + : OAuth のアクセストークンは有効期限が短いため、AI ツールや外部サービスにトークンを渡す場合でも、漏洩時のリスクを抑えられます。期限切れ時は bee が自動で更新します。 ## 複数スペースの管理 diff --git a/apps/docs/src/content/docs/guides/environment-variables.mdx b/apps/docs/src/content/docs/guides/environment-variables.mdx index a11d4a5d..7e0a2b37 100644 --- 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: |- ## 環境変数リファレンス -
-
BACKLOG_SPACE
-
デフォルトのスペースホスト名（例: xxx.backlog.com）。設定すると、bee auth login でスペースの入力を省略できます。BACKLOG_API_KEY と併用すると、ログイン不要で bee を利用できます。
+`BACKLOG_SPACE` +: デフォルトのスペースホスト名（例: `xxx.backlog.com`）。設定すると、`bee auth login` でスペースの入力を省略できます。`BACKLOG_API_KEY` と併用すると、ログイン不要で bee を利用できます。 -
BACKLOG_PROJECT
-
デフォルトのプロジェクト ID またはプロジェクトキー（例: MY_PROJECT）。設定すると、--project フラグを省略できます。
+`BACKLOG_PROJECT` +: デフォルトのプロジェクト ID またはプロジェクトキー（例: `MY_PROJECT`）。設定すると、`--project` フラグを省略できます。 -
BACKLOG_REPO
-
デフォルトのリポジトリ名（例: my-repo）。設定すると、--repo フラグを省略できます。
+`BACKLOG_REPO` +: デフォルトのリポジトリ名（例: `my-repo`）。設定すると、`--repo` フラグを省略できます。 -
BACKLOG_API_KEY
-
API キーによる認証に使用します。BACKLOG_SPACE と併用すると、bee auth login を実行しなくても認証済みの状態で bee を利用できます。CI/CD 環境で特に便利です。
+`BACKLOG_API_KEY` +: API キーによる認証に使用します。`BACKLOG_SPACE` と併用すると、`bee auth login` を実行しなくても認証済みの状態で bee を利用できます。CI/CD 環境で特に便利です。 -
BACKLOG_OAUTH_CLIENT_ID
-
OAuth 認証で使用するクライアント ID。bee auth login --method oauth 時に --client-id フラグの代わりに使用できます。
+`BACKLOG_OAUTH_CLIENT_ID` +: OAuth 認証で使用するクライアント ID。`bee auth login --method oauth` 時に `--client-id` フラグの代わりに使用できます。 -
BACKLOG_OAUTH_CLIENT_SECRET
-
OAuth 認証で使用するクライアントシークレット。bee auth login --method oauth 時に --client-secret フラグの代わりに使用できます。
- -
+`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 index b99be594..c8a4f8e7 100644 --- 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 エージェントにドキュメントを読み込ませる際に活用してください。 -
-
[`/llms.txt`](/bee/llms.txt)
-
コマンド一覧のサマリー。全体像の把握に最適。
+[`/llms.txt`](/bee/llms.txt) +: コマンド一覧のサマリー。全体像の把握に最適。 -
[`/llms-full.txt`](/bee/llms-full.txt)
-
全コマンドの完全なリファレンスを 1 ファイルで取得。
-
+[`/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 index 45594a82..521fa3d0 100644 --- 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: ## カスタマイズ -
-
ステータス ID を確認するには
-
`bee status list ` でプロジェクトのステータス一覧と ID を確認できます。`STATUS_IN_PROGRESS` の値をプロジェクトに合わせて変更してください。
+ステータス ID を確認するには +: `bee status list ` でプロジェクトのステータス一覧と ID を確認できます。`STATUS_IN_PROGRESS` の値をプロジェクトに合わせて変更してください。 -
ステータス変更が不要
-
`bee issue edit` の行と `STATUS_IN_PROGRESS` 環境変数を削除すれば、リンクのコメントだけになります。
+ステータス変更が不要 +: `bee issue edit` の行と `STATUS_IN_PROGRESS` 環境変数を削除すれば、リンクのコメントだけになります。 -
自動クローズが不要
-
「Close linked issues」ステップを削除してください。
+自動クローズが不要 +: 「Close linked issues」ステップを削除してください。 -
クローズではなく別のステータスにしたい
-
`bee issue close` を `bee issue edit --status <ステータスID>` に変更してください。ステータス ID は `bee status list ` で確認できます。
+クローズではなく別のステータスにしたい +: `bee issue close` を `bee issue edit --status <ステータスID>` に変更してください。ステータス ID は `bee status list ` で確認できます。 -
`edited` イベントが不要
-
トリガーの `types` から `edited` を削除し、「Comment PR link on newly added issues」ステップを削除してください。
-
+`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 index 2acd5d9a..d851af1d 100644 --- 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: ## カスタマイズ -
-
ドキュメント投稿が不要
-
「Post release notes to Backlog document」ステップと `BACKLOG_PROJECT`・`DOCUMENT_PARENT_ID` 環境変数を削除してください。
+ドキュメント投稿が不要 +: 「Post release notes to Backlog document」ステップと `BACKLOG_PROJECT`・`DOCUMENT_PARENT_ID` 環境変数を削除してください。 -
課題への通知が不要
-
「Collect issue keys ...」と「Comment release info ...」の2ステップを削除してください。
+課題への通知が不要 +: 「Collect issue keys ...」と「Comment release info ...」の2ステップを削除してください。 -
ドキュメントを特定のフォルダに入れたい
-
`DOCUMENT_PARENT_ID` にフォルダのドキュメント ID を設定してください。
-
+ドキュメントを特定のフォルダに入れたい +: `DOCUMENT_PARENT_ID` にフォルダのドキュメント ID を設定してください。 ## 関連するコマンド diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b9be41df..fcb22c07 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -96,6 +96,9 @@ importers: marked: specifier: ^17.0.3 version: 17.0.3 + remark-definition-list: + specifier: ^2.0.0 + version: 2.0.0 sharp: specifier: ^0.34.5 version: 0.34.5 @@ -1973,6 +1976,9 @@ packages: resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==} engines: {node: '>= 0.4'} + hast-util-definition-list@2.1.0: + resolution: {integrity: sha512-n3U2gleI8TYZ6eVFjE9TZsGTpaOQlMQj10+WZZFn6Ts5uEu/7XzB8HVLNeu5Sgu7Rv96ThFp79/U6bf/4pS0ew==} + hast-util-embedded@3.0.0: resolution: {integrity: sha512-naH8sld4Pe2ep03qqULEtvYr7EjrLK2QHY8KJR6RJkTUjPGObe1vnx585uzem2hGra+s1q08DZZpfgDVYRbaXA==} @@ -2018,6 +2024,9 @@ packages: hast-util-to-jsx-runtime@2.3.6: resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==} + hast-util-to-mdast@10.1.2: + resolution: {integrity: sha512-FiCRI7NmOvM4y+f5w32jPRzcxDIz+PUqDwEqn1A+1q2cdp3B8Gx7aVrXORdOKjMNDQsD1ogOr896+0jJHW1EFQ==} + hast-util-to-parse5@8.0.1: resolution: {integrity: sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==} @@ -2267,6 +2276,9 @@ packages: resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==} engines: {node: '>= 0.4'} + mdast-util-definition-list@2.0.0: + resolution: {integrity: sha512-aFWuASQs77BJndNSDcNdvB1HRqWZBptcEjwv67mnPbaAZsfwMHxI8MwoQxAz4I2bHx41hft/HDRC57ZkhpayOQ==} + mdast-util-definitions@6.0.0: resolution: {integrity: sha512-scTllyX6pnYNZH/AIp/0ePz6s4cZtARxImwoPJ7kS42n+MnVsI4XbnG6d4ibehRIldYMWM2LD7ImQblVhUejVQ==} @@ -2330,6 +2342,9 @@ packages: micromark-core-commonmark@2.0.3: resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==} + micromark-extension-definition-list@2.0.1: + resolution: {integrity: sha512-lQSkVTWNR0f9qzUbM4p0chJSecIRYvZBjnI+cWqN0k2zDSvzpduGJifWJj4SpCWF4TlpNV9amCF8Y1VEXdJubQ==} + micromark-extension-directive@3.0.2: resolution: {integrity: sha512-wjcXHgk+PPdmvR58Le9d7zQYWy+vKEU9Se44p2CrCDPiLr2FMyiT4Fyb5UFKFC66wGB3kPlgD7q3TnoqPS7SZA==} @@ -2845,6 +2860,9 @@ packages: rehype-format@5.0.1: resolution: {integrity: sha512-zvmVru9uB0josBVpr946OR8ui7nJEdzZobwLOOqHb/OOD88W0Vk2SqLwoVOj0fM6IPCCO6TaV9CvQvJMWwukFQ==} + rehype-minify-whitespace@6.0.2: + resolution: {integrity: sha512-Zk0pyQ06A3Lyxhe9vGtOtzz3Z0+qZ5+7icZ/PL/2x1SHPbKao5oB/g/rlc6BCTajqBb33JcOe71Ye1oFsuYbnw==} + rehype-parse@9.0.1: resolution: {integrity: sha512-ksCzCD0Fgfh7trPDxr2rSylbwq9iYDkSn8TCDmEJ49ljEUBxDVCzCHv7QNzZOfODanX4+bWQ4WZqLCRWYLfhag==} @@ -2860,6 +2878,9 @@ packages: rehype@13.0.2: resolution: {integrity: sha512-j31mdaRFrwFRUIlxGeuPXXKWQxet52RBQRvCmzl5eCefn/KGbomK5GMHNMsOJf55fgo3qw5tST5neDuarDYR2A==} + remark-definition-list@2.0.0: + resolution: {integrity: sha512-OOJ0zUrfUGITUNxOBnsipyFUjqq1m4AgYOqQk10jDXyz+RoODJL3qYvRn8qzYQDzRnz1wlCP3dbDEOpl05LlQw==} + remark-directive@3.0.1: resolution: {integrity: sha512-gwglrEQEZcZYgVyG1tQuA+h58EZfq5CSULw7J90AFuCTyib1thgHPoqQ+h9iFvU6R+vnZ5oNFQR5QKgGpk741A==} @@ -3098,9 +3119,16 @@ packages: trim-lines@3.0.1: resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==} + trim-trailing-lines@2.1.0: + resolution: {integrity: sha512-5UR5Biq4VlVOtzqkm2AZlgvSlDJtME46uV0br0gENbwN4l5+mMKT4b9gJKqWtuL2zAIqajGJGuvbCbcAJUZqBg==} + trough@2.2.0: resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==} + ts-dedent@2.2.0: + resolution: {integrity: sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==} + engines: {node: '>=6.10'} + tsconfck@3.1.6: resolution: {integrity: sha512-ks6Vjr/jEw0P1gmOVwutM3B7fWxoWBL2KRDb1JfqGVawBmO5UsvmWOQFGHBPl5yxYz4eERr19E6L7NMv+Fej4w==} engines: {node: ^18 || >=20} @@ -3194,6 +3222,9 @@ packages: unifont@0.7.4: resolution: {integrity: sha512-oHeis4/xl42HUIeHuNZRGEvxj5AaIKR+bHPNegRq5LV1gdc3jundpONbjglKpihmJf+dswygdMJn3eftGIMemg==} + unist-builder@4.0.0: + resolution: {integrity: sha512-wmRFnH+BLpZnTKpc5L7O67Kac89s9HMrtELpnNaE6TAobq5DTZZs5YaTQfAZBA9bFPECx2uVAPO31c+GVug8mg==} + unist-util-find-after@5.0.0: resolution: {integrity: sha512-amQa0Ep2m6hE2g72AugUItjbuM8X8cGQnFoHk0pGfrFeT9GZhzN5SW8nRsiGKK7Aif4CrACPENkA6P/Lw6fHGQ==} @@ -5124,6 +5155,17 @@ snapshots: dependencies: function-bind: 1.1.2 + hast-util-definition-list@2.1.0: + dependencies: + '@types/hast': 3.0.4 + '@types/mdast': 4.0.4 + '@types/unist': 3.0.3 + hast-util-to-mdast: 10.1.2 + mdast-util-definition-list: 2.0.0 + mdast-util-phrasing: 4.1.0 + transitivePeerDependencies: + - supports-color + hast-util-embedded@3.0.0: dependencies: '@types/hast': 3.0.4 @@ -5280,6 +5322,23 @@ snapshots: transitivePeerDependencies: - supports-color + hast-util-to-mdast@10.1.2: + dependencies: + '@types/hast': 3.0.4 + '@types/mdast': 4.0.4 + '@ungap/structured-clone': 1.3.0 + hast-util-phrasing: 3.0.1 + hast-util-to-html: 9.0.5 + hast-util-to-text: 4.0.2 + hast-util-whitespace: 3.0.0 + mdast-util-phrasing: 4.1.0 + mdast-util-to-hast: 13.2.1 + mdast-util-to-string: 4.0.0 + rehype-minify-whitespace: 6.0.2 + trim-trailing-lines: 2.1.0 + unist-util-position: 5.0.0 + unist-util-visit: 5.1.0 + hast-util-to-parse5@8.0.1: dependencies: '@types/hast': 3.0.4 @@ -5489,6 +5548,18 @@ snapshots: math-intrinsics@1.1.0: {} + mdast-util-definition-list@2.0.0: + dependencies: + '@types/mdast': 4.0.4 + '@types/unist': 3.0.3 + mdast-util-from-markdown: 2.0.3 + mdast-util-to-hast: 13.2.1 + mdast-util-to-markdown: 2.1.2 + micromark-extension-definition-list: 2.0.1 + unist-builder: 4.0.0 + transitivePeerDependencies: + - supports-color + mdast-util-definitions@6.0.0: dependencies: '@types/mdast': 4.0.4 @@ -5695,6 +5766,16 @@ snapshots: micromark-util-symbol: 2.0.1 micromark-util-types: 2.0.2 + micromark-extension-definition-list@2.0.1: + dependencies: + micromark-core-commonmark: 2.0.3 + micromark-factory-space: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-chunked: 2.0.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + ts-dedent: 2.2.0 + micromark-extension-directive@3.0.2: dependencies: devlop: 1.1.0 @@ -6406,6 +6487,11 @@ snapshots: '@types/hast': 3.0.4 hast-util-format: 1.1.0 + rehype-minify-whitespace@6.0.2: + dependencies: + '@types/hast': 3.0.4 + hast-util-minify-whitespace: 1.0.1 + rehype-parse@9.0.1: dependencies: '@types/hast': 3.0.4 @@ -6439,6 +6525,14 @@ snapshots: rehype-stringify: 10.0.1 unified: 11.0.5 + remark-definition-list@2.0.0: + dependencies: + hast-util-definition-list: 2.1.0 + mdast-util-definition-list: 2.0.0 + micromark-extension-definition-list: 2.0.1 + transitivePeerDependencies: + - supports-color + remark-directive@3.0.1: dependencies: '@types/mdast': 4.0.4 @@ -6790,8 +6884,12 @@ snapshots: trim-lines@3.0.1: {} + trim-trailing-lines@2.1.0: {} + trough@2.2.0: {} + ts-dedent@2.2.0: {} + tsconfck@3.1.6(typescript@6.0.0-dev.20260301): optionalDependencies: typescript: 6.0.0-dev.20260301 @@ -6898,6 +6996,10 @@ snapshots: ofetch: 1.5.1 ohash: 2.0.11 + unist-builder@4.0.0: + dependencies: + '@types/unist': 3.0.3 + unist-util-find-after@5.0.0: dependencies: '@types/unist': 3.0.3