アウトライン生成ライブラリ、document-outliner をリリースしました

この記事は Advent Calendar 2018の25日目のエントリーです。

いつもお世話になっております。 今回は2019年リリース予定のa-blog cms Ver. 2.10 に搭載予定の「目次作成機能」を一足先にライブラリ化したものを紹介するものになります。

• 公式ページ
• GitHub

概要

見出し生成機能を ブログコンテンツ や マニュアル系コンテンツ などで使用したいと、多くの方にご要望をいただいており、 a-blog cms Ver. 2.10 で搭載するために開発することになりました。

ただせっかくなので、a-blog cmsユーザーでない方にも利用していただけるように、オープンソースライブラリとして公開するようにしました。 JavaScriptのライブラリですので、特にCMSなどのシステムに依存はなく、どなたでも簡単に導入していただけれるようになっています。

仕様

• 文章のアウトラインを ul/ol でマークアップしたものを出力
• アウトラインアルゴリズムは、HTML5（Living Standard）の仕様に従っている
• HTML全体ではなく、部分的にアウトライン化可能
• アンカーリンクを自動生成

ポイントは、見出しレベル（h1, h2, h3...）だけを判定にアウトライン化するのではなく、（Living Standard）の仕様に従っているのでHTML5のセクショニングコンテンツによるアウトラインにも対応しています。

例

<h1>様々なCMS</h1>
<section>
 <h1>オープンソースCMS</h1>
 <section>
  <h1>WordPress</h1>
  <p></p>
 </section>
 <section>
  <h1>Drupal</h1>
  <p></p>
 </section>
<h1>プロプライエタリCMS</h1>
 <section>
  <h1>Movable Type</h1>
  <p></p>
 </section>
 <section>
  <h1>a-blog cms</h1>
  <p></p>
 </section>
</section>

インストール方法

このライブラリでは３パターンの方法で、インストールできるようにしています。環境にあったインストール方法をお選びください。

スタンドアローン

cdn経由

<script src="https://unpkg.com/document-outliner@latest/bundle/document-outliner.js"></script>

もしくは、GitHubからダウンロードして、ご自身の環境に設置して読み込んでください。

npm経由

webpack や browserify などのバンドルツールをお使いの場合は、npm経由でもインストールできます。

インストール $ npm install document-outliner

インポート import DocumentOutliner from 'document-outliner';

jQuery

jQuery版も用意しています。こちらもスタンドアローンと同様、CDN経由かGitHubからダウンロードして設置して読み込みます。

cdn経由

<script src="https://unpkg.com/document-outliner@latest/bundle/jquery-document-outliner.js"></script>

使い方

スタンドアローン、npm経由の場合

スタンドアローン版の場合は、グローバルに 「DocumentOutliner」 という名前でエクスポートされていますので、これを利用します。npm経由の場合は、好きに変数名を決めれますが、使い方は、スタンドアローン版もnpm経由でも同じになります。

基本的な使い方

「DocumentOutliner」を new する時に、アウトラインしたい要素を指定します。指定方法は セレクター、HTMLElement で指定できます。 次に「makeList('アウトアインを出力する場所')」を使って、実際にアウトラインを表示します。

var outliner = new DocumentOutliner('.js-outline-src');
outliner.makeList('.js-outline-output');

オプションの指定

オプションなしでも動作しますが、より細かい制御をしたい場合はオプションが指定できるようになっています。例えば以下のコードは、アウトラインにリンクを生成しないようにしています。

var outliner = new DocumentOutliner('.js-outline-src');
outliner.makeList('.js-outline-output', {
  link: false
});

jQuery版の場合

基本的な使い方

jQuery版の場合は、アウトライン化したい要素のjQueryオブジェクトから、「documentOutliner()」を呼び出します。 「documentOutliner()」の第一引数には、アウトラインを出力する要素を指定します。

$(function () {
  $('.js-outline-src').documentOutliner('.js-outline-output');
});

オプションの指定

オプションの指定方法は、「documentOutliner()」の第２引数にオブジェクトで指定していきます。以下のコードでは、リンクをオフにし、リストタイプを ul に指定しています。

$(function () {
  $('.container').documentOutliner('.output', {
    link: false,
    listType: 'ul'
  });
});

オプション

以下のようなオプションがつけれるようになっています。

おわりに

というわけで、見出しを生成するためのライブラリの紹介でした。特にブログコンテンツなどでは重宝すると思いますので、ぜひご利用いただければと思います！ また次期マイナーバージョンの Ver. 2.10 に搭載予定ですので、お楽しみに！

今年も、25日間アドベントカレンダーを埋めることができて感謝感激です！また来年もどうぞよろしくお願いいたします！