Markhor_Engineの使い方

Markhor_Engine documentation

Markhor_Engineは、Markdownで書かれた文章をHTMLに変換するJSプラグインです。
ほかのライブラリには依存せず、ブラウザでもNode.jsでも使えます。
IE 5.5以上、Chrome 1以上、Safari 1以上、Firefox 1以上で動作します。

導入

<script type="text/javascript" src="https://ohiro.ndjp.net/js/markhor_engine.js"></script>を、
<head>か<body>のどこかしらに記述しておいてください。

Node.jsで使うときは、ダウンロードしたファイルをrequireで読み込みます。
var Markhor = require('./markhor_engine.js');

使用

Markhor.render(Markdownの文字列, 設定)を呼ぶと、変換後のHTML文字列が返ってきます。
設定は省略できます(詳しくは「設定」をご覧ください)。
nullやundefinedを渡したときは、空の文字列が返ります。

例

<textarea id="src"></textarea>
<div id="out"></div>

<script type="text/javascript">
  document.getElementById('src').onkeyup = function () {
    document.getElementById('out').innerHTML = Markhor.render(this.value);
  };
</script>

下のテキストボックスに書くと、その下に変換結果が出ます。

## Markhorデモ **太字**、*斜体*、~~打ち消し~~、`code`が使えます。 - ばなな - ばはま - ぱなま | 名前 | 面積 | |---|---| | ばなな | 150 cm² | | ばはま | 1.4万km² | | ぱなま | 7.5万km² | [バナナ - Wikipedia](https://ja.wikipedia.org/wiki/バナナ)

使える記法

補足
・続けて書いた行は1つの<p>にまとまり、行の区切りは改行文字になります(画面上は空白と同じ)。引用の>のない続きの行も、同じ段落になります。
・リストの項目の間に空行があると、各項目が<p>で囲まれます。別のリストに分けたいときは、記号を変えるか(-の次は*など)、番号つきなら区切りの文字を変えて(.と))ください。
・リストの項目の中に、字下げした段落、コードブロック、引用、入れ子のリストを書けます。入れ子の<ul>や<ol>は、<li>の中に出力されます。
・表の寄せ指定は、<th>と<td>のalign属性になります。表のセルの中で使えるのはインライン記法(太字やリンクなど)だけです。
・リンクと画像は、URLの後ろに空白を空けて"title"と書くと、title属性がつきます。titleの中では、太字などの記法は変換されず、そのまま表示されます。titleが空のときは、つきません。
・画像のaltには、代替テキストから太字などの記号を除いた文字だけが入ります。
・リンクと画像のURLは、日本語や空白などが%E3...のようにパーセントエンコードされ、&は&になって出力されます(すでにある%XXはそのままです)。
・コードブロックの言語名は、開始行の最初の単語がそのまま使われます。コードブロックが閉じられていないときは、文章の最後(囲んでいる引用やリストの終わり)で閉じられます。
・コードブロックの言語名は、class="language-言語名"になるほか、ラベル用の<span>として出力されます。ラベルの見た目は、CSSで指定してください。表示する文字はcodeLangLabelで変えられます。
・引用とリストの入れ子は、合わせて255段までです。それより深いものは、文字として表示されます。極端に入り組んだ文章で処理が続けられないときは、全体が<pre>に入った文字として返ります。

出力されるクラス

設定

第2引数に、次のような項目をもつオブジェクトを渡します。すべて省略できます。

var html = Markhor.render(text, {
  linkTarget: '',
  linkRel: 'noopener noreferrer',
  allowImages: false
});

URLの検査

リンクと画像のURLは、変換のときに検査されます。許可されなかったリンクは文字だけ、画像は代替テキストだけになります。

http https ftp mailto tel…リンクで使えます
http https ftp、およびdata:image/のpng jpeg gif webp bmp…画像で使えます
スキームのない相対URL(/a/b、#topなど)…どちらでも使えます
javascript:など、上にないもの…使えません(:や空白を混ぜて隠したものも検出します)

urlFilterは、function (url, kind, ok)という形で書きます。
url…元のURLです(&なども書いたままの、エスケープ前のものです)。
kind…リンクなら"link"、画像なら"image"です。
ok…標準の検査で許可されたかどうか(trueかfalse)です。

戻り値によって、次のように動きます。
false…使わない
文字列…そのURLに置き換える(置き換えたURLには標準の検査が行われません)
true…使う(標準の検査で許可されなくても使うので、javascript:も通ってしまいます)
それ以外(undefinedなど)…標準の検査のとおりにする

例(画像は自分のサイトのものだけ許可する)

Markhor.render(text, {
  urlFilter: function (url, kind, ok) {
    if (kind === 'image' && url.indexOf('https://ohiro.ndjp.net/') !== 0) {
      return false;
    }
    return ok;
  }
});

そのほかの機能

Markhor.version…バージョンの文字列("1.3.0"など)です。
Markhor.escapeHtml(文字列)…& < > "をエスケープした文字列を返します。
Markhor.isSafeUrl(URL, 種類, 設定)…そのURLが許可されるかどうかをtrueかfalseで返します。種類は"link"か"image"で、設定にはrenderと同じものを渡せます。

以前のバージョンの動作(1.3系)

1.3系では、CommonMarkの仕様とは違う動作がいくつかありました。
1.4系で、CommonMarkの仕様に合わせました。

文章の組み立て

文字の記法