はじめに
こんにちは。ネクストビートでテクノロジーエヴァンジェリストをやっている水島です。最近は社外向け技術イベントの企画・運営や社内向けドキュメントの整備などの業務が多くなっている今日この頃ですが、その中で静的サイトジェネレータdocsifyを使っていてハマったところがあるので共有したいと思います。
起こった問題
元々、社内向けのScala関係ドキュメントをhonkitで執筆していたのですが、ページナビゲーションで不便があり、docsifyに移行することにしました。移行自体はVSCode + Cline（Gemini 2.5 Pro Exp）を使うことで十数分くらいで完了できたのですが、一つ問題がありました。
honkitで作っていたドキュメントは以下のようにシンタックスハイライトされていました。
def add(x: Int, y: Int): Int = x + y
しかし、docsify移行後は以下のように生の状態でコードが表示されるようになってしまったのです。
試行錯誤
docsifyのドキュメントを眺めてみると、そこには以下のような記述がありました：
Support for additional languages is available by loading the Prism grammar files:
!> Prism grammar files must be loaded after Docsify.
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-docker.min.js"></script>
...
どうやらdocsifyはシンタックスハイライティングにPrismを使っていて、標準でサポートされている言語以外は上記のようにCDNで配信されている各言語用の.jsファイルを<script></script>で囲めばいいようです。
というわけで、docsifyのindex.htmlに以下のような記述を追加してみました。
...
<script src="//cdn.jsdelivr.net/npm/prismjs@1.30.0/components/prism-scala.min.js"></script>
これでScalaのコードがハイライトされるかと思いきや結果は変わらず。
原因究明
一体なぜだろうと思い、minifyされる前のコードを読んでみるとそこには以下のような記述がありました。
Prism.languages.scala = Prism.languages.extend('java', {
'triple-quoted-string': {
pattern: /"""[\s\S]*?"""/,
greedy: true,
alias: 'string'
},
'string': {
pattern: /("|')(?:\\.|(?!\1)[^\\\r\n])*\1/,
greedy: true
},
Prism.languages.extend('java'まで見たところで「あ。つまり、Java用のファイルを拡張してるのだな」と思いあたったため、以下のようにJava用のファイルを追加してみました。
...
<script src="//cdn.jsdelivr.net/npm/prismjs@1.30.0/components/prism-java.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.30.0/components/prism-scala.min.js"></script>
すると、無事、以下のように表示されました。
教訓
OSSに限らずですが、ドキュメントに全ての注意事項が網羅されているとは限りません。挙動がドキュメントと矛盾しているように見えるとき、最後にはやはりソースコードを見に行く必要がしばしばあるものです。
最近、ソースコードを書く機会が減っていたので、そんな当たり前のことを忘れていましたが、久しぶりにそんな気分を思い出すことができました。
皆様も、ドキュメントに書いてあるのにどうもおかしいな……という時は必要に応じてソースコードを参照してみてくださいませ。
Discussion