HexoのoEmbedプラグインをnpmに公開した話(後編)

HexoにYouTubeなどのサイトを記事に埋め込むためのプラグインを作成して、npmに公開しました。この記事はその後編にあたります。前編は以下になります。

HexoのoEmbedプラグインをnpmに公開した話(前編)

Hexoタグの制作

前回はコンテンツ埋め込みのための業界標準であるoEmbedの説明まで行いました。今回はいよいよoEmbedを利用したHexoタグの制作と公開を行います。ここからはこれから実際にHexoタグを作ってみたい方や、OSS貢献に興味がある方向けに丁寧に書いてみたいと思います。

完成形をイメージする

制作を始める前に完成形をイメージします。今回Hexoのタグ名はoembedにして、後ろにパーマリンクを渡せるものとします。
パーマリンクがスライドの場合、oEmbedのレスポンスとしてはtypeがrichのものが帰ってくるので、パラメータのhtmlの値をそのまま表示すればよいだけです。大抵の場合htmlの中身はiframeタグになっています。あとは外側をdivタグで囲ってクラスを指定しておきます。こうすることで後で簡単にスタイルを適用できるようになります。outerとinnerで二重に囲っているのは要素をセンタリングしたい場合にinnerクラスが指定してあったほうが便利だからです。最初はouterだけだったのですが、htmlパラメータで返ってくるのがiframeかどうか保証はできないので念の為囲うことにしました。

Hexo タグ

{% oembed http://slide.com/slides/123456 %}

実際に展開されるHTML

<div class="oembed-outer">
  <div class="oembed-inner">
    <iframe width="560" height="315" src="http://slide.com/slides/xxxxx/yyyyy" ></iframe>
  </div>
</div>

もう一つ例を見てみましょう。今度は写真の場合です。写真の場合はoEmbedのtypeがphotoになるので自分でタグを生成します。といっても、aタグとimgタグを入れ子にするだけの単純なものです。aタグで囲うのは写真をクリックした際にもとのパーマリンク先に飛べるようにするためです。あとはoEmbedにtitleパラメータがあればimgのalt属性に指定するようにしておきます。あと、oEmbedの仕様ではオプションでmaxwidthとmaxheightを渡せるので、これもHexoタグにオプションとして渡せるようにします。以下の例ではmaxwidthに300、maxheightに400を指定しています。

Hexoタグ

{ oembed http://phote.com/photos/456789 300 400 %}

実際に展開されるHTML

<div class="oembed-outer">
  <a class="oembed-inner" href="http://phote.com/photos/456789">
    <img src="http://photo.com/abcde.png" alt="きれいな写真">
  </a>
</div>

モデルを探す

ある程度仕様がイメージできたら、次はパクリ元リスペクト元を探してきます。ライセンスには十分注意しましょう。公式のサンプルを参考にしたり一般的な構成を真似るくらいであれば特に言及はいらないと思いますが、ソースコードを流用する場合はライセンスに則って処理してください。ソースの流用がなくても独創的な機能を真似る場合は、READMEに謝辞を述べるのが礼儀だと思います。今回は以下を参考にさせて頂きました。

• Hexo公式のタグプラグイン
  • 公式のタグプラグインです。本体に取り込まれているためプラグインとしての参考にはなりませんでしたが、タグの作り方の参考にしました
• linkPreviewプラグイン
  • 本ブログでもお世話になっているタグです。構成の参考にしました
• hexo-tag-oembed
  • 前編で紹介したoEmbed対応タグです。 今回作ろうとしているタグはこれのパワーアップ版みたいなものです
  • ソースコードの流用はしていませんが、構成の参考にしました
• node-oembed
  • ライブラリとして利用させて頂きました
  • Discoveryに対応しています

一番簡単なタグを作ってみる

公式のドキュメントを参考に一番簡単なタグを作ってみます。以下は単なるhoge と表示するだけのタグです。hoge.jsというファイルに保存して[hexo dir]/themes/scripts配下に配置します。

hoge.js

hexo.extend.tag.register('hoge', function(){
  return '<span>hoge</span>';
});

配置ができたらHexoサーバを再起動して、ブログの記事でhogeタグを使ってみましょう。
レンダリングした投稿に「hoge」と表示されていて、HTMLが以下のようになっていれば、成功です。HTMLはChromeのデベロッパーツール等で確認してください。

Hexo タグ

{% hoge %}

実際に展開されるHTML

<span>hoge</span>

プラグイン化してみる

Hexoはプラグイン機能を持っています。プラグイン化するとソースコードを外出しできて、npmでインストールすることができるようになります。npmで公開するための必須の手順ですが、単に外出しできるだけでもGitによるソース管理が行いやすくなるので、早めにやったほうがいいと思われます。プラグイン化の方法は 公式に書いてあるとおり、驚くほど簡単です。適当なディレクトリ(hexo-hoge-plugin)を作って、メインのソースファイルであるindex.jsとnpmのメタファイルであるpackage.jsonを配置するだけです。

index.js

hexo.extend.tag.register('hoge', function(){
  return '<span>hoge</span>';
});

package.json

{
  "name": "hexo-hoge-plugin",
  "version": "0.0.1",
  "main": "index"
}

さっそく作成したパッケージをnpmでインストールしてみましょう。

$ npm install --save <パッケージのディレクトリのパス>

Hexoサーバを再起動してhogeタグが利用できれば成功です。このとき前節で作成したhoge.jsファイルをscriptsディレクトリから削除しておくことを忘れないでください(笑)。npmは一般的にはネット上のnpmリポジトリからダウンロードしてインストールしますが、このようにローカルのパスを指定してインストールすることも可能です。このときインストール先のnode_modules配下にはパッケージディレクトリへのシンボリックリンクが張られるだけなので、一度インストールをすればパッケージディレクトリのファイルを修正が同期します。したがって更新のたびにインストールするとかは必要ないです[^1]。

[^1]: ちなみにnpm linkというコマンドもあってこちらはさらに便利で、複数の非公開パッケージを開発するときに真価を発揮します。興味がある方はぜひ調べてみることをオススメします。

ソースコードをGit管理してみる

Gitにおけるファイル管理は非常に心強いです。こまめにコミットしておくことで至福の安心感が得られます。特に新しいモノを作ろうとしているときは試行錯誤の連続なのでバージョン管理があるとないとでは効率で大きな差がつくのでなるべく早い段階でGit管理に以降するようにしましょう。以下はおまじないのようなものです。反射的に打てるようになるまで写経しましょう(笑)。ちなみに公開予定のリポジトリのコミットログは英語だけで書くことをオススメします。拙くても日本語で書かれるよりはより多くの人に理解してもらえます[^2]。

$ cd <hexo_hote_pluginディレクトリ> # 管理対象のソースコードの一番上のディレクトリに移動
$ git init                        # Gitのレポジトリとして初期化
$ echo node_modules > .gitignore  # .gitignoreにnode_modules配下を無視するように記述
$ git add .                       # カレントディレクトリ配下のファイルをステージング
$ git status                      # 余計なファイルが入っていないか確認
$ git commit -m "initial commit"    # メッセージ付きでコミット

[^2]: 自分も頑張れば読めはしますが、書くのは苦手です・・・　話すのはもっと無理です・・・

oEmbedを利用したタグを作ってみる

さて、いよいよoEmbedを利用したタグ作りに取り掛かります。まず、oEmbedのプロトコルをどのように実装するかです。HTTPクライアントを使って素直に実装する手もありますが、Discoveryも含めるとちょっと面倒なので公開されているパッケージの中に良いものがないか探してみたところ、node-oembedパッケージがありました。これを使えば比較的ラクにoEmbedを実装できそうです。

npm

oembed

https://www.npmjs.com/package/oembed

oEmbed consumer library and tools. Latest version: 0.1.2, last published: 6 years ago. Start using oembed in your project by running `npm i …

あともう一つ決めなければいけないことは、エンドポイントの設定方法です。幸いにもHexoにはディレクトリのトップに_config.ymlという設定ファイルがあり、これに自由に設定を加えていけます。具体的には以下のような設定があったとします。classNameは冒頭で述べたCSSのクラス名の設定です。endpointsが具体的のoEmbedプロバイダを設定する箇所で、matchパラメータがパーマリンクのURLのホスト名に部分一致していたらそのエンドポイントのurlを利用するという仕様にします。正確なスキーマの検査をしなくても多分このレベルで実用になるだろうと判断しました。手を抜いたわけじゃないよ！

_config.yml

oembed:
  className: oembed
  endpoints:
    instagram:
      match: instagram
      url: http://api.instagram.com/oembed/
    gyazo:
      match: gyazo
      url: https://api.gyazo.com/api/oembed/
    flickr:
      match: flickr
      url: http://www.flickr.com/services/oembed/

上記の設定ファイルにはhexo.configでアクセスできます。例えばインスタグラムのエンドポイントのURLが欲しい場合はhexo.config.oembed.endpoints.instagram.urlです。これで、oEmbedのタグを実装する上での主要な情報と仕様が出揃いました。あとは基本的はWebプログラミングの知識があれば解ける問題です。Let’s Try!

答え合わせ

さて、皆様の出来栄えはいかがしょうか？以下のCodePenに自分のソースコードを日本語のコメント付きで載せたので参考にしてみてください。

See the Pen hexo-oembed by hinastory (@hinastory) on CodePen.

Hexoタグの公開

せっかく作ったので公開して多くの人に使ってもらいたいと思います。そのための手順を簡単に説明したいと思います。

GitHubでリポジトリを作成する

まずは、 GitHubにリポジトリを作成します。もしまだアカウントを作成していない方はSignUpから始めてください^3。以前に以下の記事でプライベートリポジトリの作り方を説明しましたが、今回は公開用のパブリックリポジトリです。

cats cats cats

GitHubのプライベートリポジトリに移行した話

https://hinastory.github.io/cats-cats-cats/2019/01/13/github/

新年そうそうビッグニュースが流れてきました。GitHubがプライベートリポジトリをタダで使わせてくれるってよ! ITmedia NEWSGitHub、無料ユーザーもプライベートリポジトリを使い放題にhttp://www.itmedia.co.jp/n…

リポジトリ名はダイレクトにhexo-oembedにしました。ライセンスは特にこだわりがなければHexoと同じMITライセンスにしておけばいいと思います。.gitignoreファイルはもうすでに作成済みなのでここであえて作成する必要はないです。リポジトリの作成自体は十秒もかからず終わります。以下が今回作成したGitHubのリポジトリです。

リポジトリの作成が終わったらローカルのリポジトリとGitHubのリポジトリをリンクさせます。

$ git remote set-url origin {new url}

README.mdを書く

README.mdは公開したパッケージの説明や利用法をMarkdownで書くファイルです。リポジトリのトップにこのファイルを置いておけばGitHubのリポジトリのトップページに表示してくれるので、公開時にはほぼ必須のファイルです。書き方も大体以下のようにリポジトリ名->リポジトリの簡単な説明 -> 特徴 -> インストール方法 -> 利用方法 -> 設定(あれば)　-> 謝辞(利用or参考にしたものがあれば) -> ライセンスの順に書いていけばOKです。

# hexo-oembed

Embed [oEmbed](https://oembed.com/) item on your [Hexo](https://hexo.io/) article.

Features
--------

- Supports A
- Supports B

## Installation

`npm install hexo-oembed --save`

## Usage

・・・

## Configuration

...

## Thanks

## License

MIT

実はここが今回一番苦労したところです。oEmbedはともかくoEmbed Discoveryとかエンドポイントの設定方法とか説明しなければいけない部分がそこそこあるので、どうしたものかと悩みました。特に英語が苦手なのでGoogle先生のお力も拝借したのですがイマイチ自信がありません・・・

package.jsonを書く

すでにnpmでインストールするために最低限のpackage.jsonは記述していると思いますが、npmに公開するためにはさらに追加の記述が必要です。以下がほぼ最低限の公開用package.jsonです。特に気をつけなければ行けないのはバージョン番号です。セマンティック バージョニングになるべく厳密に従うようにしてください。あと、ファーストバージョンは1未満のバージョンから初めるのが慣例です。ある程度成熟したと感じたときにバージョン1をリリースしてください。

{
  "name": "hexo-oembed",
  "version": "0.1.5",
  "description": "embed oEmbed item on your Hexo article.",
  "main": "index.js",
  "repository": {
    "type": "git",
    "url": "git@github.com:hinastory/hexo-oembed.git"
  },
  "bugs": {
    "url": "https://github.com/hinastory/hexo-oembed/issues"
  },
  "keywords": [
    "hexo", "blog","plugin","helper","tag","oembed","youtube","slideshare","speakerdeck","twitter","vimeo","codepen","pixiv","instagram","flickr","gyazo"
  ],
  "author": "hinastory",
  "license": "MIT",
  "dependencies": {
    "hexo-util": "^0.6.3",
    "oembed": "^0.1.2"
  }
}

あと、お気づきだと思いますがキーワード盛り盛りですね(笑)。ここのキーワードはnpmの検索時に参照されるので、嘘偽りがなければできるだけ多く記載したほうが良いです。特に今回のhexo-oembedみたいにパッケージ名だけだと具体的に何をするものか分からない場合はkeywordに力を入れましょう。

GitHubに公開する

GitHubに公開するのは簡単です。git pushするだけです。簡単なんですが、以下のコマンドを打った瞬間に全世界に公開されしまうのでgit diffやgit showで余計なファイルやコミットがないか再確認してからpushしましょう。一番ありがちなのは必要なファイルをgit addし忘れてpushすることです。他にもプライベートアクセスキーとか重要な情報も一緒にコミットしてしまったりとかあります。もし間違ったコミットをしてしまった場合は、早い段階であればforce pushでもみ消せますがマナーとしては最低ですので最後の手段としましょう。

$ git push origin master

ブランチをプッシュしたら忘れずにタグもプッシュしておきましょう。GitHubの場合タグのプッシュが新バージョンのリリースとみなされるので、リリース直前には必ずタグを打つようにします。

$ git tag v0.1.5
$ git push origin v0.1.5

npmに公開する

npmに公開するのはもっと簡単です。公開するパッケージ直下でnpm publishを打つだけです。npmのアカウントを持っていなければ作成する必要がありますが、GitHubのアカウントでログインできるので手間はそれほどかかりません。アバターの設定にはGravatarが利用できます。これも持っていなければWordPress.comにログインしてすぐに作ることができます。

npm publishに成功したらnpmからページを確認してみます。自分のアバターのメニューのPackagesからも確認できますし、パッケージ名やキーワードで検索をかければ出てきます。

npm

hexo-oembed

https://www.npmjs.com/package/hexo-oembed

embed oEmbed item on your Hexo article.. Latest version: 0.1.8, last published: 2 years ago. Start using hexo-oembed in your project by runn…

ページの確認ができたらnpm installしてパッケージがネットからインストールできるか試してみましょう。このときローカルバージョンをインストールしている場合は一旦npm uninstallしてから実行してください。

READMEにバッジをつける

GitHubのリポジトリを眺めているとREADME.mdにイカすバッジが着いているのを見かけることがあります。や みたいな奴です。

これらのバッジはカッコいいだけでなく、必要な情報が視覚的にわかりやすいという実用面も大きいのでぜひ貼りましょう。まず一番目に紹介するのはnpmパッケージをかっこよく表示してくれる NodeICOです。ドメイン名にこだわりが感じられます(笑)。npmのパッケージ名を指定するだけですぐに作ってくれるので張らない手はないです。

次に紹介したいのは Shields.ioです。Shields.ioではOSS向けに高いクオリティのバッジを提供しています。種類も豊富でカスタマイズも可能なので、大抵の用途のバッジはここで作成することができます。上記のlicenseのバッジはここで作成しました。

最後に紹介したいのはCode Climiteです。ここはGitHubのリポジトリからOSSの品質を測定するサービスを提供しています。そしてその結果はバッジとして表示可能になっています。上記のこのバッジはCode Climiteを利用しています。hexo-oembedのページには、測定結果の詳細が載っているのでパッケージの改善に役立てる事ができます。

Hexo本家のプラグイン一覧に載せてもらう

ようやく公開の最終工程の一歩手前です。実は拡張の公開は以下のとおり大きく分けて4段階あって、今までおこなったのは2段階目までです。3番目は見逃されがちですが利用者の観点からすれば非常に重要です。ここに載せてもらえるか否かでリーチできるターゲット規模が大きく変わるので手を抜かずにやり遂げましょう。

1. パブリックソースリポジトリに公開する

• GitHub, GitLab, Bitbucket, Mercurial・・・

2. パブリックパッケージリポジトリに公開する

• npm, RubyGems, PyPI CPAN, MvnRepository, NuGet, OS系パッケージ管理システム・・・

3. 公式の拡張リストに記載してもらう
4. ブログやツイッター等で告知する

とはいっても、気負う必要はまったくありません。最近は公式のサイト自体GitHubで管理でしているところが増えてきているので、ドキュメントを修正してプルリクエストを投げるだけです。バグ修正のプルリクエストと変わらないというかむしろそれより敷居は低いといっても過言ではありません。
さらにHexoの場合には公式サイト自体がHexoで構築されているため、ドキュメントの修正確認に新しい知識は不要です。具体的には公式の手順を確認してもらう必要がありますが、たった5ステップで通常のバグ修正とほぼ変わりないことがわかると思います。

注意点としては、プルリクエストには各リポジトリにマナーがあるのでコントリビューションガイドにはよく目をとおすことと、過去のクローズ済みのプルリクエストを確認して自分のプルリクエストに問題ないか確認することを忘れないようにしましょう。マナー違反のプルリクは優しく注意してくれる場合もありますが、問題が多ければ放置や強制クローズもありえます。ちなみに今回のプルリクは半日程度でマージしてもらえました[^4]。

マージしてもらったら公式のプラグイン一覧でoembedで検索して、問題なく掲載されているか確認します。自分の1件しか引っかからなかったので、どうやらhexo-tag-oembedの方は公式への登録を行っていなかったみたいです。もったいない・・・

[^4]: このプルリクです。

ブログやツイッター等で告知する

まさしくこの記事です・・・

hexo-oembedの今後

npmパッケージとしては結構ニッチかなと思っていましたが、公開から一週間も経たないうちにダウンロード数が200を超えたので意外とニーズはあったみたいです。ということでしっかり開発およびメンテナンスはしていきたいと思います。

まず開発の基本方針として、サイト固有の対応を入れるつもりはないです。それやりだすとキリがないので・・・実はjquery-oembed-allというライブラリも見つけていたのですが、更新が止まっていたし自分がこのようなものを作ろうと思ってもメンテナンスが辛そうなので正直やりたくありません。しかもこのライブラリのフォールバック先のYQL (Yahoo! Query Language)は2019/1/3で終了したみたいです。

ただちょっと面白いなと思ったのはフォールバック先にOpen Graph protocolがあることです。OGP対応は割とメジャーなSEO対策でリンク先のサムネイルや説明の表示でお馴染みだとおもいます。もちろんこのページもOGPには対応しています。hexo-oembedのフォールバック先として一応Embed.lyには対応していますが^5、OGPへのフォールバックは今後検討しようかと思います。

もちろんプルリクは大歓迎です。またバグ報告、ご意見・ご要望はGitHubのIssuesにお願いします^6。

まとめ

既存のOSSへの貢献としてメジャーなのはバグ報告したりプルリクを出したりすることだと思いますが、プラグインを作って公開して公式の載せてもらうまでを丁寧に解説した入門記事は意外と少ないと感じました。断片的な記事は多いのですが、それだとどういう流れなのか入門者にわかりづらいかなと思い、本記事ではhexo-oembedをテーマにOSSへの貢献への流れを要点を絞って解説するようにしました。

実際に既存のOSSへの貢献を始めるには、いきなり本体に手をだすよりもプラグインから手をだした方がうまくいく場合が多いです^7。プラグインを通して本体を見たほうが理解しやすいですし、プラグインを作ってる最中に本体のバグを見つけることも多いので本体へのプルリクを書く動機にもなります(笑)。そのうちプルリクを送り続けていれば本体側にも十分詳しくなってコラボレーターとして招待されるかもしれません。実際にプラグインから始めてそのOSSへのメンテナーになった人は数多くいるので、まずOSSに貢献してみたいと思ったら気に入ったOSSを見つけてプラグイン機能を探して、実際に作ってみることをオススメします。

最初はHexoタグの作り方を簡単に紹介する記事にする予定でしたが、もしかしたら既存のOSSへの貢献の入門記事としてもニーズがあるのではないかと思ったのが今回の記事を書こうと思った動機です。長くなってしまいましたが本当にここまで読んで頂いてありがとうございました。この記事が読んでくれた方のOSS貢献の一助となれば幸いです。