【Pandoc拡張】はじめてのOSS公開？PandocのHTMLビルドを強化する拡張パックをリリースしました【mnmpep】

はじめて、OSS？を公開した話

この度、人生初のGitHub公開リポジトリとして、mnmpepをリリースしました。

Pandocが持つmarkdown→HTMLのビルド機能を利用して、迅速に実用的なWebドキュメントを作成するためのものです。
これ以上の詳細は、mnmpepがどのようなものかは、リポジトリのページ及び、当サイトにアップしたビルドサンプルに任せましょう。

特に、当サイトにアップしたサンプルはreadmeであると同時に、mnmpepを通して作成したHTMLドキュメントの実物サンプルです。
ここまでの説明で利用してみたいと思われた方は、サンプルに触れていただくのが一番、手っ取り早いでしょう。

今回はリリースの報告がてら、開発・公開経緯やその他四方山話を語るコラム的な記事となります。
個人ブログらしく？雑談多めなので、気軽にご覧下さいね。

これはOSS(オープンソースソフトウェア)なのか？

readmeを読むと気が付かれると思うのですが、mnmpepはアプリケーションとは異なります。

要は、Pandocのコマンドでビルドするときに引数で注入するファイル群がほとんどで、そこにさらに目次になるHTMLのテンプレを用意しているからそっちも編集してかぶせてね、というファイル群でしかありません。

そうすると、もちろんソースコードは公開しているしMITライセンスを宣言しているので、オープンソースにはなります。
で、プログラムかと言われると、実に微妙。

上記画像が、執筆時点でのmnmpepリポジトリの利用言語割合なんですが、92%はHTMLとCSS。
圧倒的な比率で非プログラミング言語優勢なわけです。

注入するファイル群の中には一応わずかにLuaも書いているし、関連HTMLにもほんのわずかながらJSを書いており、またmermaid.min.jsも利用してはいます。
ただ本質的にはそれらも含めて、Pandocのビルド機能に注入するファイル群、いわば料理に加える調味料みたいなもんなんですよ。¹

そう考えると、ソフトウェアですよーと声を大にしていっていいのかが微妙、という印象が拭えません。²
この記事にやたらクエスチョンが多いのは、この違和感のせいですね。

オープンソースだけど、ソフトウェアなのか…？
なわけです。
でも、「OSSを公開したんだぜ」って言ったほうがカッコいいし世間でも通りやすいので、一応OSS公開しましたって言っておきます。

奇妙な名前の由来

mnmpep、何のことだかわかりませんよね？
作者の私だって、変な名前にしたもんだと、改めて思っています。

mnmは、私の名前 MiNaMo の略称です。
西川貴教さんがTNNKなのと同じノリです。
なんか、畏れ多いことを書いてしまった気がする。

pepは、

• Pandoc
• Expansion(拡張)
• Pack(パック)

の略です。
ここ1～2年お世話になっているCopilotさんが、のちのちmnmpepとなるものをごちゃごちゃ相談している時に途中から、pep呼ばわりしだしたので採用しました。

ようは、PPAPみたいなノリでついた名前です。
またもや、畏れ多いことを書いてしまった気がする。

はじめてなんですよ

当サイトで公開しているMod Translatorは、オープンソースにはしていません。
また著書がらみでこのサイトでもコンテンツを公開しているOPFSジャック関連は、まだ公開レベルに至ってません。
公開レベルに至った時点で、OSSとするのかそうじゃないのかはまだ決めてもいません。

というわけで、オープンソースとして公開する、初めての作品がmnmpepとなるわけです。

開発経緯

業務上の問題点

仕事柄、WindowsServerを触ることが多いのですが。
そうすると、GUI操作はできるけれど普通、Officeソフトは入っていないわけです。
サーバー的には邪魔者の場合が多いですからね。

で、WordやExcelで資料が入っている場合、そのままでは読めないわけです。
LAN内のサーバーなんて、普段触らないサーバーなだけあって、決して人が作業しやすい場所になんておいていないことが大概。
なので、その資料を見ようと思うと物理的に離れた位置にあるクライアントPCを借りるとか、ものすごい狭い場所に無理矢理捩じ込んだ持参したノートPCとかでリモートデスクトップで入ったりしないと閲覧できない。
なんだったら、そこに書いてある文字列とかホントはコピペしたほうが作業が楽・精度が高いなことができない、もある。

こりゃいかんぞ、と。
はじめは、.txtで書けばいいのに、くらいに思っていたんですが、表現力不足は否めない。

Markdownとの出会い

そんなことを感じていた時期と前後して、自分自身モダンなWebの一つでも経験せねばならんという動機もあってこのサイト、みなもの研究室を立ち上げました。
この頃すでに、業務で携わったWordPressサイトの保守でそれなりに痛い目を見ていたので、ぜーったいにWordPressは使ってやんねぇ、違う選択肢を示せる人間になるぞ、みたいな妙な気概もありました(笑)³

色々調べた結果、「SSGでサイト作ってMarkdownでブログ更新するのがモダンらしい」という結論に至り、このサイトはGatsby.jsを採用しました。
ITエンジニアになって数年、ここではじめて、Markdownに触れます。
結構、衝撃的でした。

• こんなシンプルなルールに沿って書くだけで、ブログ記事の元になるんだ！？
• VSCodeみたいなコードエディタなら、プレーンテキストの状態で既に文書として文書構造まで把握しながら普通に読めるぞ！？

Gatsbyのビルド周りやちょっと手を加えるだけでReactReactな仕様には辟易しつつも、Markdownそのものにはガンガン傾倒していきます。
気がつけば、ちょっとしたメモ書きや、打ち合わせ中のリアルタイムに書く走り書きなど、瞬く間に、みなもの日常にMarkdownが侵食していました。

そして、Pandocへ・・・

ですが、このブログと違って、手元で作ったMarkdownを他人が見やすいようにする手段がありませんでした。
受託開発したアプリなどのヘルプも、Markdownで書いたほうが速いくらいだというのに。
ちなみに私は、あっという間にメモ帳で開いた素のMarkdownでも読めるようになっていました(笑)

Markdownをローカルで見れる形で、HTMLとかWordあたりに変換してくれるものが何かないか

そう考えて探し出したのが、Pandocでした。
コマンドひとつでHTMLやWordにビルドしてくれるのはありがたかったです。

が。

成果物がとても、もさい

そう、HTMLにせよWordにせよ、ビルド結果をそのまま開くと、すんげー、もさいんです。
HTMLなんて、変に色付けてないだけましですが黎明期のインターネットサイト感まで漂ってます。
インターネット老人会に提出すれば喜ばれるやつですね。

HTMLについては割と早くから対策ができました。
GitHub風にするCSSを探し出して、それをコマンドで注入するすべを覚えたんです。⁴

おかげで、WindowsServerにも必ず積んである、Webブラウザで見れるドキュメントを作る手段が出来上がったわけです。

カスタマイズの沼にハマる

さて、そうなってくると気になりだすのが、とりあえず採用したCSSへの不満です。
いや、利用させていただいて有り難いのにおこがましいのですが。

• 現代的に見やすく本文部分を真ん中に寄せて幅を絞っているからこそ気になる、その幅に合わせた画像じゃないと詳細が見えづらい問題。
• 脚注をクリックするたびに一番下までスクロールさせられ、脚注と本文を並べてみれないフラストレーション。
• フラットすぎて見出しなどが分かりづらく、メリハリがない構成。
• 複数ページに渡るドキュメントのリンクを本文内に入れ込むしかないので、多数のドキュメントを俯瞰する構造が難しい点。

ただし、Pandocの素晴らしい点は、ビルドするときにCSSをリンクとして指定させられる点です。
つまり、上記の問題の大半は、CSSをどうにかすればどうにかなるんじゃね！？と思えた点だったんです。

というわけで・・・ ビルドしたページをナビゲーションするためのHTML用意すればいいじゃんとか、いろんな気づきを経ながら気がつけば2～3年。

自分好みの青ベースの、こんなレイアウトが出来上がってました。

知ってるよ、私！
こういうのを魔改造っていうんでしょ？

公開しようと思ったのは

作った業務システムマニュアルをLAN内の共有フォルダに置いて、目次用ページへのショートカットをクライアントPCのデスクトップに張り付けるなどの暴挙も当たり前にこなすようになった昨今。
今度作るドキュメントには、フローチャートなどの図表が必要になってきました。
別にPowerPointなどで作って画像出力をしてもよかったのですが、せっかくMarkdownを覚えたのだからと、mermaidに手を出し始めます。
そして、それを図にした状態でPandocに埋め込む術を導入しだしたあたりで、前々から感じていたことが確信に近づきました。

私が用意した注入ファイル一式を入れたフォルダ⁵と目次用HTML、あとはやり方さえ提供すれば、だれでもPandocでこのクオリティ出せるよね⁶

ということで、Pandocユーザーもしくは使ってみたいけど二の足を踏んでいる方への力になれると思ったんです。

あと、いい加減私のポートフォリオとなるものを作らねば、という思いもありました。
なんせ、mnmpepは

• JSも制限されてりゃ⁷、限定されたHTML構造という縛り⁸の中で、大概の問題をCSSだけでどうにかした集大成

ですからね。
バニラWebへのスキル証明としては、それなりの水準だとみてもらえるんじゃないでしょうか。⁹

後はできれば今後、これを足掛かりにGitHubSponsorsの申請を通して、収益化も少し狙いたいところですね。

せっかくなので

というわけで公開されたmnmpep、もともと私が必要としていた

• LAN内やサーバー内などの限定的な環境で見る、それも特定ソフトに依存しない¹⁰ドキュメントの作成

の他にも、サンプルページのように

• Webサイト内に公開するマニュアルやリファレンスなどのドキュメント群をまとめて作成・公開する

といった用途でも利用しやすいものとなっています。
サンプルページも結局、GitHub用に用意したreadme.mdを(サンプルにするために)複数ファイルに内容を分割して、それぞれmnmpep仕様でビルドして、目次HTMLを添えて公開して、目次用HTMLにアクセスしてもらってるだけですからね。
Markdownを書く手間は仕方がないですが、あとは

• Pandocのインストールと
• mnmpep導入(ダウンロードしたフォルダとファイルをコピペ)
• 目次HTMLを編集(これはちょっとHTML慣れが必要かも)
• テンプレ通りのコマンドを叩けば

このクオリティのドキュメントが完成ですから。
現代なら大抵のパソコンで目次用HTMLを読めばもう、そのドキュメントは一冊として読めます。
Webサイトにも、ただの静的なページなのでツルッとそのままアップしても大丈夫。
私みたいなフレームワークに縛られたサイトでも、内部で書いているのが相対リンクなら割と何とかなります。¹¹

ぜひぜひ、利用してみて下さいね。