RoomMirrorというnpmモジュールを作った
RoomMirrorとは
Markdownから生成したHTMLの中のコードブロックにCodeMirrorでシンタックスハイライトを行うために作ったもの。
この記事はドキュメントの内容に修正を加えつつまとめたものです。
インストール
Nodeがインストール済みで、npmが使える場合は、
npm install roommirror
npmが使えない場合は、
github: all-user/RoomMirror
からダウンロード。
使い方
共通の設定
codemirror.cssを読み込む。
パスは"RoomMirrorのルートフォルダ/node_modules/codemirror/lib"。
<link rel="stylesheet" href="codemirror/lib/codemirror.css">
使用するカラースキームのCSSも読み込む。
パスは"RoomMirrorのルートフォルダ/node_modules/codemirror/theme"。
<link rel="stylesheet" href="codemirror/theme/base16-dark.css"> <link rel="stylesheet" href="codemirror/theme/solarized.css"> <link rel="stylesheet" href="codemirror/theme/monokai.css">
はてなブログの場合は「設定」→「詳細設定」で、<head>内で読み込む物を追加出来るのでそこに記述すると簡単です。
ブラウザの場合
roommirror.jsを読み込む。
RoomMirrorのルートフォルダ/browserにあります。
<script src="browser/roommirror.js"></script>
あるいは、CodeMirrorを別で用意したりすでに定義済みの場合、
rm_without_cm.jsを読み込む。
<script src="path/to/codemirror.js"></script> <script src="browser/rm_without_cm.js"></script>
使用したい言語のモードファイルを読み込む。
RoomMirrorのルートフォルダ/node_modules/codemirror/modeにあります。
<script src="codemirror/mode/htmlmixed/htmlmixed.js"></script> <script src="codemirror/mode/javascript/javascript.js"></script> <script src="codemirror/mode/css/css.js"></script>
Browserifyの場合
requireで読み込む。
var RoomMirror = require('roommirror');
// and mode files...
require('codemirror/mode/htmlmixed/htmlmixed.js');
require('codemirror/mode/javascript/javascript.js');
require('codemirror/mode/css/css.js');
RoomMirrorでのデフォルトのCodeMirrorオプション
シンタックスハイライトとして使う事をメインで考えていたので以下の設定がデフォルトで有効になっています。
{
readOnly : true,
viewportMargin: Infinity
}
プロパティ
RoomMirror.preset
コードブロックの共通のCodeMirrorオプションを指定する。
デフォルトの設定とマージされた後CodeMirrorに渡される。
RoomMirror.preset = {
mode : 'javascript',
theme: 'monokai'
};
シンタックスハイライトとして使う場合は言語とカラースキームの指定程度で大丈夫、
以下に挙げるのはRoomMirrorで使えそうなCodeMirrorの主なオブション。
他にもCodeMirrorのConfigurationを参照されたい。
readOnly =
true: boolean
コードブロックを編集可能にしたい場合はfalseに指定。
falseを指定することでエディタブルにすることも可能。viewportMargin =
Infinity: integer
コードブロックの高さを行数で指定する。
この値をInfinityに設定し、CSSで.RoomMirror { height: auto; }を指定すると。
コードブロックの内容に応じて行数が調整される。
デフォルトではこの設定になっている。tabSize =
4: integer
タブのサイズを指定する。lineWrapping =
false: boolean
一行が長い時、はみ出た部分のコードを折り返すかどうかを指定する。
デフォルトではfalseに指定されており、はみ出た部分はスクロールで表示する。lineNumbers =
false: boolean
左側に行番号を表示するかどうかを指定する。firstLineNumber =
1: integer
lineNumbersをtrueに設定した時、行番号がいくつから始まるかを指定する。
デフォルトでは1になっている。lineNumberFormatter: (integer) -> string
lineNumbersをtrueに設定した際の行番号の表示フォーマットを指定する。
行番号を表す整数を受け取り、整形した文字列を返す関数を指定する。fixedGutter =
true: boolean
lineNumbers、lineWrappingがtrueに設定され水平スクロールが発生した際に、行番号がスクロールに追従するかどうかを指定する。
デフォルトではtrueに指定されており、コードブロックの左側に固定して表示される。
メソッド
RoomMirror(qs) -> [cm]
HTML内の任意の要素にCodeMirrorを使用したシンタックスハイライトを行う。
data-evalの文字列がevalで評価され、デフォルトの設定とマージされた後CodeMirrorに渡される。
html
<pre class="rm" data-eval="{ mode:'javascript' }"><code>
var test = 'test';
</code></pre>
var codeBlocks = RoomMirror('.rm');
RoomMirror.byAnnotation(qs) -> [cm]
HTML内の任意の要素をアノテーションとみなして、次に続く要素のシンタックスハイライトを行う。
data-evalの文字列がevalで評価され、デフォルトの設定とマージされた後CodeMirrorに渡される。
Markdownと組み合わせる場合はこのメソッドを使う。
html
<p class="rm-a" data-eval="{ mode:'javascript' }"></p>
<div>
var test = 'test';
</div>
var codeBlocks = RoomMirror.byAnnotation('.rm-a');
Markdownの例
markdown
<p class="rm-a" data-eval="{ mode:'javascript' }"></p>
var test = 'test';
var codeBlocks = RoomMirror.byAnnotation('.rm-a');
evaluable-tagとappend-css
RoomMirrorを作るのに先立って、evaluable-tagとappend-cssという二つのnpmモジュールを作りました。
evaluable-tag
タグの中のdata-eval属性の内容をJavaScriptとして実行するだけのモジュール。append-css
CSSルールを追加するだけのモジュール。
有名なライブラリを見ていると複数の小さいnpmモジュールを組み合わせて作られていたので、そういうアプローチを目指しました。
npmモジュール作りは初めてだったのでその練習も兼ねております。
ドキュメントは無理やり英語で書いたので恥ずかしいことになっていたら教えていだだけると幸いです。
npmモジュールの作り方・公開の仕方は下の記事を参考にしました。
evaluable-tagとappend-cssについても書くつもりです。
