こんな人に

API ドキュメントをコードごと Markdown で保存

Clean Web Clipper は、コードブロックのクラス、親要素、ハイライターが残したマークアップからページ上の言語を読み取り、コードブロックに書き込みます。9 ページの技術系コーパスでは、156 個のコードブロックのうち 73 個でタグが残りました。比較した 2 つのエンジンでは 20 個と 0 個でした。

クリップしたドキュメントに手直しが必要な理由

ドキュメントの大半はコードで、コードこそ多くのクリッパーが取りこぼす部分です。フレームワークのドキュメントや、また必要になる回答を保存してノートに貼り付けると、コードブロックはどれもタグなしです。js も bash も sql もありません。色が消え、シェルのコマンドと JSON の本文を一目で見分ける一番速い手段も一緒に消えます。

残りの被害は構造に出ます。セルにコード例がある表は 1 行につぶれます。バージョンの切り替えと「このページの内容」のレールが記事の途中に入り込みます。コードウィジェットを包む div がマークアップのまま残ります。これを手で直すのは記憶からノートを書くより時間がかかるので、たいていの人はドキュメントをクリップするのをやめ、情報が古くなるまでタブを開いたままにします。

そのタブが 3 つ目の問題です。ドキュメントにはバージョンがあり、URL にはたいていありません。v4 のために読んだページはいつの間にか v6 になり、フラグの名前が変わり、オプションが消え、ブックマークは相変わらず開きます。ただし別の文章に。実際にどのバージョンに合わせて作ったのかは、ノートのどこにも記録されていません。URL とページ自身の日付をヘッダーに持つファイルなら 1 年後もその問いに答えられますが、ブックマークが答えられたことはありません。

代わりにノートに入るもの

• コードブロックにタグが付きます。 タグなしではなく ```js なので、Obsidian でも VS Code でも GitHub でも、貼り付けた瞬間にハイライトが効きます。
• 言語は推測ではなく読み取ります。 サイト自身のハイライターが残したクラスから取るので、タグの正しさは元のページと同じです。
• セルにコードがある表も崩れません。 技術系コーパスで 15 個中 12 個が残り、比較した各エンジンは 7 個でした。
• 参照リンクは [^1] の脚注になり、定義は末尾にまとまるので、仕様書の出典はノートの中でもたどれます。
• サイドバーとバージョンの切り替えは変換せずに切り落とします。 測定した 512 ページで、残った HTML タグは 0 でした。
• 抽出は描画後の DOM で行うので、JavaScript で作られたドキュメントサイトも見たとおりに取り込めます。
• Reddit のスレッドは構造と各コメントのスコアを保ちます。 ライブラリについての本当の答えの半分はそこにあります。
• extraction 欄が経路を示します。 dom、またはページが構造化データに本文を入れて描画しなかった場合は jsonld-articlebody です。

• この数字の出どころ：エンジンのバージョンと日付を載せたベンチマーク

The JSON API returns some data that looks like this:

```js
[
  { category: "Fruits", price: "$1", stocked: true, name: "Apple" },
  { category: "Vegetables", price: "$2", stocked: true, name: "Spinach" }
]
```

## Step 1: Break the UI into a component hierarchy

ドキュメント向けの設定

一度 6 分かければ、あとはショートカットが引き受けます。初期設定は記事を読むために調整されていて、ドキュメントには別のファイル名、著者欄なし、画像なしが向いています。

1. 拡張機能をインストールし、アイコンをツールバーに固定します。アイコンを右クリックして オプション を選ぶと、設定がタブで開きます。
2. アイコンをクリックしたとき を「フォルダに保存」にします。これでクリップが、ウィンドウに邪魔されないキー 1 回の操作になります。プレビューウィンドウは道具に慣れるまでは役に立ちますが、慣れたあとは邪魔になります。
3. フォルダを選びます。作業中のリポジトリにある docs/clips のように、すでにバージョン管理しているディレクトリを指定します。ブラウザが一度だけ確認し、そのプロファイルで許可を記憶します。
4. ファイル名のテンプレートを {domain}-{title} にします。4 つのフレームワークにはどれも「Getting started」というページがあり、名前にドメインがないと 4 つ目は黙って getting-started-4 になります。
5. frontmatter の欄では source と extraction を残し、author をオフにします。ドキュメントに署名があることはまれで、全ファイルにある空の欄はいずれ消すことになるノイズです。
6. 画像を 含めない にします。他人の IDE のスクリーンショットは検索できず、画像のリンクは移動する CDN を指しています。
7. chrome://extensions/shortcuts を開き、Alt+Shift+M が割り当てられていることを確認します。ほかの拡張機能に取られていたら、ここで取り戻します。

開発者に合う設定

初期設定から変える価値のある値と、それが読書一般ではなくドキュメントにとってなぜ大事なのかをまとめました。

Run the migration before starting the server:

```
./bin/migrate --env production
```

```sql
SELECT id, created_at FROM sessions WHERE expires_at < now();
```

2 つ目のコードブロックには class="language-sql" が付いていました。
1 つ目には何もなく、推測でタグを付けずにタグなしのまま残しています。

3 つの作業場面

実際に合わせたバージョンを固定する

フレームワークのドキュメントの v4 ブランチで、v5 で名前が変わった設定フラグのページを読んでいます。Alt+Shift+M を押すと、ファイルは docs/clips に example-dev-configuration-reference.md として保存され、source は /v4/ の URL を指し、ヘッダーにはページが示した日付が入ります。

8 か月後、本番でそのフラグの挙動が変わり、なぜそう設定したのか誰も覚えていません。クリップはリポジトリの、変更と同じ範囲のコミットにあり、どのバージョンのドキュメントに基づいて決めたのかを示しています。いまの URL は v6 を返し、そのフラグにはもう触れてもいません。

本当に解決してくれたフォーラムのスレッド

公式ドキュメントは順調な場合しか書いておらず、あなたのケースの解決策は Reddit のスレッドの 4 階層下にあります。採用された回答は 140 ポイントで、30 ポイントの誤った回答の下にあります。スレッドをクリップすると、サイト別ルールが threads に振り分け、コメントの構造は入れ子の引用ブロックとして、各スコア付きで取り込まれます。

読み返すときに大事なのはスコアです。スレッドを平らにコピー＆ペーストすると順位の手がかりが丸ごと失われ、コミュニティがどれに同意したのか分からないまま 5 つの意見を読み直すことになります。

変数の表をそのままプルリクエストに

デプロイのガイドには 18 個の環境変数の表があり、そのうち 3 つのセルにコード例があります。ページで表を選択し、選択範囲をクリップして、Markdown をプルリクエストの説明に貼り付けます。スクリーンショットではなく GFM の表なので、GitHub は表として表示します。

15 個の表からなる技術系コーパスで、このシリアライザーは 12 個を残し、比較した各エンジンは 7 個でした。汎用の変換ツールを壊すセルはまさにこういう、コードやリストが入ったセルです。

よくあるやり方との比較

どれも使える方法で、どれもチームの誰かが今まさにやっていることです。3 列目は正直なコストで、この拡張機能も含みます。

うまく出てこないとき

コードブロックにタグが付かないのはなぜ？

ページが言語を示していなかったからです。Clean Web Clipper はサイト自身のハイライターが残したクラスから言語を読み取り、コードを見て推測はしません。クラスのない手作業で装飾したサンプルはタグなしになり、それが正直な結果です。シェルの断片に推測で python タグを付けるのはタグがないより悪く、ハイライトが自信満々に間違った部分に色を付けてしまいます。

ガイドの半分が抜けているのはなぜ？

ほとんどの場合、タブかアコーディオンです。拡張機能はブラウザが実際に描画したものを変換し、クリックしたときにだけ中身が挿入されるタブは、クリックするまで DOM にありません。タブを開き、セクションを展開してからクリップするか、切り替えごとに 1 回ずつクリップします。サイトがすべてのタブを描画して CSS で隠している場合は、すべてが順番に取り込まれます。

記事がないと言われるのはなぜ？

API のプレイグラウンド、検索結果、パッケージの一覧は大半がリンクのラベルで、拡張機能はこれらを意図的に拒否します。抽出した文字の約 4 分の 1 を超える部分がリンクの中にあれば、300 件の項目を渡す代わりに「記事なし」と報告します。常に何かを返すエンジンより「有用なテキストの割合」の点数が低く出るのは、この拒否のためです。

ファイルの extraction: "jsonld-articlebody" は何を意味する？

ページが記事のテキストを構造化データに入れていながら DOM への描画を終えなかったので、本文を構造化データから読み取ったという意味です。2 つの経路は内容が違うことがあるので、隠さずに記録しています。構造化データの写しは古い下書きのこともあれば、唯一の完全な版のこともあります。この値を見たら、テキストに頼る前に元のページを一度確認する価値があります。

しないこと

ドキュメントサイトを巡回はしません。1 回に 1 ページ、開いているページだけです。画像、図、その他のバイナリはダウンロードせず、画像のリンクは元のサイトを指したままです。タグのないコードブロックの言語は推測しないので、ハイライターがクラスを残さないページではタグの誤ったブロックではなくタグなしのブロックになります。そして API のプレイグラウンドや検索結果のような記事の本文がないページでは、リンク 300 件を渡す代わりに「記事なし」と報告します。

よくある質問