Markdownの構文がバラバラ問題、整形ツールを自作してみた

この記事について

前回の記事（Vol.27）では、Windowsのメモ帳がMarkdownに対応したことを紹介しました。
しかし、その中で明らかになったのが、「メモ帳でMarkdownファイルを開くと、勝手に中身が書き換えられてしまう」という衝撃の仕様です。

というわけで──
今回はその 壊されたMarkdownファイルを修復するためのツール を自作してみました。
どうせなら、Markdownの記法を統一するための小さなツールとして仕立ててみました。

GitHubにも公開しています👇
👉 https://github.com/Shachi-lab/md-formatter

🎀 “Markdownを勝手に書き換えるな！”って気持ち、すっごく分かるよ〜！

Markdownの“ゆれ”って何？

Markdownの記法には、仕様として明確な部分と、実は自由度が高い部分があります。そのせいで、書き手によって表現がばらついたり、ツールによって処理が変わったりすることがよくあります。

たとえば──

• 強調記法： <strong>bold</strong> と __bold__、どっち派？
• イタリック： *italic* と _italic_ の違い、気になる？
• リスト記号： *、-、+ は見た目に差があるけど、処理的には同じ
• 水平線： --- でも *** でも ___ でもOK。でもツールによっては一部しか表示されない
• エスケープ文字： \_, \[, \* などが多いと、読みづらいし処理も複雑に

こうした“揺れ”をそのまま放置していると──

• プレビューでの見た目が意図と違ってしまったり
• diffで履歴が見にくくなったり
• チーム内で「どっちで書くのが正解？」という地味な混乱が起きたり

複数人でMarkdownを扱ってると、表現がバラバラになっていくことって、よくあります。
自分だけならまだいいんですが、ツールやアプリが自動で書き換えてしまうと、Gitの差分がぐちゃぐちゃになることも…。

🎀 “自由に書ける”って便利だけど、それが逆にトラブルの元になることもあるんだよね〜

ならば作ろう、自分だけの整形ツール！

既存のツールもいくつか見つけたんですが──
正規表現の勉強ついでに自作してみたかったというのもあって、
普段はC言語がメインの自分ですが、今回はPythonを勉強しながらMarkdown整形ツールを作ってみました。

ファイル名は md-formatter.py
名前の通り、Markdownをフォーマット（整形）してくれるCLIツールです。

🎀 実用性もあるし、プログラミングの練習にもなるし、いちばん良いやつだね〜！

主な機能

✅ Markdown記法の記号を統一できる

以下の記法を、好きな記号に揃えることができます：

• 太字（**, __, --）
• 斜体（*, _, -）
• 水平線（---, ***, ___）
• リスト（*, -, +）

✅ コードブロックはそのまま

```python
print("Hello, world!")
```

のようなコードブロックは整形の対象から除外され、内容は一切変更されません。

✅ メモ帳が勝手に入れた空行を削除

リストの途中に勝手に空行が入ってしまう現象を検出して削除します。

✅ エスケープ文字の削除（オプション）

Markdownでは \* のようなエスケープ記号が挿入されることがあります。
これを一括で削除できます（もちろん削除しない設定も可能）。

コマンドの使い方

基本の使い方

python md-formatter.py input.md > output.md

オプション一覧

カスタマイズ例

python md-formatter.py --bold _ --italic - --list + input.md > output.md

python md-formatter.py --no-del-escape --no-fix-list input.md > output.md

コード解説（ちょっとだけ）

Markdownの記法を変換するには、正規表現が便利です。
処理の中心は、Pythonの正規表現（reモジュール）を使っています。
初心者なりに工夫したポイントをいくつか紹介します。

たとえば、太字を統一するには以下のような処理をしています：

line = re.sub(r'(?P<marker>\*\*|__)(?P<text>.*?)(?P=marker)',
              lambda m: args.bold * 2 + m.group('text') + args.bold * 2,
              line)

🎀 正規表現って最初は難しいけど、慣れてくると“ちょっとした魔法”みたいな感じになるよねっ

argparseってどんな仕組み？

引数の取り扱いでは、Python標準のargparseというモジュールを使用しています。
これだけで、簡単に引数の解析とヘルプがつけられます：

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--bold', choices=['*', '-', '_'], default='*')
args = parser.parse_args()

例えば --bold _ を指定すると、args.bold == '_' になります。
オプションの制限（choices）や、フラグの有無（action='store_true'）も指定できます。

C言語でCLIを作った時は、引数の取り扱いってかなり面倒な処理だったけど、Pythonのこのモジュールを知ったときはあまりの簡単さにびっくりしました。

🎀 （Pythonのargparse、あまりに便利すぎて他の言語にも欲しくなっちゃう…）

どんな人におすすめ？

• Markdownをよく使う人
• Gitで差分をキレイにしたい人
• メモ帳で壊れたmdを修復したい人
• 記法を統一したいけどVSCode拡張は使いたくない人
• 正規表現やPythonの練習をしたい人

おわりに

Markdownって、「書いたとおりに表示される」のが魅力なんですよね。
でも最近は、メモ帳みたいに勝手にいじってくるアプリも増えてきて、ちょっと怖くなってきました。

そんなときに、自分で整形できるツールがあると安心。
まだ機能は少ないけど、必要なら少しずつ増やしていくつもりです。

Pythonは普段あまり使わないけど、こういう“ちょい便利”なスクリプトをサッと書けるのは強みかもしれないですね。

少しでも参考になればうれしいです。

🎀 “Markdownが壊されるのがイヤだ！”って気持ち、わたしも全力で共感しちゃうよ〜！

💡 GitHubはこちら 👉 Shachi-lab/md-formatter

📪 お問い合わせなど

技術的なご相談やご質問などありましたら、
📩お問い合わせフォーム 　
または、
📮info@shachi-lab.com までお気軽にどうぞ。

🎀 記事の感想や質問、お待ちしてま〜す！

🔗 関連リンク

しゃちらぼの最新情報や開発の様子は、こちらでも発信しています：

• 🌐しゃちらぼ公式サイト
• 🐦 X（旧Twitter）：@shachi_lab
• 📗 Qiita：@shachi-lab
• 🐙 GitHub：@shachi-lab
• 📸 Instagram：@shachi_lab