i-Vinci TechBlog
株式会社i-Vinciの技術ブログ

MarkdownViewerに翻弄された話

皆さんこんにちは。推し OS は Ubuntu な i-Vinci の下位です。
昔社内でアンチ ○ac、○indows とか噂されたことがありますが、そんなことないです。
嫌いな OS はありません。多分。

さて、本日は Markdown の作成でやらかした案件についてご紹介します。
当時の状況をダイ(DIE)ジェスト形式でお楽しみくださいませ。

いきなり結論

文書構造が破壊された Markdown を社内リポジトリにアップロードしました。
更に PullRequest 発信のおまけ付きです。

当然ですが、レビュアーからの指摘も頂きました。
穴があったら入りたいですね。

Markdown 環境構築時の話

最初に Markdown の記述にあたって、環境構築が必要だと考えました。
必要と考えたのが下記の要素です。

尚、VisualStudioCode を利用すればこれらの要素は一瞬で揃います。

  • シンタックスハイライト
  • ライブプレビュー

シンタックスハイライトの準備

調査をしていたところ、既に先駆者がいらっしゃったので参考にさせて頂きました。
(参考:markdown-mode で"GitHub Flavored Markdown"を実現する)

どうやら[commonmarker]を利用すれば、GitHub とほぼ同等のイメージが取得できるようです。

# ライブラリ導入
gem install github-markup commonmarker

ライブプレビューの準備

ブラウザ確認が入る以上、ライブプレビュー機能は必須です。
幸いにも素敵なライブラリを見つけることができました。

markdown-preview-mode

これで上述のシンタックスハイライトと組み合わせれば、Markdown の記述が始められそうです。

いざ実演

これは当時利用したソースの断片です。
以下の要素が内包されていれば想定通りです。
それでは Let's Challenge!!

  • 想定結果
    • 見開きの展開
    • ソースコードのインデント表示
    • 画像の表示
<details>
<summary>やらかしたコードのサンプル</summary>
<pre>
<code>

    Dim fs : Set fs = CreateObject("Scripting.FileSystemObject")

</code>
</pre>
</details>

<details>
<summary>やらかした画像のサンプル</summary>
![イメージ@1](./image_1.jpg)
</details>

実際の表示内容はこちらです。

開発環境イメージ

開発環境

なん...だと...

見開きは消滅し、インデントは働かず、画像に至っては代替テキストすら出力されていません。
これは酷い。

Markdown コンバーターを変更してみる

一旦、[commonmarker]から離れ、別の Markdown コンバーターを試すことにしました。
注目したのは[github-markdown]です。

gem uninstall commonmarker
gem install github-markdown

そして実行結果。

開発環境リベンジ

開発環境リベンジ

いいですね。画像が表示されていないことを除けば大分改善しました。

そして私は画像の未出力に気づかず、第一の Push をしてしまうのでした...

リポジトリ上の悲劇

突然ですが、ご覧ください。
VisualStudioCode のプレビュー(GitHub とほぼ同等)です。

リポジトリ上のプレビュー(※再現)

リポジトリ上のプレビュー

画像は今更なので突っ込みませんが、ソースのインデントが再び崩れています。
なんでや!!

結局の原因

ローカルとリポジトリに相違が出たのは、描画の問題でしょう。
クロスブラウザ開発でもよくあることです。

但し、今回の事例はもっと根本的なところでした。
[Markdown]の不正構文です。

情報収集していたところ、先駆者様が既に解説されていました。
(参考:GitHub の Markdown で折りたたみ記法の中身を整形させる方法)

今回の事象は[summary]の直後に空行を入れることで解決しそうです。
ということで修正です。

 <details>
 <summary>やらかしたコードのサンプル</summary>
+
 <pre>
 <code>

     Dim fs : Set fs = CreateObject("Scripting.FileSystemObject")

 </code>
 </pre>
 </details>

 <details>
 <summary>やらかした画像のサンプル</summary>
+
 ![イメージ@1](./image_1.jpg)

 </details>
実行結果

VSコードプレビューリトライ

ソースコードのインデントは復活し、画像も表示されるようになりました。
そして無事、リポジトリへの Push を終えて作業を終了させました。

めでたし、めでたし。

今回の教訓

環境に自信がないのであれば、実績の多いものを使いましょう。
あと、Markdown 系は Push 後に必ず表示確認を行いましょう。

誤りに気づかぬまま、勢い余って PullRequest を投げてしまったら恥ずかしい思いをしますよ。
私のようにね!

最新記事