Skip to content

Commit 0bd368b

Browse files
lollipop-onlclaude
lollipop-onl
and
claude
authored
Replace HTML definition lists with Markdown syntax (#62)
* fix: prevent double-dash flags from being converted to em-dash in docs SmartyPants (remark-smartypants) converts `--` to `—` (em dash) inside `<code>` tags within the `<dl>` HTML block on the environment variables page. Use JSX expressions (`{'--flag'}`) to bypass the transformation and render flags like `--project`, `--repo`, `--client-id`, and `--client-secret` correctly. https://claude.ai/code/session_0163JhpTd1Sojez8yK7ARqnW * fix: use remark-definition-list to avoid SmartyPants em-dash in docs Replace the raw HTML `<dl>` block in environment-variables.mdx with Markdown definition list syntax (`: ` prefix). Add remark-definition-list plugin so Astro/Starlight renders them as `<dl>`/`<dt>`/`<dd>`. This fixes `--project`, `--repo`, `--client-id`, `--client-secret`, and `bee auth login --method oauth` being rendered with an em-dash (`—`) instead of double dashes due to SmartyPants typography conversion inside raw HTML blocks. https://claude.ai/code/session_0163JhpTd1Sojez8yK7ARqnW * refactor: replace raw HTML <dl> with Markdown definition list syntax Convert all remaining <dl>/<dt>/<dd> HTML blocks in docs to Markdown definition list syntax using the remark-definition-list plugin added in the previous commit. Files updated: - integrations/ai-agent.mdx - guides/authentication.mdx (inside <Card> components) - recipes/release-notify-issues.mdx - recipes/pr-lifecycle-sync.mdx https://claude.ai/code/session_0163JhpTd1Sojez8yK7ARqnW * docs: document Markdown definition list syntax in AGENTS.md Add guidance to the Documentation site section about using Markdown definition list syntax (term + `: description`) instead of raw <dl>/<dt>/<dd> HTML, including a note that it works inside JSX components like <Card>. https://claude.ai/code/session_0163JhpTd1Sojez8yK7ARqnW --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 0417108 commit 0bd368b

9 files changed

Lines changed: 168 additions & 53 deletions

File tree

‎AGENTS.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,26 @@ Command reference pages are **auto-generated** from CLI source code — do NOT c
6666

6767
**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.
6868

69+
#### Definition lists
70+
71+
The docs site supports Markdown definition list syntax via `remark-definition-list`. Use this instead of raw `<dl>`/`<dt>`/`<dd>` HTML:
72+
73+
```mdx
74+
<!-- Correct — Markdown definition list -->
75+
76+
用語
77+
: 説明文
78+
79+
<!-- Wrong — raw HTML -->
80+
81+
<dl>
82+
<dt>用語</dt>
83+
<dd>説明文</dd>
84+
</dl>
85+
```
86+
87+
This also works inside JSX components like `<Card>`.
88+
6989
#### Internal link conventions
7090

7191
All internal links in documentation content (`apps/docs/src/content/docs/`) must use **absolute paths with the base prefix `/bee/` and a trailing slash**:

‎apps/docs/astro.config.mjs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
11
import { defineConfig } from "astro/config";
22
import starlight from "@astrojs/starlight";
33
import starlightLinksValidator from "starlight-links-validator";
4+
import { defListHastHandlers, remarkDefinitionList } from "remark-definition-list";
45
import { loadCommandSidebar } from "./src/lib/sidebar-commands";
56

67
const commandSidebar = await loadCommandSidebar();
78

89
export default defineConfig({
910
site: "https://nulab.github.io",
1011
base: "/bee",
12+
markdown: {
13+
remarkPlugins: [remarkDefinitionList],
14+
remarkRehype: { handlers: { ...defListHastHandlers } },
15+
},
1116
integrations: [
1217
starlight({
1318
plugins: [

‎apps/docs/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
"@astrojs/starlight": "^0.37.6",
1313
"astro": "^5.5.0",
1414
"marked": "^17.0.3",
15+
"remark-definition-list": "^2.0.0",
1516
"sharp": "^0.34.5"
1617
},
1718
"devDependencies": {

‎apps/docs/src/content/docs/guides/authentication.mdx‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -90,25 +90,21 @@ OAuth クライアント ID とシークレットは、フラグまたは環境
9090
<Card title="API キーがおすすめな場合">
9191
手軽に始めたいなら API キーが最適です。
9292

93-
<dl>
94-
<dt>個人利用や CI/CD</dt>
95-
<dd>セットアップがシンプルで、環境変数だけで完結します。</dd>
93+
個人利用や CI/CD
94+
: セットアップがシンプルで、環境変数だけで完結します。
9695

97-
<dt>すぐに使い始めたい場合</dt>
98-
<dd>Backlog の個人設定から API キーを発行するだけで利用できます。</dd>
99-
</dl>
96+
すぐに使い始めたい場合
97+
: Backlog の個人設定から API キーを発行するだけで利用できます。
10098
</Card>
10199

102100
<Card title="OAuth がおすすめな場合">
103101
セキュリティを重視するなら OAuth がおすすめです。
104102

105-
<dl>
106-
<dt>チームでの利用</dt>
107-
<dd>OAuth クライアントを共有し、各メンバーが自分のアカウントで認証できます。</dd>
103+
チームでの利用
104+
: OAuth クライアントを共有し、各メンバーが自分のアカウントで認証できます。
108105

109-
<dt>有効期限の短いトークン</dt>
110-
<dd>OAuth のアクセストークンは有効期限が短いため、AI ツールや外部サービスにトークンを渡す場合でも、漏洩時のリスクを抑えられます。期限切れ時は bee が自動で更新します。</dd>
111-
</dl>
106+
有効期限の短いトークン
107+
: OAuth のアクセストークンは有効期限が短いため、AI ツールや外部サービスにトークンを渡す場合でも、漏洩時のリスクを抑えられます。期限切れ時は bee が自動で更新します。
112108
</Card>
113109

114110
## 複数スペースの管理

‎apps/docs/src/content/docs/guides/environment-variables.mdx‎

Lines changed: 12 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -12,26 +12,23 @@ description: |-
1212

1313
## 環境変数リファレンス
1414

15-
<dl>
16-
<dt><code>BACKLOG_SPACE</code></dt>
17-
<dd>デフォルトのスペースホスト名（例: <code>xxx.backlog.com</code>）。設定すると、<code>bee auth login</code> でスペースの入力を省略できます。<code>BACKLOG_API_KEY</code> と併用すると、ログイン不要で bee を利用できます。</dd>
15+
`BACKLOG_SPACE`
16+
: デフォルトのスペースホスト名（例: `xxx.backlog.com`）。設定すると、`bee auth login` でスペースの入力を省略できます。`BACKLOG_API_KEY` と併用すると、ログイン不要で bee を利用できます。
1817

19-
<dt><code>BACKLOG_PROJECT</code></dt>
20-
<dd>デフォルトのプロジェクト ID またはプロジェクトキー（例: <code>MY_PROJECT</code>）。設定すると、<code>--project</code> フラグを省略できます。</dd>
18+
`BACKLOG_PROJECT`
19+
: デフォルトのプロジェクト ID またはプロジェクトキー（例: `MY_PROJECT`）。設定すると、`--project` フラグを省略できます。
2120

22-
<dt><code>BACKLOG_REPO</code></dt>
23-
<dd>デフォルトのリポジトリ名（例: <code>my-repo</code>）。設定すると、<code>--repo</code> フラグを省略できます。</dd>
21+
`BACKLOG_REPO`
22+
: デフォルトのリポジトリ名（例: `my-repo`）。設定すると、`--repo` フラグを省略できます。
2423

25-
<dt><code>BACKLOG_API_KEY</code></dt>
26-
<dd>API キーによる認証に使用します。<code>BACKLOG_SPACE</code> と併用すると、<code>bee auth login</code> を実行しなくても認証済みの状態で bee を利用できます。CI/CD 環境で特に便利です。</dd>
24+
`BACKLOG_API_KEY`
25+
: API キーによる認証に使用します。`BACKLOG_SPACE` と併用すると、`bee auth login` を実行しなくても認証済みの状態で bee を利用できます。CI/CD 環境で特に便利です。
2726

28-
<dt><code>BACKLOG_OAUTH_CLIENT_ID</code></dt>
29-
<dd>OAuth 認証で使用するクライアント ID。<code>bee auth login --method oauth</code> 時に <code>--client-id</code> フラグの代わりに使用できます。</dd>
27+
`BACKLOG_OAUTH_CLIENT_ID`
28+
: OAuth 認証で使用するクライアント ID。`bee auth login --method oauth` 時に `--client-id` フラグの代わりに使用できます。
3029

31-
<dt><code>BACKLOG_OAUTH_CLIENT_SECRET</code></dt>
32-
<dd>OAuth 認証で使用するクライアントシークレット。<code>bee auth login --method oauth</code> 時に <code>--client-secret</code> フラグの代わりに使用できます。</dd>
33-
34-
</dl>
30+
`BACKLOG_OAUTH_CLIENT_SECRET`
31+
: OAuth 認証で使用するクライアントシークレット。`bee auth login --method oauth` 時に `--client-secret` フラグの代わりに使用できます。
3532

3633
## よく使うパターン
3734

‎apps/docs/src/content/docs/integrations/ai-agent.mdx‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,11 @@ bee はターミナルツールとして、AI エージェントの「手足」
1212

1313
bee のドキュメントサイトでは、LLM がコマンドの使い方を効率的に取得できるエンドポイントを提供しています。AI エージェントにドキュメントを読み込ませる際に活用してください。
1414

15-
<dl>
16-
<dt>[`/llms.txt`](/bee/llms.txt)</dt>
17-
<dd>コマンド一覧のサマリー。全体像の把握に最適。</dd>
15+
[`/llms.txt`](/bee/llms.txt)
16+
: コマンド一覧のサマリー。全体像の把握に最適。
1817

19-
<dt>[`/llms-full.txt`](/bee/llms-full.txt)</dt>
20-
<dd>全コマンドの完全なリファレンスを 1 ファイルで取得。</dd>
21-
</dl>
18+
[`/llms-full.txt`](/bee/llms-full.txt)
19+
: 全コマンドの完全なリファレンスを 1 ファイルで取得。
2220

2321
各ドキュメントページにも `.md` エンドポイントがあり、個別のページを Markdown 形式で取得できます。
2422

‎apps/docs/src/content/docs/recipes/pr-lifecycle-sync.mdx‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -124,22 +124,20 @@ jobs:
124124
125125
## カスタマイズ
126126
127-
<dl>
128-
<dt>ステータス ID を確認するには</dt>
129-
<dd>`bee status list <PROJECT>` でプロジェクトのステータス一覧と ID を確認できます。`STATUS_IN_PROGRESS` の値をプロジェクトに合わせて変更してください。</dd>
127+
ステータス ID を確認するには
128+
: `bee status list <PROJECT>` でプロジェクトのステータス一覧と ID を確認できます。`STATUS_IN_PROGRESS` の値をプロジェクトに合わせて変更してください。
130129

131-
<dt>ステータス変更が不要</dt>
132-
<dd>`bee issue edit` の行と `STATUS_IN_PROGRESS` 環境変数を削除すれば、リンクのコメントだけになります。</dd>
130+
ステータス変更が不要
131+
: `bee issue edit` の行と `STATUS_IN_PROGRESS` 環境変数を削除すれば、リンクのコメントだけになります。
133132

134-
<dt>自動クローズが不要</dt>
135-
<dd>「Close linked issues」ステップを削除してください。</dd>
133+
自動クローズが不要
134+
: 「Close linked issues」ステップを削除してください。
136135

137-
<dt>クローズではなく別のステータスにしたい</dt>
138-
<dd>`bee issue close` を `bee issue edit --status <ステータスID>` に変更してください。ステータス ID は `bee status list <PROJECT>` で確認できます。</dd>
136+
クローズではなく別のステータスにしたい
137+
: `bee issue close` を `bee issue edit --status <ステータスID>` に変更してください。ステータス ID は `bee status list <PROJECT>` で確認できます。
139138

140-
<dt>`edited` イベントが不要</dt>
141-
<dd>トリガーの `types` から `edited` を削除し、「Comment PR link on newly added issues」ステップを削除してください。</dd>
142-
</dl>
139+
`edited` イベントが不要
140+
: トリガーの `types` から `edited` を削除し、「Comment PR link on newly added issues」ステップを削除してください。
143141

144142
## 関連するコマンド
145143

‎apps/docs/src/content/docs/recipes/release-notify-issues.mdx‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -87,16 +87,14 @@ jobs:
8787
8888
## カスタマイズ
8989
90-
<dl>
91-
<dt>ドキュメント投稿が不要</dt>
92-
<dd>「Post release notes to Backlog document」ステップと `BACKLOG_PROJECT`・`DOCUMENT_PARENT_ID` 環境変数を削除してください。</dd>
90+
ドキュメント投稿が不要
91+
: 「Post release notes to Backlog document」ステップと `BACKLOG_PROJECT`・`DOCUMENT_PARENT_ID` 環境変数を削除してください。
9392

94-
<dt>課題への通知が不要</dt>
95-
<dd>「Collect issue keys ...」と「Comment release info ...」の2ステップを削除してください。</dd>
93+
課題への通知が不要
94+
: 「Collect issue keys ...」と「Comment release info ...」の2ステップを削除してください。
9695

97-
<dt>ドキュメントを特定のフォルダに入れたい</dt>
98-
<dd>`DOCUMENT_PARENT_ID` にフォルダのドキュメント ID を設定してください。</dd>
99-
</dl>
96+
ドキュメントを特定のフォルダに入れたい
97+
: `DOCUMENT_PARENT_ID` にフォルダのドキュメント ID を設定してください。
10098

10199
## 関連するコマンド
102100

0 commit comments

Comments
 (0)