メモを揉め

お勉強の覚書。

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の主なオブション。

他にもCodeMirrorConfigurationを参照されたい。

  • 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
    lineNumberstrueに設定した時、行番号がいくつから始まるかを指定する。
    デフォルトでは1になっている。

  • lineNumberFormatter: (integer) -> string
    lineNumberstrueに設定した際の行番号の表示フォーマットを指定する。
    行番号を表す整数を受け取り、整形した文字列を返す関数を指定する。

  • fixedGutter = true: boolean
    lineNumberslineWrappingtrueに設定され水平スクロールが発生した際に、行番号がスクロールに追従するかどうかを指定する。
    デフォルトではtrueに指定されており、コードブロックの左側に固定して表示される。

メソッド

RoomMirror(qs) -> [cm]

HTML内の任意の要素にCodeMirrorを使用したシンタックスハイライトを行う。
data-evalの文字列がevalで評価され、デフォルトの設定とマージされた後CodeMirrorに渡される。

html

<pre class="rm" data-eval="{ mode:'javascript' }"><code>
    var test = 'test';
</code></pre>

javascript

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>

javascript

var codeBlocks = RoomMirror.byAnnotation('.rm-a');

Markdownの例

markdown

<p class="rm-a" data-eval="{ mode:'javascript' }"></p>

    var test = 'test';

javascript

var codeBlocks = RoomMirror.byAnnotation('.rm-a');

evaluable-tagとappend-css

RoomMirrorを作るのに先立って、evaluable-tagappend-cssという二つのnpmモジュールを作りました。

  • evaluable-tag
    タグの中のdata-eval属性の内容をJavaScriptとして実行するだけのモジュール。

  • append-css
    CSSルールを追加するだけのモジュール。

有名なライブラリを見ていると複数の小さいnpmモジュールを組み合わせて作られていたので、そういうアプローチを目指しました。
npmモジュール作りは初めてだったのでその練習も兼ねております。
ドキュメントは無理やり英語で書いたので恥ずかしいことになっていたら教えていだだけると幸いです。

npmモジュールの作り方・公開の仕方は下の記事を参考にしました。

evaluable-tagappend-cssについても書くつもりです。