こんな人に

ドキュメントを手直しなしで Markdown に移行

ドキュメントの移行とは、たいてい HTML を変換し、そのあと変換ツールが残したものを取り除くのにもっと長い時間をかけることです。Clean Web Clipper はその除去を中心に作られており、測定したのもそこです。512 ページで残った HTML タグは 0 でした。

変換のあとの手直し

変換自体は 1 秒で済みます。1 週間かかるのは、それについてくるすべてです。どのファイルの先頭にも繰り返される左側のナビゲーション、バージョンの切り替え、「このページの内容」のレール、フィードバックのウィジェット、パンくずリスト、8 列のフッター。それを 200 ページ分かけ合わせると、移行は、元のサイトごとに違うセレクターを使う検索と置換のプロジェクトになります。

そして、いちばん必要だった部分が傷んで届きます。コードブロックは言語を失うので、何もハイライトされず、読み手はシェルのコマンドと JSON の本文を見分けられません。セルにリストがある表は崩れます。注意書きは、警告であることを示すものが何もない、はぐれた段落になります。それを直すのは検索と置換の作業ではなく、すべてのページを読み直す作業です。

誰も計画していないのが、そのあとの監査です。6 週間後、新しいサイトのある段落が古いサイトにあったのか移行中に書かれたのかと誰かが尋ねます。変換したファイルが取得元のアドレスを持っていなければ、元のページを探し出す以外に答えはなく、その後停止されたドキュメントサイトでは、それは何も見つからないということです。取り込んだどのファイルにも source の行があれば 1 行で決着がつき、date の行があればどの版を取り込んだかに決着がつきます。

きれいに対応づけられるもの

• 見出し、リスト、表、コードブロック、脚注は、すべて標準の Markdown に対応づけられます。
• コードブロックは言語タグを保ちます。 技術系コーパスで 156 個中 73 個が残り、比較したエンジンは 20 個と 0 個でした。
• 測定した 512 ページで残った HTML タグは 0。
• ナビゲーションのサイドバー、バージョンの切り替え、「このページの内容」のレールは、変換せずに切り落とします。
• 注意書きやコールアウトは引用ブロックになります。 Markdown にはそれらの標準の構文がないからです。
• ファイル名のテンプレートとサブフォルダで、取り込んだ一式が増えても整理されたままです。
• どのファイルも取得元のアドレスを持つので、レビュー中も、取り込んだ段落を元のページまでたどれます。
• 脚注は、サニタイザーがそれらの依存する要素の id を削除する前に集めます。 参照リンクがそもそも残るかどうかを決める、順序の細部です。

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

## Workflow

Django can create migrations for you. Make changes to your models, then run:

```bash
python manage.py makemigrations
```

> **Note:** migrations are files on disk. Commit them with your code.

| Command         | What it does                              |
| --------------- | ----------------------------------------- |
| `makemigrations`| Writes new migrations from model changes  |
| `migrate`       | Applies migrations to the database        |

移行に向けた設定

設定 2 つ、フォルダ 1 つ、コミットについての作業ルール 1 つです。あとでレビューを可能にするのは、コミットのルールの部分です。

1. ドキュメントのリポジトリに、完成したページを置く場所とは別に import/ ディレクトリを作ります。移行が進んでいるあいだ、生の変換と編集済みのページを同じフォルダに置くべきではありません。
2. 拡張機能のアイコンから オプション を開き、保存先を import/ に向け、アイコンをクリックしたとき を「フォルダに保存」にします。30 ページはキー 30 回であるべきで、ウィンドウ 30 回であるべきではありません。
3. ファイル名のテンプレートを {domain}-{title} にします。2〜3 の元のサイトから集める取り込みではタイトルが常に重なり、「Overview」が overview-3 にならないようにするのがドメインです。
4. frontmatter で title、source、extraction をオンにします。source は 6 週間後の監査の問いに答え、extraction は、描画されたものではなく構造化データから来たページがどれかを教えてくれます。
5. 画像は含めないのではなくリンクのまま残します。その URL を使い続けることはありませんが、リンクは目録です。ページに図があったことを記録し、それはアセットの作業を計画するときに必要なものです。
6. タブやアコーディオンのあるページをクリップする前に、それを開きます。拡張機能はブラウザが描画したものを変換し、クリックで中身が挿入されるタブは、クリックされるまで DOM にありません。
7. 生の取り込みを 1 つのコミットとしてコミットし、構成し直しはそのあとのコミットで行います。そうすれば以後のどの差分も、あなたの変更と変換の変更が混ざったものではなく、編集上の変更だけを示します。

取り込みのための設定

これらは、1 回読んで忘れるフォルダではなく、人がページごとにレビューし、それから編集するファイル一式のために選んでいます。

## Installing

> **Warning:** upgrading across two major versions at once is not supported.

npm

```bash
npm install example-cli --save-dev
```

pnpm

```bash
pnpm add -D example-cli
```

どちらのタブも DOM に描画されていたので、両方が順番に取り込まれました。
クリックしたときにだけ描画されるタブなら、取り込まれていません。

3 つの移行

提供元のドキュメント 30 ページ

パートナーの API リファレンスを自社のドキュメントに置く必要があります。30 ページを、キー 1 回ずつ import/ にクリップします。コードブロックはタグ付きで届き（技術系コーパスでは 156 個中 73 個で言語タグが残り、比較したエンジンは 20 個と 0 個でした）、左側のナビゲーション、バージョンの切り替え、フィードバックのウィジェットはどこにも届きません。

そのあと編集するのは文章と構造です。編集しなくて済むのは、HTML をそのまま変換していればどのファイルの先頭にも置かれていた、ページあたり 200 行のサイドバーで、それこそ移行に何週間もかかる本当の理由です。

注意書きで組み立てられたガイド

元のガイドは警告、注記、ヒントのコールアウトを多用しています。Markdown にはどれの標準構文もないので、3 つとも引用ブロックになります。中身は残り、3 種類の区別は残りません。

それは始めたあとではなく前に知っておく価値があります。種類ごとの付け直しは手作業の一巡で、その量は元の資料次第だからです。生の取り込みの中の引用ブロックを調べれば、その一巡の規模が分かり、それはページごとに読むことではなく grep 1 回です。

サイトが停止される前の救出

ある製品が終了し、そのドキュメントは月末にオフラインになります。ここにはクローラーがないので 1 ページずつですが、どのページもヘッダーに元のアドレスを持つファイルとして届き、それが救出にあとから価値を持たせます。

別に計画すべきなのは画像です。画像は間もなく存在しなくなるサイトへのリンクのままなので、重要なページは期限の前に図を手で保存する必要があり、取り込んだファイルのリンクの目録がそのためのチェックリストになります。

ほかの変換方法との比較

移行はたいてい、このうち 2 つを組み合わせることになります。正直な比較は、手作業があるかどうかではなく、手作業がどこに来るかです。

取り込みのあとで直すべきもの

コールアウトがすべて同じに見える

警告、注記、ヒントはすべて引用ブロックになります。Markdown には対応づける先の標準の注意書き構文がないからです。テキストはそのままで、行頭の強調の記号もたいてい残るので、太字の「Warning:」で始まっていた警告は今もそう書かれています。種類ごとの付け直しは計画に入れておく一巡で、その規模は引用ブロックへの grep 1 回で分かります。

先頭に見出しのないページが入ってきた

空の見出しは取り除きます。また多くのドキュメントサイトでは、目に見えるページのタイトルは見出しではなく、記事の本文の外にあるナビゲーションの要素です。それでもタイトルは、ページ自身のメタデータから取る title の frontmatter の欄を通じてファイルに届きます。それを H1 に格上げするのは、取り込み全体にスクリプトで適用できる機械的な手順です。

画像のリンクがまだ古いサイトを指している

そうなります。拡張機能はバイナリをダウンロードしないので、どの画像も元の場所へのリンクで、取り込んだ一式は単体で完結しません。リンクは結果ではなく目録として扱ってください。どのページにいくつアセットがあるかを教えてくれ、それはアセットの移行にまさに必要な一覧です。

jsonld-articlebody と記録されたページがサイトと違って読める

そのページは記事のテキストを構造化データに入れていながら描画を終えなかったので、本文を構造化データから取りました。2 つは同じとは限りません。描画するページを構造化データより頻繁に更新するサイトでは、そのブロックに古い版が残ります。コミットする前に元と読み比べるべきなのは、そうしたページです。

これは何ではないか

移行ツールではありません。クローラーも、リンクの書き換えも、リダイレクトの対応表も、アセットのダウンロードもありません。画像は元のサイトへのリンクのままなので、取り込んだ一式は単体で完結しません。Markdown で表せないもの（タブ付きのコードブロック、インクルード、注意書きの種類、独自のコンポーネント）は最も近い素朴な表現に平らにするので、中身は残り、スタイルは残りません。そしてページが描画したものを変換するので、開いていないアコーディオンの中のテキストは DOM になく、クリップされません。

よくある質問