Slateでナビが機能しなくなった話

こんにちは、今年度から新卒で入社しました。株式会社ROBOT PAYMENTの片岡です。

現在、弊社のサービスを利用する開発者用のリファレンスをよりよくするため、Slateでリファレンス作成の検証を行っています。

今回は、リファレンス作成の検証中につまずいたこととして、Slateでナビが機能しなくなった原因と現在の解決策の2点をお話します。

前提

Slateは、ナビ・リファレンス・サンプルコードの3構成になります
- Slateのサンプル[^1]
Slateは、マークダウンを使用してリファレンスを作成します（GitHubのREADME.mdと同じものです）
「#」を付けてタイトルにした文は、ナビのリンクになります
- マークダウンで記載されたタイトル[^2] 　　
- ナビに表示されているタイトル[^3]

発端

前提でお話した通りに # の後にタイトルをつけてリファレンスを作成していたところ、

他のリファレンスとは異なるタイトルであるが、ナビが機能しない

と問題が出てきました。

Slateの仕様上、リファレンスのタイトルを全て日本語で書いている場合は、ナビが参照するタグの id はハッシュになります。そのため、同じタイトルにしてしまうとハッシュ値が同じになり、同じリファレンスを参照してしまうことになります。
しかし、今回のナビの動作不良はハッシュ値が同じになる事によるものではありませんでした。

原因

結論から言うと、日本語と英語を混ぜたタイトルにすると日本語が無視され、英語の id にする事が原因でした。

英語のみで構成されている場合

### Test <!-- <h3 id="test">Test</h3> となる -->

日本語のみで構成されている場合

### テスト <!-- <h3 id="jaf830pa9">テスト</h3> とハッシュになる -->

日本語と英語を混在させている場合

### テストURL <!-- <h3 id="url">テストURL</h3> となり「テスト」が無視される -->

これにより、マークダウン上では異なるタイトルを指定したつもりが、同じタイトルを付けた場合と同じ挙動になっていました。

日本語と英語を混在させ、異なるタイトルを指定している場合

### テスト１URL <!-- <h3 id="url">テスト１URL</h3> -->
### テスト２URL <!-- <h3 id="url">テスト２URL</h3> -->

解決策

現在、解決策としてXMLのように独自のタグを作成し、CSSで隠しています。

### <contents-id>test1-url</contents-id>テスト１URL <!-- <h3 id="test1-url">テスト１URL</h3> -->
### <contents-id>test2-url</contents-id>テスト２URL <!-- <h3 id="test2-url">テスト２URL</h3> -->

上記のマークダウンを見て、HTMLで用意されている div や span を使用して id になる部分を作成すればよいのでは？と考える方もいらっしゃるかもしれません。

なぜこの方法をとっているかと、div , span を使用して id になる部分を作成すると、ナビとリファレンスが正しく表示されないという問題があるからです。

div を使用して id を作成した場合

### <div class="contents-id">test1-url</div>テスト１URL
<!--
    <a href="#test1-url" class="toc-h3 toc-link" data-title="<div class="content-id">test1-url</a>
-->

上記のコードのように div の class のダブルクォーテーションにより、data-title の値が切られています。
これが原因で、この a タグ以降の要素はすべて div に囲われ、CSSにより表示されない現象が起きていました。また、ダブルクォーテーションをエスケープしたら、ビルド中にダブルクォーテーションを無視してくれないかと考え試してみたところ、ダメでした。

そのため、XMLのように独自のタグを作成し、CSSで隠すという解決策をとっています。
id を指定する際に、人の手で id を指定すると手間が多くなってしまうため、自動化するためのスクリプトで対策をしています。