HTML Docset の作り方

Docset は以下のようなディレクトリ構造になってます。

<name>.docset/
├── Contents
│   ├── Resources
│   │   ├── Documents
│   │   └── docSet.dsidx
│   └── info.plist
├── icon.png
└── icon@2x.png

この中で重要なのが

  1. Documents
  2. docSet.dsidx
  3. info.plist

です。

Documents

この中にはHTMLファイルを格納します。Dash ではドキュメント(HTML)を開くと時に単にDocuments/からのパスで開こうとします。

HTMLファイルであれば何でもいいので静的サイトジェネレーターの選定は自由です。

docSet.dsidx

索引する為のデータです。例えば「typescript: interfaces」と検索した時に「Interfaces」が出てくるのは、このファイルに「Interfaces の時はこのタイプでこの HTML ファイルね」と登録されている為です。これは Sqlite3 ファイルで作ります。

Sqlite3 へはsqlite3 docSet.dsidxのように入り、

CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);
CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);

でテーブルを作った後、

INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES ('Interfaces', 'Guide', '/interfaces.html');

のような感じでデータを入れていきます。基本的はここはスクリプトを組んで実行する部分だと思います。

info.plist

Dash でのメタ情報を設定します。例えばtypescript:入力した時に、TypeScript Docset だけの検索モードになるのは、このファイルに「typescriptをキーワードとして使ってね」のように記述されてる為です。

基本的にこれは以下の[nN]ameを自分の環境に合わせて書き換えるだけでいいと思います。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleIdentifier</key>
    <string>name</string>
    <key>CFBundleName</key>
    <string>Name</string>
    <key>DocSetPlatformFamily</key>
    <string>name</string>
    <key>isDashDocset</key>
    <true/>
    <key>isJavaScriptEnabled</key>
  <true/>
</dict>
</plist>

アイコン

オプショナルですが<name>.docset直下にicon.pngicon@2x.pngを置くとキーワードを入力した時にアイコンが付いて分かりやすくなります。

icon.png16x16icon@2x.png32x32のサイズでそれぞれ作成します。

作った Docset を登録

Preferences > Docsets > + > Add Local Docset をクリックするとファインダーが開きます。ここで先程の<name>.docsetを開けば登録されるはずです!

も参照してください。

dash-feed で配信する

dash-feed を提供するとその URI リンクを開いただけで利用者が対象の Docset をインストールできるようになります。

この dash-feed は XML で以下のように記述します。(このサイトのフィード)

<entry>
  <version>1.0.0</version>
  <ios_version>1</ios_version>
  <url>https://github.com/nju33/nju33.com-docset/raw/master/nju33.tgz</url>
</entry>

versionios_versionは最新のバージョンを置きます。Docset を更新する時は、このバージョンを上げる必要があります。(同じバージョンではアンインストール→インストールをしないと更新できませんでした。)

urlへは<name>.docsettgz化したファイルへの URL を記載します。

フィードを提供するにはdash-feed:スキーマを使い、後に続けてフィードへのエンコードした URL を続けます。(このサイトの例: dash-feedd://https%3A%2F%2Fnju33.com%2Fdash-feed%2Fnju33.com.xml

注意点として最後の<name>.xml<name>が Docsets 一覧の名前に使われるのでdash-feed.xmlのような名前ではなく、<name>.docset<name>と同じものにするのがいいと思おいます。

nju33.com を Dash で読む

このサイト(nju33.com)用の docset を作りました。2つの方法で使えます。

  1. dash-feedを単に開く
  2. ローカルへソースをダウンロードしインストール

2つ目の方法はこのリポジトリをクローンし、Preferences > Docsets > + > Add Local Docset で、持ってきたリポジトリファイルのnju33.docset/ディレクトリを指定するだけです。

nju33をキーワードとして使い、後に<note名> [postタイトル]のように続けることで記事を検索できます。(例: nju33: typescript string

良ければ使ってみてください!