Merge pull request #3 from hirano00o/fix/css-robustness-and-standalone-filter

fix: CSS specificity 強化とインラインリンクの変換除外

Author: hirano00o

README.md

@@ -7,10 +7,47 @@ GitHub blob URL を、シンタックスハイライト付きコードビュー
 `<script>` タグで読み込むと、ページ内の GitHub blob URL を持つ `<a>` タグを自動的に変換します。
 
 ```html
-<script src="dist/git-code-embed.min.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/hirano00o/git-code-embed@v0/dist/git-code-embed.min.js"></script>
 <a href="https://github.com/owner/repo/blob/main/src/index.ts#L1-L10"></a>
 ```
 
+行範囲（`#L1-L10`）を省略するとファイル全体を表示します。
+
+## 変換対象の条件
+
+**前後に他のコンテンツがない「単独」の `<a>` タグのみ**を変換します。
+文中に埋め込まれたリンクや、同じ行に複数並んだリンクは変換されません。
+
+隣接ノードの判定ルール：
+
+| 隣接ノード | 扱い |
+|---|---|
+| なし（親要素の端） | 単独とみなす ✅ |
+| 空白・改行のみのテキスト | 単独とみなす ✅ |
+| `<br>` | 単独とみなす ✅ |
+| `<p>`, `<h1>`〜`<h6>`, `<div>` 等のブロック要素 | 単独とみなす ✅ |
+| 文字を含むテキスト | 文中リンクとみなし変換しない ❌ |
+| 別の `<a>` 等のインライン要素 | 複数リンクとみなし変換しない ❌ |
+
+```html
+<!-- 変換される -->
+<p><a href="https://github.com/owner/repo/blob/main/src/index.ts"></a></p>
+
+<!-- 変換される（ブロック要素に挟まれた単独リンク） -->
+<h2>実装例</h2>
+<a href="https://github.com/owner/repo/blob/main/src/index.ts"></a>
+<h2>次のセクション</h2>
+
+<!-- 変換されない（文中リンク） -->
+<p>詳細は<a href="https://github.com/owner/repo/blob/main/src/index.ts">こちら</a>を参照。</p>
+
+<!-- 変換されない（複数リンクが並んでいる） -->
+<p>
+  <a href="https://github.com/owner/repo/blob/main/a.ts"></a>
+  <a href="https://github.com/owner/repo/blob/main/b.ts"></a>
+</p>
+```
+
 ## はてなブログでの使い方
 
 ### 1. はてなブログにスクリプトを読み込む
@@ -19,21 +56,44 @@ GitHub blob URL を、シンタックスハイライト付きコードビュー
 以下を貼り付けて保存します。これによりブログ全ページに適用されます。
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/hirano00o/git-code-embed@v0/dist/git-code-embed.min.js" defer />
+<script src="https://cdn.jsdelivr.net/gh/hirano00o/git-code-embed@v0/dist/git-code-embed.min.js" defer></script>
 ```
 
 ### 2. 記事に GitHub blob URL を貼る
 
-記事の編集画面（見たままモードやMarkdownモード）でリンクを挿入するだけで動作します。
-スクリプトがページ読み込み時に全リンクを自動スキャンして変換します。
+**単独の行に URL を貼ることが必要です。** 前後に文字が続く形で挿入すると変換されません。
 
-Pro プランの場合は HTML 編集モードで直接 `<a>` タグを記述することもできます。
+#### 見たままモード・Markdownモード
 
-```html
-<a href="https://github.com/owner/repo/blob/main/src/index.ts#L1-L10"></a>
+リンクを単独の段落として挿入します。Markdown の場合は前後に空行を入れます。
+
+```markdown
+コードを確認してください。
+
+https://github.com/owner/repo/blob/main/src/index.ts#L1-L10
+
+上記がエントリーポイントです。
 ```
 
-行範囲（`#L1-L10`）を省略するとファイル全体を表示します。
+> **注意:** はてなブログの見たままモードでは、URL を貼り付けると自動的にリンクカードに変換される場合があります。変換された場合は `<a>` タグが単独行に配置されるため、git-code-embed も正しく動作します。
+
+#### HTML編集モード（Pro プランまたは HTML モード）
+
+`<a>` タグを `<p>` タグで囲み、単独で配置します。
+
+```html
+<!-- 正しい書き方: <p> で囲んで単独行に置く -->
+<p><a href="https://github.com/owner/repo/blob/main/src/index.ts#L1-L10"></a></p>
+
+<!-- 動作しない: 文中に埋め込む -->
+<p>詳細は<a href="https://github.com/owner/repo/blob/main/src/index.ts">こちら</a>を参照。</p>
+
+<!-- 動作しない: 複数リンクを並べる -->
+<p>
+  <a href="https://github.com/owner/repo/blob/main/a.ts"></a>
+  <a href="https://github.com/owner/repo/blob/main/b.ts"></a>
+</p>
+```
 
 ## 既知の制限